Runtime Parameter overrides

Runtime Parameter overrides

ThoughtSpot lets you create Parameters in a Worksheet and integrate them into formulas, filters, data queries, and Liveboards. 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.

How to apply Parameters🔗

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.

Runtime overrides🔗

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.

Note

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

To apply overrides to a Liveboard or Answer object, Parameters must be defined in the Worksheet from which the data is retrieved for live analytics.

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
https://{ThoughtSpot-host}/#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a?param1=Discount&paramVal1=0.25
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

For the DATE parameter, specify the value in 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 via REST API🔗

You can apply Parameter overrides to a Liveboard or Answer using REST v1 data API endpoints.

Liveboard data🔗

Before applying a Parameter override on a Liveboard, make sure the Worksheet used for generating visualizations contains Parameters.

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

Answer data🔗

Before applying a Parameter override on an Answer object, make sure the Worksheet used for generating the Answer data has the Parameters and formula configured.

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

The following example shows the API response for the above request:

{
    "columnNames": [
        "Ship Mode",
        "Total Tax"
    ],
    "data": [
        [
            "air",
            2888
        ],
        [
            "fob",
            2802
        ],
        [
            "mail",
            2833
        ],
        [
            "rail",
            2885
        ],
        [
            "reg air",
            3053
        ],
        [
            "ship",
            2770
        ],
        [
            "truck",
            2995
        ],
        [
            null,
            2
        ]
    ],
    "samplingRatio": 1.0,
    "totalRowCount": 8,
    "rowCount": 8,
    "pageSize": 100000,
    "offset": 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 Parameter overrides using Visual Embed SDK🔗

The Visual Embed SDK v1.25.0 supports 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: "9"
    }]
});
Note

Parameter overrides do not modify the labels on filter chips displayed on a Liveboard or Answer. However, the overrides are applied on charts and tables as per the Parameter definition in the runtimeParameters array.