About runtime filters

Runtime filters allow you to apply filters to the data returned by the APIs, or the visualizations and Liveboard you are embedding in another app.

Capabilities of runtime filters

Runtime filters provide the ability to apply filters on embedded objects at the time of retrieval. You can pass the filter criteria as URL query parameters on a Liveboard or its visualizations. ThoughtSpot supports applying runtime filters to objects embedded using the Visual Embed SDK and the REST APIs.

This example shows how to apply runtime filters when rendering a visualization or Liveboard using the Visual Embed SDK. Here, the RuntimeFilter is operating on the Revenue column and will return values equal to 100000.

      runtimeFilters: [{
      columnName: 'Revenue',
      operator: EQ,
      values: [100000]

This example shows the URL to access a Liveboard with a filter. Here the runtime filter is operating on the column Color and will only return values that are equal (EQ) to "red".


This example shows the URL for a REST API call with a runtime filter. Here the runtime filter is operating on the column Category and returning values that are equal to mfgr%2324.


ThoughtSpot will try to find a matching column from the Liveboard or visualization being accessed, using the col field as name. You can add any number of filter sets by incrementing the parameters (for example, col2, op2, and val2, etc.) For operators that support more than one value, you can pass val1=foo&val1=bar, etc.

If the Liveboard or Answer you’re filtering already has one or more filters applied, the Runtime Filter(s) will act as an AND condition. This means that the data returned must meet the conditions of all filters - those supplied in the runtime filter, and those included in the Liveboard or visualization itself.

Supported data types

You can use runtime filters on these data types:



  • INT




  • DATE


  • TIME

For the DATE and DATE_TIME data types, you must provide the date and time values in the Epoch time format. The Epoch time is also referred to as POSIX or Unix time. Epoch time is an integer value representing the number of seconds elapsed since 1 JAN 1970 00:00:00 UTC. You may have to convert time zones to calculate the appropriate timestamp.

For example, if you want to filter data for 2020-05-22, you can specify the date value in the Epoch time format as 1590192000, or use the following JavaScript method to calculate the timestamp:

new Date('2020-05-22').getTime() / 1000

Example Uses

You can use runtime filters alongside the REST API and Embedding to create dynamic controls in your Web portal. For example, you could use the REST API to get a list of possible filters for a visualization. Then use that data to populate a select list on your Web portal. When a user makes a selection, you would then pass it as a Runtime Filter, and the result returned will apply the filter.

Limitations of runtime filters

Runtime filters do not work directly on top of tables. You must create a Worksheet if you want to use runtime filters. This means that the Liveboard or visualization on which you apply a runtime filter must be created on top of a Worksheet.

If the Worksheet was created from an Answer (it is an aggregated Worksheet), runtime filters will only work if the Answer was formed using a single Worksheet. If the Answer from which the Worksheet was created includes raw tables or joins multiple Worksheets, you won’t be able to use runtime filters on it. This is because of the join path ambiguity that could result.

Runtime filters do not allow you to apply “having” filters using a URL.

You cannot apply a runtime filter on a Liveboard or visualization built on tables whose schema includes a chasm trap. See the ThoughtSpot Administrator Guide for details on chasm traps and how ThoughtSpot handles them.