Tableau JavaScript API Help

Apply filters to display a subset of the data available for a view. You can either apply filters before a visualization has been loaded or after.

When you specify fields in a filter, you should use the caption as shown in the user interface, not the database field name. In some cases, Tableau Desktop renames fields after they've been dragged to a shelf. For example the Date field might be renamed to YEAR(Date) after being dragged to the rows shelf. In this case, you should use YEAR(Date) as the parameter. The exception is hierarchical filters, which use the full hierarchical name (for example, [Product].[All Product].[Espresso]). Captions can use the optional [] delimiters around names.

Apply Filters Before Loading the Visualization

To apply filters before a visualization has loaded, specify the filters as options during initialization. For example, if you have a filter named Container and you only want to view data for Boxes, then you might use the following code to initialize the visualization:

var containerDiv = document.getElementById("vizContainer"),
url = "http://YOUR-SERVER/views/YOUR-VIEW",
options = {
    "Container": "Boxes"
};

viz = new tableau.Viz(containerDiv, url, options);

Apply Filters After Loading the Visualization

Use the applyFilterAsync function to apply filters after your visualization has loaded. You can use the following code to filter a single value:

worksheet.applyFilterAsync("Container", "Boxes",
   tableau.FilterUpdateType.REPLACE);

There is a difference between querying existing filter state and setting new or existing filters. Querying filters is done via Worksheet.getFiltersAsync(), which returns a collection of Filter classes, or by using Dashboard.getFiltersAsync(), which returns a collection of Filter classes used in the dashboard. Setting filters is done via Worksheet.applyFilterAsync(and its variants) and and Dashboard.applyFilterAsync. These are function calls that don't require you to instantiate a Filter class.

Here are examples of several types of filtering:

var worksheet;

viz.getWorkbook().activateSheetAsync("Sheet 4").then(function (sheet) {
  worksheet = sheet;
})
// Single value
.then(function () {
  return worksheet.applyFilterAsync("Product Type", "Coffee",
    tableau.FilterUpdateType.REPLACE);
})
// Multiple values
.then(function () {
  return worksheet.applyFilterAsync(
    "Product Type", ["Coffee", "Tea"],
    tableau.FilterUpdateType.REPLACE);
})
// Multiple Values - adding and removing
.then(function () {
  return worksheet.applyFilterAsync("Product", ["Lemon", "Mint"],
    tableau.FilterUpdateType.ADD);
})
.then(function () {
  return worksheet.applyFilterAsync("Product", ["Caffe Latte", "Green Tea"],
    tableau.FilterUpdateType.REMOVE);
})
// All values
.then(function () {
  return worksheet.applyFilterAsync("Product Type", "",
    tableau.FilterUpdateType.ALL);
})
// Date Range
.then(function () {
  return worksheet.applyRangeFilterAsync("Date", {
    min: new Date(Date.UTC(2010, 3, 1)),
    max: new Date(Date.UTC(2010, 12, 31))
  });
})
// Clearing a Filter
.then(function () {
  return worksheet.clearFilterAsync("Date");
})
// Relative Date
.then(function () {
  return worksheet.applyRelativeDateFilterAsync("Date", {
    anchorDate: new Date(Date.UTC(2011, 5, 1)),
    periodType: tableau.PeriodType.YEAR,
    rangeType: tableau.DateRangeType.LASTN,
    rangeN: 1
  });
})
// Quantitative Filters
// SUM(Sales) > 2000 and SUM(Sales) < 4000
.then(function () {
  return worksheet.applyRangeFilterAsync("SUM(Sales)", {
    min: 2000,
    max: 4000
  });
})
// SUM(Sales) > 1000
.then(function () {
  return worksheet.applyRangeFilterAsync("SUM(Sales)", {
    min: 1000
  });
})
// SUM(Sales) < 1000, excluding null values
.then(function () {
  return worksheet.applyRangeFilterAsync("SUM(Sales)", {
    max: 1000,
    nullOption: tableauSoftware.NullOption.NON_NULL_VALUES
  });
})
// Hierarchical Filters - selecting all on a level
.then(function () {
  return worksheet.applyHierarchicalFilterAsync("[Product].[Product Categories]", {
    levels: [0, 1]
  }, tableau.FilterUpdateType.ADD);
}, function (err) { /* ignore errors */ })
// Hierarchical Filters - adding one item
.then(function () {
  return worksheet.applyHierarchicalFilterAsync(
    "[Product].[Product Categories].[Product Name]",
    "Accessories.Bike Racks.Hitch Rack - 4-Bike",
    tableau.FilterUpdateType.REPLACE);
}, function (err) { /* ignore errors */ })
// Hierarchical Filters - adding multiple items
.then(function () {
  return worksheet.applyHierarchicalFilterAsync(
  "[Product].[Product Categories].[Product Name]",
  [
    "Accessories.Bike Racks.Hitch Rack - 4-Bike",
    "Accessories.Bike Stands.All-Purpose Bike Stand"
  ],
  tableau.FilterUpdateType.REPLACE);
}, function (err) { /* ignore errors */ })
.otherwise(function (err) {
  console.log(err);
});