Runtime filters and Parameter overrides
Runtime filters and Parameter overrides apply filters or Parameter values to a Liveboard or Answer by passing the filter or Parameter properties as query parameters in a Liveboard or visualization URL. You can also apply runtime filters in REST API requests when querying data from a Liveboard, Answer, or a visualization object. On embedded instances, you can use the Visual Embed SDK to apply filters to an embedded Liveboard or Answer, and update filters using events.
Runtime filters
Runtime filters apply filters to a Liveboard or Answer by passing the filter properties as query parameters in a Liveboard or visualization URL.
Supported data types for runtime filters
You can use runtime filters on these data types:
-
VARCHAR
-
BIGINT
-
INT
-
FLOAT
-
DOUBLE
-
BOOLEAN
-
DATE
-
DATE_TIME
-
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
Runtime filter operators
This list contains all the filter operators you can use with runtime filters. Note that these operators do not apply to runtime Parameter overrides.
Operator | Description | Number of Values |
---|---|---|
|
equals |
1 |
|
does not equal |
1 |
|
less than |
1 |
|
less than or equal to |
1 |
|
greater than |
1 |
|
greater than or equal to |
1 |
|
contains |
1 |
|
begins with |
1 |
|
ends with |
1 |
|
between inclusive of the higher value |
2 |
|
between inclusive of the lower value |
2 |
|
between inclusive |
2 |
|
between non-inclusive |
2 |
|
is included in this list of values |
multiple |
How to apply runtime filters
For information about how to apply runtime filters, see Runtime filters. For information about how to apply runtime filters in REST API v1 requests, see Apply runtime filters in REST API v1 requests.
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.
-
You can pass a maximum of 2000 characters in the URL using runtime filters.
-
The DATE and DATE_TIME data type must be specified as EPOCH time (Unix or POSIX time) in runtime filters.
-
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 in the URL parameters.
-
You cannot apply a runtime filter on a Liveboard or visualization built on tables whose schema includes a chasm trap.
The runtime Parameter override limitations do not apply to runtime filters.
Runtime Parameter overrides
Runtime Parameter overrides apply Parameter values to a Liveboard or Answer by passing the Parameter properties as query parameters in a Liveboard or visualization URL.
Supported data types for runtime Parameter overrides
You can use runtime Parameter overrides on these data types:
-
VARCHAR
-
BIGINT
(Stored internally as int64) -
DOUBLE
-
BOOLEAN
-
DATE
(Stored internally as int64. Must be epoch value.)
How to override Parameter values at runtime on a Liveboard or visualization
To change Parameter values in a Liveboard or visualization URL, use the following syntax in the URL. Place the runtime content directly after the ThoughtSpot host name and forward slash, or at the end of the URL.
?param1=<parameter-name>¶mVal1=<supported-parameter-value>¶m2=<parameter2-name>¶mVal2=<supported-parameter2-value>#
For example:
Liveboards
https://{ThoughtSpot-Host}/?param1=discount¶mVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a
https://{ThoughtSpot-Host}/#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a?param1=discount¶mVal1=0.25
Answers
https://{ThoughtSpot-Host}/?param1=discount¶mVal1=0.25#/saved-answer/923d2db9-d3f1-40bb-8836-b5fbd6727082
https://{ThoughtSpot-Host}/#/saved-answer/923d2db9-d3f1-40bb-8836-b5fbd6727082?param1=discount¶mVal1=0.25
Limitations of runtime Parameter overrides
-
You can pass a maximum of 2000 characters in the URL using runtime Parameter overrides.
-
Runtime Parameter overrides only work on Liveboards and Answers that already use Parameters.
-
The DATE data type must be specified as EPOCH time.
The runtime filter limitations do not apply to runtime Parameters overrides.