Tableau Server URL Parameterization and Limits

Background

This short set of material covers how Tableau Server Views can be invoked via URLs while passing values for filters along on the URL.

This capability is particularly useful when using the Tableau Server embedded views capability. Embedded views allow you to place a Tableau View inside any other web application you have – a portal, a wiki page, or any other web-based application. In these scenario’s, you may want the view to be displayed and have filters for the data be passed to it from other aspects of your web application.

Whether you embed the views, or just create links directly to the standard Tableau Server interface, the ability to pass filter values along with the URL to open the view is a powerful technique to provide a more customized experience for the person working with the view.

The basic URL pattern

The basic URL pattern to open views is:http://servername/views/workbook/sheet

The examples in the rest of the document will open a workbook named “Coffee Sales”, which was published with a sheet named “Sales Performance”. The base url for this document is:

http://servername/views/CoffeeSales/SalesPerformance

Spaces and many special characters are removed from workbook and sheet names, for example, the Tableau sample workbook named “Wow!” becomes just “Wow” in the URL, and a sheet named “Sales Attainment – By Geo” becomes “SalesAttainment-ByGeo”.

The best way to see the precise URL for a specific view is to simply open it from the Tableau Server and examine the URL in your browser.

The original view

This is the base view that we will use in all the rest of our examples. This view was built using the Sample Coffee Chain data, and has the structure:

Column Shelf: Market and SalesRow Shelf: Product Type, Type, and ProductColor Shelf: Profit

Your first filter!

To limit the view to just show the West, use the URL:http://servername/views/CoffeeSales/SalesPerformance?Market=West

Only the West is displayed, as we passed that value as a filter on our URL.

What about field names with spaces?

To limit the view to just show Espresso drinks, use the URL:http://servername/views/CoffeeSales/SalesPerformance?Product%20Type=Espresso

To use fields with spaces in the names, replace the space with a %20. This is the URL encoding value for a space.

It is a best practice to URL encode the entire string to ensure special characters are passed correctly.

Only Espresso drinks are displayed, as we passed that value as a filter on our URL.

And if I want to pass multiple values?

To pass multiple values to the filter, just separate the values with commas:http://servername/views/CoffeeSales/SalesPerformance?Product%20Type=Coffee,Espresso

Coffee & Espresso!

Just comma separate the values on the limit.

If my filter values have spaces in them?

To limit the view to just show Decaf Espresso and Caffe Latte, use the URL:http://servername/views/CoffeeSales/SalesPerformance?Product=Decaf%20Espresso,Caffe%20Latte

Same trick as with the field names, just replace the spaces with a %20.

Limits on multiple fields at a time

The basic pattern is to just string the parameters together on the URL, using & as the separator between fields=value pairs:http://servername/views/CoffeeSales/SalesPerformance?Product%20Type=Espresso&Market=East

Only Espresso drinks in the East are displayed, as we passed both filter values along on the URL.

Now it gets interesting…

To pass multiple values to multiple limits on one URL is where the syntax gets a bit more involved, but allows for tremendous flexibility in the resulting view you ask for.

The interesting way the filters work is when passing multiple values for a specific filter is that all other filters passed in need to have the same number of values specified. In essence, it is building a matrix of the “cells” you would like to see in the resulting view.

For example, if you want to see Coffee and Espresso sales in just the West, you would specify:

?Product%20Type=Coffee,Espresso&Market=West,West

Which is instructing the view to get coffee in the west and espresso in the west.Simply having Market=West will result in an error on the server and not return a view.

Lets look at the next example…

Multiple values, multiple limits

The power in this format is it allows you to request specific combinations of items to include in your view, for example, you may want Coffee in the West and Espresso in the East:http://servername/views/CoffeeSales/SalesPerformance?Product%20Type=Coffee,Espresso&Market=East,West

We didn’t get any data for Espresso in the East (or Coffee in the West), since we didn’t ask for it. The filter passing allows for very precise views to be returned.

The resulting view matches up the sequence of the values passed on each filter to specify the combinations of data desired, in this case the 1st value for Product Type is Coffee which is matched with the 1st value for Market which is East, and the 2nd values are matched for Espresso & West.

More on multiple values, multiple limits

To extend the prior example, if I want to retrieve Coffee and Espresso for both the East and the West, I would use the URL:http://servername/views/CoffeeSales/SalesPerformance?Product%20Type=Coffee,Coffee,Espresso,Espresso&Market=East,West,East,West

Adding limits on new fields

In all the examples so far we have set filters on items that are displayed in the view. No filter or quick filter is required to be pre-created by the original author; you can pass a filter value of any value.

You can even pass filters for items that are not included in the current view, and Tableau will automatically add that item to the level of detail and set the filter.

Extending our example, the database also has a State column in it, which was not included in the original view that we constructed. Passing State= as one of the filter values will add State to the Level of Detail and set the filter. The view will be restricted to just the state(s) specified.

Adding limits on new fields

Passing a filter for State, even though that field isn’t used in the view:http://servername/views/CoffeeSales/SalesPerformance?State=California,Wisconsin

Be careful when using this technique, as there won’t be any visual indicators in the view that the data has been limited, since the State field is never actually displayed on the page.

Date values

Two important points when working with dates. The first is that all date (and time) values passed on the filter need to match the Tableau default format, which is not necessarily the display format used in your view.

The Tableau internal format is: yyyy-mm-dd hh:mm:ss

Where the timepart uses a 24 hour clock, so 10:18 pm would be specified as 22:18:00, remember that many database actually store dates as datetime values, so you may need to include a time part to the value you provide on the filter.

The second thing to remember is that many databases store all date values as datetime fields, so you may need to pass a time value along with your date.

If you data is just a date field (with no time), the URL would look like:http://servername/views/CoffeeSales/SalesPerformance?Date=1999-07-01

If you have a database with datetime values, the URL would look like:http://servername/views/CoffeeSales/SalesPerformance?Date=1999-07-01%2022:18:00

Date values

In this example, we are asking for the display from our Coffee Sales/Sales Performance view to be filtered to only show data from July 1, 1999.

http://servername/views/CoffeeSales/SalesPerformance?Date=1999-07-01%2000%3A00%3A00

(the value is URL encoded, which converts the space to %20, and the colons in the timepart to %3A)

Selecting to View Underlying Data confirms this view only has values for the specific date we provided on the filter.

Multiple date values

To set the filter to specify multiple date values, just comma separate the list of values:

http://servername/views/CoffeeSales/SalesPerformance?Date=1999-07-01,1999-09-01,1999-10-01

What about measures?

All the examples up to this point have been setting filters on dimensions. You can also set filters on measures via the URL. All limit values are equality limits. There is no current support for greater than or less than, or shortcuts for ranges. If you have multiple values, just comma separate them.

http://servername/views/CoffeeSales/SalesPerformance?Profit=0,100,250