Using the Embedding API, you can apply filters to display a subset of the data available for the embedded Pulse metric. You can either apply filters before a Pulse metric has been loaded (at initialization) or after (interactively). You can also get and set the time dimension of the Pulse metric.
In this section
You can apply filters to the Tableau Pulse web component. These filters are applied when the Pulse metric first loads.
You can apply filters by adding <pulse-filter> elements to your <tableau-pulse> web component. This element is only supported in <tableau-pulse> web components. You can’t apply these filters to <tableau-viz> components.
The <pulse-filter> element has two attributes: the field and its value.
<pulse-filter field="name" value="value"> </pulse-filter>
The filter can contain multiple values, and you can add multiple <pulse-filter> elements to the <tableau-pulse> component.
Note that when a filter contains multiple values, the values should be comma-delimited (,) without spaces.
When you specify fields in a filter, you should use the caption as shown in the Tableau Pulse metric (user interface), not the database field name. The field names are case-sensitive.
Here’s example code that adds two filters to a <tableau-pulse> web component.
<!-- assumes you have included the Embedding API v3 library -->
<tableau-pulse id="tableauPulse"
src='https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838'
layout="default">
<pulse-filter field="Category" value="Technology"> </pulse-filter>
<pulse-filter field="State" value="California,Oregon,Washington"> </pulse-filter>
</tableau-pulse>
If you prefer to use JavaScript to embed your views, you can still apply filters during initialization by using the addFilter() method. To do this you add the filters on the TableauPulse object before you render the metric. For example, the following snippet applies two filters (Central, West) to the metric and then renders the metric by appending it to the HTML element that has the identifier, tableauPulse.
let url = 'https://online.tableau.com/pulse/site/mysite/metrics/3ec1437f-d40d-4a5d-9363-aa22cd862838';
// create the Pulse object
const pulse = new TableauPulse();
pulse.src = url;
// configure the Pulse metric...
// apply filters
pulse.addFilter('Region', 'Central,West');
// render the metric by appending it to "tableauPulse"
document.querySelector("#container").appendChild(pulse);
To apply filters after you have initialized and rendered the Pulse metric, use the applyFilterAsync or applyFiltersAsync methods, see Apply Pulse filters interactively (after initialization). If you use the addFilter() method after initialization, the view is re-rendered.
As an alternative to using the applyFilter() method, you could create a filter element and append that to the TableauPulse object directly before initialization. For example, the following snippet shows how you might apply a filter on the Region field so that it only shows the West.
// assumes a Pulse object has been created
const filter = document.createElement("pulse-filter");
filter.setAttribute("field", "Region");
filter.setAttribute("value", "West");
pulse.appendChild(filter);
// render the view by appending it to the "tableau-pulse" component
document.querySelector("#container").appendChild(pulse);
You can use the applyFilterAsync() and applyFiltersAsync methods to apply filters after Pulse metric has loaded. To do this, you first need to create a JavaScript object from the web component <tableau-pulse>. After you have the Pulse object, you can use the Embedding API methods to interact and filter the metric. For working with the methods for filters, be sure to import FilterUpdateType, FilterDomainType from the Embedding API library.
Use the applyFilterAsync() method to filter the Pulse metric based on a list of values for the specified filter. For example, the following code shows how you might filter a single value. In this case, the field is Ship Mode and the value is First Class. Note that the applyFilterAsync method requires an array of values, so you must include the brackets ([ ]) even if you are filtering on a single value.
When you call the applyFilterAsync() method, you also need to specify what action you want to take. You can either add a new filter, replace, or remove existing filters, or apply all filters. To specify the action, use the FilterUpdateType enumerations (FilterUpdateType.Replace, FilterUpdateType.Add, FilterUpdateType.Remove, FilterUpdateType.All).
As in the Filter dialog box in Tableau, you can also choose whether to include or exclude the specified filter values, by setting the filter option (isExcludeMode). If this option is not specified, the method only applies the filter values provided. Note that the applyFilterAsync, along with some other Pulse methods, is asynchronous and returns a promise. A recommended way to handle this promise is to call the method from an async function, using the await keyword. The following examples show this approach.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'applyFilter'
applyFilter.onclick = async () => {
const adjustedFilter = await pulse.applyFilterAsync('Ship Mode', ['First Class'], FilterUpdateType.Replace, {
isExcludeMode: false,
});
};
You can use the applyFiltersAsync() method to apply multiple filters to a Pulse metric after metric has loaded. To do this, you define the array of filters, including the filter values, the update type, and the optional exclude mode. Note that the filter values must be specified as an array of values, so you include the brackets ([ ]) even if you are filtering on a single value.
You define an array of filters, using the keyword filters, as shown in the following example. Each filter has the following parameters, fieldName, values, updateType, and options (isExcludeMode). You pass the array of filters to the applyFiltersAsync method.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'applyFilters'
applyFilters.onclick = async () => {
const filters = [
{
fieldName: 'Sub-Category',
values: ['Art', 'Phones'],
updateType: FilterUpdateType.Replace,
options: { isExcludeMode: false },
},
{
fieldName: 'Region',
values: ['North Asia'],
updateType: FilterUpdateType.Replace,
options: { isExcludeMode: false },
},
];
const adjustedFilters = await tableauPulse.applyFiltersAsync(filters);
console.log('adjustedFilters', adjustedFilters);
};
The Embedding API provides two methods for clearing filters.
To clear a single filter on a Pulse metric, use the clearFilterAsync method and specify the field name for the filter.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'clearFilter'
clearFilter.onclick = async () => {
const clearedFilter = await tableauPulse.clearFilterAsync('Sub-Category');
console.log('clearedFilter', clearedFilter);
};
To clear a multiple filters on a Pulse metric, use the clearFiltersAsync method and specify an array of field names.
Be sure to include the brackets ([ ]) around the list of filters.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'clearFilters'
clearFilters.onclick = async () => {
const clearedFilters = await tableauPulse.clearFiltersAsync(['Sub-Category', 'Region']);
console.log('clearedFilters', clearedFilters);
};
If you want to clear all filters, rather than a subset of filters,
use the clearAllFiltersAsync method.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'clearAllFilters'
clearAllFilters.onclick = async () => {
await tableauPulse.clearAllFiltersAsync();
};
The Embedding API provides a method you can use to retrieve the list of applied categorical filters on the Pulse metric. The getFiltersAsync method returns an array of Pulse filters (CategoricalPulseFilter).
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'getFilters'
getFilters.onclick = async () => {
const filters = await tableauPulse.getFiltersAsync();
console.log('filters', filters);
}
Note if you intend to call the getFiltersAsync() method in the context of a filter change event, see Adding an event listener for a PulseFiltersChanged event for some additional considerations.
You can use the CategoricalPulseFilter objects to get the applied values, the filter type, or the domain of a categorical filter.
To get the currently applied values for a filter, you can call the CategoricalPulseFilter.appliedValues property, which returns an array of filter values.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'getFilters'
getFilters.onclick = async () => {
const filters = await tableauPulse.getFiltersAsync();
console.log(`The number of filters: ${filters.length}
Filters: ${filters.map((s) => s.fieldName)}`);
console.log('filter[0] applied values', filters[0].appliedValues);
}
If you want to see all possible values for a given categorical Pulse filter, you can use the CategoricalPulseFilter.getDomainAsync() method.
Note that if you are familiar with the CategoricalFilter.getDomainAsync() method used for embedded Tableau views, the comparable method for Pulse filters works a little differently.
For a Tableau viz filter, the CategoricalFilter.getDomainAsync() method essentially returns all the field values chunked up into arrays of length 100, even if there are a million values.
For a Pulse filter, however, the getDomainAsync() method only returns 100 field values at a time, which is the default “page size” that Pulse uses. That is, the first call to getDomainAsync() returns first 100 values (1-100). The 2nd request returns the values 101-200, etc. The “page size” is configurable. However, the first call to getDomainAsync() can only return the first 100 values.
The Pulse getDomainAsync() method also returns the total number of available field values and a next page token, so you can customize the page size if there are more than 100 total. For example, say that there are 300 values. The first call of getDomainAsync() returns the first 100 values (1-100) out of the total available of 300. And the method also returns the next page token. If you set the page size to 200 and include the next page token in your next call of getDomainAsync(), you can return the values 101-300.
Note that the maximum number of field values that can be returned for a single field, even across multiple requests, is 1000. That is the limit even if the total number of available values is greater than 1000. For example, suppose that there are 1100 field values. The first request returns the first 100 values (1-100), out of the total available of 1100, and the next page token. If you call the method again and specify a page size of 1000, the second request returns the next 900 values (101-1000) and an empty next page token. The only way you can retrieve the field values numbered 1001-1100 is by providing a search term to getDomainAsync().
getFiltersAsync and getDomainAsyncThe following code example shows how you might extract the field values from the domains of two categorical filters.
The code shows an event handler for a ‘getFilters’ button click event.
It performs the following steps:
Retrieves all filters using tableauPulse.getFiltersAsync().
filters[0].getDomainAsync() and:
filters[1].getDomainAsync() and:
foo’ and logs the results.The event handler uses pagination to retrieve all domain values in chunks (pages) until all values are retrieved. The initial page size is 100 and the page size adjusted based upon the total values available.
// assumes a Pulse object has been created
// assumes there is a 'button' with the id 'getFilters'
getFilters.onclick = async () => {
const filters = await tableauPulse.getFiltersAsync();
console.log('filters', filters);
let domain = [];
let page = undefined;
let pageSize = 100;
do {
page = await filters[0].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Database);
domain = domain.concat(page.values);
console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
pageSize = page.totalAvailable - domain.length;
} while (page.nextPageToken);
console.log('domain (database)', domain);
domain = [];
page = undefined;
pageSize = 100;
do {
page = await filters[0].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
domain = domain.concat(page.values);
console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
pageSize = page.totalAvailable - domain.length;
} while (page.nextPageToken);
console.log('domain (relevant)', domain);
domain = [];
page = undefined;
pageSize = 100;
do {
page = await filters[1].getDomainAsync('', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
domain = domain.concat(page.values);
console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
pageSize = page.totalAvailable - domain.length;
} while (page.nextPageToken);
console.log('domain (relevant)', domain);
domain = [];
page = undefined;
pageSize = 100;
do {
page = await filters[1].getDomainAsync('foo', pageSize, page?.nextPageToken, FilterDomainType.Relevant);
domain = domain.concat(page.values);
console.log(`Retrieved ${domain.length} of ${page.totalAvailable} field values`);
pageSize = page.totalAvailable - domain.length;
} while (page.nextPageToken);
console.log('domain (foo)', domain);
};
You can use the Embedding API to get and set the time dimension for the Tableau Pulse. You can set the time dimension before initialization,
by using the time-dimension attribute on the <tableau-pulse> web component, or after initialization, by using the applyTimeDimensionAsync() method.
time-dimension) in the Pulse web componentYou can set time-dimension attribute to set the initial time dimension used during initialization when the metric first loads.
You can apply the following time dimensions:
LastMonth,
LastQuarter,
LastWeek,
LastYear,
MonthToDate,
QuarterToDate,
Today,
WeekToDate,
YearToDate,
Yesterday.
<tableau-pulse id="tableauPulse"
src="Pulse_URL"
time-dimension="MonthToDate">
</tableau-pulse>
applyTimeDimensionAsync)You can use the applyTimeDimensionAsync() method to set the time dimension for the Tableau Pulse metric. Be sure to import the PulseTimeDimension from the Embedding API library.
You can apply the following time dimensions:
PulseTimeDimension.LastMonth,
PulseTimeDimension.LastQuarter,
PulseTimeDimension.LastWeek,
PulseTimeDimension.LastYear,
PulseTimeDimension.MonthToDate,
PulseTimeDimension.QuarterToDate,
PulseTimeDimension.Today,
PulseTimeDimension.WeekToDate,
PulseTimeDimension.YearToDate,
PulseTimeDimension.Yesterday.
// assumes a Pulse object has been created
// assumes the applyTimeDimensionAsync() method is called from an `async` function
// import PulseTimeDimension from the Embedding API library
await tableauPulse.applyTimeDimensionAsync(PulseTimeDimension.LastQuarter);
getTimeDimensionAsync)You can use the getTimeDimensionAsync method to retrieve the currently applied time dimension.
// assumes a Pulse object has been created
// assumes the getTimeDimension() method is called from an `async` function
const timeDimension = await tableauPulse.getTimeDimensionAsync();
console.log('timeDimension', timeDimension);