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

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

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.