Runtime filters

With runtime filters, you can filter an answer or Liveboard through URL query parameters. Use this approach with the Data API, and with embedded answers and Liveboards.

Starting in May 2022, ThoughtSpot rebranded pinboards as Liveboards. For backward compatibility, we currently support internal processes and external methods that use the older naming convention.

Use runtime filters to filter data at the time of retrieval; see Data REST API.

Pinboard runtime filter

In this example, the Liveboard URL uses the runtime filter on the column Color, and returns values that are equal (EQ) to "red".

http://<thoughtspot_server>:<port>/?col1=Color&op1=EQ&val1=red#
/pinboard/e36ee65e-64be-436b-a29a-22d8998c4fae
REST API runtime filter

In this example, the URL for a Data REST API call uses a runtime filter on the column Category, and returns values that are equal to mfgr%2324.

http://<thoughtspot_server>:<port>/callosum/v1/tspublic/v1/pinboarddata?
id=e36ee65e-64be-436b-a29a-22d8998c4fae&col1=Category
&op1=EQ&val1=mfgr%2324

ThoughtSpot attempts to find a matching column in the Liveboard or visualization using the col field as name. You can add any number of filter sets by adding additional parameters for columns, operations, and values to the URL. For operators that support more than one value, pass val1=foo&val1=bar, and so on.

If the Liveboard or answer already has one or more filters, ThoughtSpot combines runtime filter(s) in an AND condition. This means that the returned data 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: VARCHAR, BIGINT, INT, FLOAT, DOUBLE, BOOLEAN, DATE, DATETIME, and TIME.

You must specify the date in epoch time (also known as POSIX or Unix time) for DATE and DATETIME values.

Best practices

You can use runtime filters with the Data REST API to create dynamic controls in your application. For example, you could use the Data REST API to get a list of possible filters for a visualization. Then use that data to populate a select list in your Web application. When a user selects an option, the application passes that option as a runtime filter. The resulting answer or Liveboard satisfies the conditions of 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 from a worksheet.

  • You can pass a maximum of 2000 characters in the URL using runtime filters.

  • When creating an aggregated worksheet from an answer, you can only use runtime filters if the answer was formed using a single worksheet. If the answer from which you create the worksheet includes raw tables or joins multiple worksheets, you cannot use runtime filters on it. This is to prevent join path ambiguity.

Runtime filters do not allow you to apply having filters using the URL.
Was this page helpful?
×