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

EQ

equals

1

NE

does not equal

1

LT

less than

1

LE

less than or equal to

1

GT

greater than

1

GE

greater than or equal to

1

CONTAINS

contains

1

BEGINS_WITH

begins with

1

ENDS_WITH

ends with

1

BW_INC_MAX

between inclusive of the higher value

2

BW_INC_MIN

between inclusive of the lower value

2

BW_INC

between inclusive

2

BW

between non-inclusive

2

IN

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>&paramVal1=<supported-parameter-value>&param2=<parameter2-name>&paramVal2=<supported-parameter2-value>#

For example:

Liveboards

https://{ThoughtSpot-Host}/?param1=discount&paramVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a

https://{ThoughtSpot-Host}/#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a?param1=discount&paramVal1=0.25

Answers

https://{ThoughtSpot-Host}/?param1=discount&paramVal1=0.25#/saved-answer/923d2db9-d3f1-40bb-8836-b5fbd6727082

https://{ThoughtSpot-Host}/#/saved-answer/923d2db9-d3f1-40bb-8836-b5fbd6727082?param1=discount&paramVal1=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.