Runtime Parameter overrides

Runtime Parameter overrides

ThoughtSpot lets you create Parameters in a Worksheet and integrate them into formulas, filters, data queries, and Liveboards.

About Parametersđź”—

Parameters are useful for "what-if" analysis, financial planning, cohort analysis, and so on. Parameters allow users to visualize data by running different scenarios with adjustable values. With Parameters, business users can use a single report and adjust the values dynamically to fit the scenario they want to analyze.

You can use Parameters within formulas when querying your data via Search, Liveboards, or Answers. For more information about creating and using Parameters, see the following articles in ThoughtSpot product documentation.

Note

Applying Parameter overrides on a Liveboard or Answer via URL, Visual Embed SDK, or REST API hides the filter chips on the Liveboard or Answer page. However, the overrides will be applied to charts and tables.

Supported data typesđź”—

You can apply runtime Parameters on these 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 v1.25.0 and later support Parameter overrides on embedded Liveboards and Answers. Before applying a Parameter override on an Answer or Liveboard object, make sure the Parameters and associated formulas are configured in the Worksheet used for generating charts and tables.

The following example shows how to apply multiple runtime filters on a Liveboard embedded using the SDK:

liveboardEmbed.render({
    liveboardId: '543619d6-0015-4667-b257-eff547d13a12',
    runtimeParameters:[{
        name: "Date List Param",
        value: 1662361200
    },
    {
        name: "Integer Range Param",
        value: 5
    }]
});

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
    }
])

Runtime parameters in object URLsđź”—

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.

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 Worksheet.

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

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
  }
}'

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 chipInitialized via runtimeParameters or URL parameter?Update via HostEvent.UpdateParameters

Hidden

Yes

Possible

Shown

No

Possible

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 Worksheet 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 Worksheet/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.