Runtime Parameter overrides

Table of Contents

Overview
- Supported data types
Apply Parameter overrides in Visual Embed SDK
- Adjust Parameter values using SDK events
- Show or hide Parameter chips in embedded sessions
Apply Parameter overrides via REST API
- REST API v2
- REST API v1
Apply runtime overrides via URL query parameters
Parameters and JWT tokens

Parameters in ThoughtSpot are typically used for "what-if" analysis, scenario planning, or to personalize data views without modifying the underlying data object. You can create Parameters in a Model and integrate them into formulas, filters, data queries, and Liveboards. You can also use Parameters within formulas when querying your data via Search, Liveboards, Answers, or Spotter sessions.

Overview🔗

Runtime parameters in ThoughtSpot are dynamic values that can be set or overridden at the time of accessing a Liveboard, Answer, visualization, or Spotter session.

Runtime parameters can be applied using one of the following options:

Via Visual Embed SDK
Use the runtimeParameters property in the Visual Embed SDK for embedded objects.
The SDK also provides host events to update Parameters.
Via RETS APIs
Use REST API requests to apply runtime overrides on Liveboard, Answer, or visualization data.
Via URL query parameters
Pass Parameter name and values as query parameters in the URL.

When applied, runtime parameters override the default or saved Parameter values for the user session or API call, and the changes are reflected in the resulting data and visualizations, but not saved to the object itself.

Supported data types🔗

You can apply runtime Parameters on the following data types:

VARCHAR
BIGINT
INT
FLOAT
DOUBLE
BOOLEAN
DATE
DATE_TIME
TIME

Important

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

Apply Parameter overrides in Visual Embed SDK🔗

The Visual Embed SDK supports runtime Parameter overrides on embedded Liveboards, Answers, and Spotter-generated answers. Before applying a Parameter override on any object, make sure the Parameters and associated formulas are configured in the data Model used for generating charts and tables.

The following examples show how to apply multiple runtime filters in the embed code:

const liveboardEmbed = new LiveboardEmbed('#tsEmbed', {
    ... // other embed view config
    liveboardId: '543619d6-0015-4667-b257-eff547d13a12',
    runtimeParameters:[{
        name: "Date List Param",
        value: 1662361200
    },
    {
        name: "Integer Range Param",
        value: 5
    }]
});

const spotterEmbed = new SpotterEmbed('#tsEmbed', {
    ... // other embed view config
    worksheetId: "cd252e5c-b552-49a8-821d-3eadaa049cca",
    searchOptions: {
        searchQuery: 'sales data for west coast',
    },
    runtimeParameters: [{
            name: "Date List Param",
            value: 1662361200
        },
        {
            name: "Integer Range Param",
            value: 5
        }
    ]
});

Note the following behavior in Spotter embedding:

Saving or pinning an answer does not retain the Parameter. Instead, only the Parameter value is stored.
In future releases, saved chats will also not retain the Parameter.
Users can see the Parameter value in formulas in edit mode, but only the value set for them will be visible.
Parameter values cannot be changed during a conversation session and may result in unintended effects.
If a user adds a Parameter to an answer through the edit flow, Spotter may drop this Parameter and any formulas using it in follow-up interactions. This means Parameters added in this way are not guaranteed to persist in subsequent conversational steps.

Adjust Parameter values using SDK events🔗

After loading the embedded object, Parameters can be adjusted using the HostEvent.UpdateParameters event:

liveboardEmbed.trigger(HostEvent.UpdateParameters, [{
        name: "Date List Param",
        value: 1656914873
    },
    {
        name: "Integer Range Param",
        value: 10
    }
])

Note	In Spotter embed, updating Parameters via host and embed events may not work.

Show or hide Parameter chips in embedded sessions🔗

Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from ThoughtSpot’s UI, while in other cases you may want to show the chips.

Hide Parameter chips🔗

To hide the parameter chip in ThoughtSpot’s UI, initialize a Parameter override before loading ThoughtSpot’s page by using one of the following methods:

Use the runtimeParameters option in ThoughtSpot’s Visual Embed SDK (Recommended)
Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK)

To update the parameter’s value once the page is loaded, use HostEvent.UpdateParameters. The Parameter chip will remain hidden, however its value in ThoughtSpot’s visualizations will be updated accordingly.

Show Parameter chip in ThoughtSpot UI🔗

To show the parameter chip from ThoughtSpot’s user interface, update the Parameter’s value with HostEvent.UpdateParameters after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event.

Parameter chip Initialized via runtimeParameters or URL parameter? Update via HostEvent.UpdateParameters

Parameter chip	Initialized via `runtimeParameters` or URL parameter?	Update via `HostEvent.UpdateParameters`
Hidden	Yes	Possible
Shown	No	Possible

Hidden

Yes

Possible

Shown

Possible

Apply Parameter overrides via REST API🔗

You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. Before applying a Parameter override on a Liveboard or Answer object, ensure that the Parameters are configured in the source Model.

REST API v2🔗

You can apply runtime Parameters when sending an API request to the following v2 API endpoints:

POST /api/rest/2.0/searchdata (Search data)

Allows searching data from a given data source.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "query_string": "[revenue][color]",
  "logical_table_identifier": "540c4503-5bc7-4727-897b-f7f4d78dd2ff",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'

POST /api/rest/2.0/metadata/liveboard/data (Fetch Liveboard data)

Gets data from the Liveboard specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'

POST /api/rest/2.0/metadata/answer/data (Fetch Answer data)

Gets data from a saved Answer.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "0fb54198-868d-45de-8929-139b0089e964",
  "runtime_param_override": {
    "param1": "Double List Param",
    "paramVal1": 0.5,
    "param2": "Date Param",
    "paramVal2": 1696932000
  }
}'

POST /api/rest/2.0/report/liveboard (Export Liveboard Report)

Gets data from a Liveboard in the file format specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/liveboard' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "9bd202f5-d431-44bf-9a07-b4f7be372125",
  "file_format": "PNG",
  "runtime_param_override": {
    "param1": "Date List Param",
    "paramVal1": 1672567200,
    "param2": "Integer Range Param ",
    "paramVal2": 5
  }
}'

POST /api/rest/2.0/report/answer (Export Answer Report)

Gets data from a saved Answer in the file format specified in the API request.

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \
  -H 'Authorization: Bearer {access-token}'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "metadata_identifier": "0fb54198-868d-45de-8929-139b0089e964",
  "file_format": "PNG",
  "runtime_param_override": {
    "param1": "Double List Param",
    "paramVal1": 0.5,
    "param2": "Date Param",
    "paramVal2": 1696932000
  }
}'

REST API v1🔗

You can apply runtime Parameters when sending an API request to the following v1 Data API endpoints:

/tspublic/v1/pinboarddata (Liveboard data API)
/tspublic/v1/searchdata (Search data API)

Liveboard data🔗

To apply overrides to a Liveboard via REST API, add Parameters to the Liveboard data API request URL as shown in the example here:

https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=86bedf72-c718-49cc-9f49-6e8870233f35&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=Double%20list%20param&paramVal1=0

If the API request is valid, overrides are applied to the Liveboard data, and ThoughtSpot returns the requested data in the API response.

{
    "adfaa348-755b-4b95-94ff-220c94c0c8b6": {
        "columnNames": [
            "Ship Mode",
            "Total Tax",
            "Adjusted Tax"
        ],
        "data": [
            [
                "fob",
                7,
                0.0
            ],
            [
                "mail",
                2,
                0.0
            ]
        ],
        "samplingRatio": 1.0,
        "totalRowCount": 2,
        "rowCount": 2,
        "pageSize": 100000,
        "offset": 0,
        "name": "Parameters Answer"
    }
}

Search data🔗

To apply overrides on an Answer obtained from a new search query, append the Parameter attributes to the search data API request URL as shown here:

https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?query_string=%20%5BTax%5D%5BShip%20Mode%5D&data_source_guid=540c4503-5bc7-4727-897b-f7f4d78dd2ff&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=Double%20list%20param&paramVal1=0

Add additional Parameters🔗

You can add additional Parameters in the URL by incrementing the number for each Parameter attribute; for example, param1, param2, paramVal1, paramVal2, and so on. To add additional overrides, specify the values by separating them with an ampersand (&) as shown in the examples here:

URL

https://{ThoughtSpot-host}/?param1=double%20list%20param&paramVal1=0&param2=double%20param&paramVal2=0#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a

REST API request

https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT&param1=double%20list%20param&paramVal1=0&param2=double%20param&paramVal2=0

Apply runtime overrides via URL query parameters🔗

You can apply overrides to Parameter values at runtime and visualize data with the adjusted values. Like runtime filters, you can append the Parameter attribute to the object URLs and modify the resulting output.

For example, if you want to override the value of the inflation Parameter on a Liveboard or Answer, add the Parameters to the object URL as shown in these examples:

Liveboard

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

Saved Answer

https://{ThoughtSpot-host}/?param1=Discount&paramVal1=0.25#/saved-answer/3e84d95c-986e-4154-8362-3807906dad50

Search data

https://{ThoughtSpot-host}/?param1=Discount&paramVal1=0.25#/answer/

Important

ThoughtSpot returns an error if an object URL with Parameter attributes exceeds 2000 characters.

Parameters and JWT tokens🔗

Parameters work differently when used in JWT tokens to secure values for users. Setting a Parameter value via a JWT token will not hide the Parameter value by default. It lets you display a placeholder value on the Parameter chip, for example “Secured”, to indicate that the Parameter is used for security purposes. Note that the placeholder Parameter value is the default value set in your Parameter. Business users will see this value on the Parameter chip. However, the value of the parameter being used in the data displayed will be the one passed via the JWT token.

Regardless of the user’s interaction with the Parameter chip, Parameter values initiated via the JWT token cannot be overridden through the UI, to guarantee its use for security purposes only.

ThoughtSpot recommends hiding the Parameter chip while using a JWT token to minimize confusion. To do so, set the is_hidden flag to true in the Model TML for all Parameter columns that you wish to hide from ThoughtSpot’s user interface:

Parameter hidden

Is the Parameter value passed via a JWT? Is the is_hidden property enabled for the Parameter in the Model? Parameter chip behavior

Is the Parameter value passed via a JWT?	Is the `is_hidden` property enabled for the Parameter in the Model?	Parameter chip behavior
Yes	No	The Parameter chip is visible and shows the parameter’s default value. It uses the Parameter value defined in the JWT in the data. User interactions with the filter chip will be ignored due to Parameter value defined via JWT token being locked.
Yes	Yes	The Parameter chip will be hidden. Uses the Parameter value defined in the JWT token.

Yes

The Parameter chip is visible and shows the parameter’s default value. It uses the Parameter value defined in the JWT in the data. User interactions with the filter chip will be ignored due to Parameter value defined via JWT token being locked.

Yes

The Parameter chip will be hidden. Uses the Parameter value defined in the JWT token.