Runtime filters

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.

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

  • The DATE and DATE_TIME data types must be specified as EPOCH time (Unix or POSIX time) in runtime filters.

  • Runtime filters work only on Answers and Liveboard visualizations built from Worksheets. Runtime filters on visualizations and Answers built directly from Tables, Views, and SQL Views do not work because the possibility of multiple join paths and join path choice is not supported as input in runtime filters.

  • Runtime filters do not allow you to apply HAVING filters in the URL parameters.

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 Parameter overrides.