Define variables
10.14.0.cl
Cloud (Latest)
10.13.0.cl
Cloud
10.12.0.cl
Cloud
10.10.0.sw
Software (Latest)
10.1.0.sw
Software

Define variables

Variables allow you to define dynamic placeholders for specific properties of metadata objects, such as Connections and Tables. By using variables, you can dynamically assign different values to the object properties for each Org and yet use a single source with a consistent data structure across different Orgs. Before publishing an object to other Orgs, define variables for each Org and assign these variables to the metadata object properties.

Important

Note the following enhancements and breaking changes introduced in ThoughtSpot Cloud 10.14.l0.cl release:

  • Variable creation

    • The variable creation endpoint /api/rest/2.0/template/variables/create doesn’t support assigning values to a variable. To assign values to a variable, use the /api/rest/2.0/template/variables/update-values endpoint.

    • The sensitive parameter is renamed as is_sensitive.

  • Variables update and value assignment
    The /api/rest/2.0/template/variables/update endpoint is deprecated and is replaced with /api/rest/2.0/template/variables/update-values.
    To update the properties of a specific variable, use the /api/rest/2.0/template/variables/{identifier}/update endpoint and to assign values to one or several variables, use the POST /api/rest/2.0/template/variables/update-values endpoint.

  • Variable search

    • The variables search API endpoint /api/rest/2.0/template/variables/search now includes the value_scope parameter that allows you to filter the API response by the objects to which the variable is mapped.

    • Filtering API response by EDITABLE_METADATA_AND_VALUES output format is no longer supported.

ThoughtSpot recommends updating your application setup and workflows to avoid operational issues in your environment.

Before you begin🔗

  • Ensure that you have edit access to the metadata objects to which you want to assign variables.

  • Ensure that you have administration privileges to create, edit, or delete a variable.

Create a variable🔗

To create a variable, send a POST request to the /api/rest/2.0/template/variables/create API endpoint, with the following parameters in the request body.

Request parameters🔗

In your POST request body, include the following parameters:

ParameterDescription

type

String. Type of the variable. The API supports the following types of variables:

  • TABLE_MAPPING
    To map Tables properties to variables.

  • CONNECTION_PROPERTY
    To define variables for connection properties. This variable allows editing connection properties such as accountName, warehouse, user, password, role and so on.

  • CONNECTION_PROPERTY_PER_PRINCIPAL
    To define variables for connection properties per user or user group. This variable allows modifying connection properties such as warehouse, role, user, password. The CONNECTION_PROPERTY_PER_PRINCIPLE variable does not support modifying core connection properties such as accountName, host, or port. These properties must be derived from the connection configuration and cannot be set per user or user group.

name

String. Name of the variable. For example, schema_var. Note that the name must be unique across all Orgs within the instance.

is_sensitive Optional

Boolean. Indicates if the variable contains sensitive values such as passwords.

data_type
Available from 10.15.0.cl onwards

String. Variable data type.

Supported data types are:

  • VARCHAR
    String. For example, "East", "Administrator", "Secure", "2025-10-23"

  • INT32
    32-bit integer data type. For example, 100,-42

  • INT64
    32-bit integer data type. For example, 0, 2147483647

  • DOUBLE
    The Double data type refers to a floating point numeric type that is recommended for storing decimal values. For example, 3.14, -0.001, 100.0, 1.7E+308. In ThoughtSpot, DOUBLE is used for columns that require floating point arithmetic or need to store decimal numbers, such as latitude and longitude or financial amounts.

  • DATE
    Date format. For example, 2025-10-20.

  • DATE_TIME
    Date with time stamp. For example, 2025-10-20 14:30:00.

    Note
    		 The API doesn’t support setting data type for the TABLE_MAPPING, CONNECTION_PROPERTY, and CONNECTION_PROPERTY_PER_PRINCIPAL variable types.

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/create'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
 --data-raw '{
  "type": "TABLE_MAPPING",
  "name": "TableVar",
  "is_sensitive": true,
  "data_type": "VARCHAR"
}'

Example response🔗

If the API request is successful, the following response is returned:

{
  "id": "3242b54c-69bc-4ff0-97cf-f99a2216b616",
  "name": "TableVar",
  "variable_type": "TABLE_MAPPING",
  "sensitive": true,
  "values": []
}

Note the variable ID.

Update variable values🔗

To update a variable or properties of a variable, use the following REST APIs:

Update properties of a variable🔗

To update the properties of a variable, send a POST request to /api/rest/2.0/template/variables/{identifier}/update with the following parameters in the request body. Specify the variable ID in the {identifier} path parameter.

Request parameters🔗

In your POST request body, you can include the following parameters:

ParameterType

Description

identifier

Path

String. Name or ID of the variable to update.

name

Form parameter

Example request🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/3242b54c-69bc-4ff0-97cf-f99a2216b616/update'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "name": "TableVar"
}'

If the update operation is successful, the API returns a 204 response to indicate that the variable was updated successfully.

Update properties of multiple variables🔗

To update properties of multiple variables in a single API call, send a POST request to the POST /api/rest/2.0/template/variables/update-values API endpoint.

The API endpoint allows:

  • Adding new values to variables

  • Replacing existing values

  • Resetting values

Request parameters🔗

In your POST request body, you can include the following parameters:

ParameterPropertiesDescription

variable_assignment

Properties for setting values for a variable at a specific entity level such as Org, user, or user-group. This allows the same variable to have different values depending on which entity is being referenced.

variable_identifier

Array of strings. Specify the variables to which you want to assign values.

variable_values

Array of strings. Specify the values to assign. For example, staging1.

operation

Specify the update operation type. The following values are available:

  • ADD
    Adds new values. Use this operation type if you want to add new attributes to the variable.

  • REPLACE
    Replaces the existing attributes with new values.

  • REMOVE
    Removes the values assigned to the variable. For example, you can remove the values assigned to a variable configured for an Org.

  • `RESET
    Resets all values at the variable level. For example, if a variable is assigned to multiple entities such as Org, user, or user group, the reset operation clears the values assigned to the variable for all entities.

variable_value_scope

Set the scope for variable values.

org_identifier

String
ID or name of the Org. For primary Org, specify primaryOrg or Org 0.

principal_type and principal_identifier
Optional

String. Principal attributes such as user and user group. These attributes are applicable to the CONNECTION_PROPERTY_PER_PRINCIPAL variable type.

model_identifier

ID or name of the Model.

priority
Optional

The priority assigned to this value. Applicable to the CONNECTION_PROPERTY_PER_PRINCIPAL variable type.
Priority refers to the order of precedence when updating variable values for multiple entities in a single operation. If more than one entity matches the conditions during variable resolution, based on the value assigned to the priority, the system determines which entity’s value takes effect. For example, if both a user and their group have a value for the same variable, the system uses the priority to decide which value to apply.

Request example🔗

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/update-values'  \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "variable_assignment": [
    {
      "variable_identifier": "e61ace04-6651-4725-9174-90ce33423ef9",
      "variable_values": [
        "prod1"
      ],
      "operation": "REPLACE"
    }
  ],
  "variable_value_scope": [
    {
      "org_identifier": "prodOrg",
      "model_identifier": "Sampel retail sales"
    }
  ]
}'

If the update operation is successful, the API returns a 204 response to indicate that the variable was updated successfully.

Get details of variables🔗

To get a list of variables or the details of a specific variable, send a POST request to the /api/rest/2.0/template/variables/search API endpoint.

To search for a variable, specify the following parameters in your API request:

  • variable details
    Details such as variable type, ID, and name pattern. For name pattern search, specify the partial name of the variable. For wildcard search, use %.

  • variable value
    Variable parameters such as Org ID, Model ID, ID and type of Principal object.

  • output format for response content
    Specify one of the following values for output format:

    • METADATA_ONLY (default)
      Returns only the variable metadata

    • METADATA_AND_VALUES
      Returns variable metadata and values

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/search'  \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {AUTH_TOKEN}' \
  --data-raw '{
  "record_offset": 0,
  "record_size": 10,
  "output_format": "METADATA_AND_VALUES",
  "variable_details": [
    {
      "type": "TABLE_MAPPING"
    }
  ]
}'

If the request is successful, the API returns the variable data in the response:

[
   {
      "id":"180a9cd3-8605-445b-8b70-aa0bcef5dfb0",
      "name":"schema_var",
      "variable_type":null,
      "sensitive":null,
      "values":[
         {
            "value":"primaryOrg",
            "org_identifier":"Primary",
            "principal_type":null,
            "principal_identifier":null,
            "priority":null
         },
         {
            "value":"MyOrg1",
            "org_identifier":"MyOrg1",
            "principal_type":null,
            "principal_identifier":null,
            "priority":null
         },
         {
            "value":"MyOrg2",
            "org_identifier":"MyOrg2",
            "principal_type":null,
            "principal_identifier":null,
            "priority":null
         }
      ]
   }
]

Delete a variable🔗

To delete a variable, send a POST request to the /api/rest/2.0/template/variables/{identifier}/delete API endpoint, with the variable ID in the path parameter.

Note that you can delete only one variable at a time.

If the variable is used by other objects, make sure to update the properties of the object before deleting the variable.

curl -X POST \
--url 'https://{ThoughtSpot-Host}/api/rest/2.0/template/variables/180a9cd3-8605-445b-8b70-aa0bcef5dfb0/delete' \
-H 'Authorization: Bearer {AUTH_TOKEN}'

If the API request is successful, ThoughtSpot returns a 204 response code.

© 2025 ThoughtSpot Inc. All Rights Reserved.