TML for Sets

Use TML to modify a ThoughtSpot object in a flat-file format. Then, migrate the object to a different cluster, or restore it to the same cluster.

To work with TML files for Sets, you can download these objects to flat files in .TML format, modify the files, and subsequently upload the files either to the same cluster, or to a different cluster. To learn how to export, change, and update Sets, see Import and export TML files.

The syntax examples in this article contain every possible parameter in TML files for Sets. Some of these parameters are not in these files by default. If you want to use them, you must add them yourself. For example, the fqn parameter is not present in any TML file by default, but you can add it to differentiate a table from another table with the same name.

As you work with TML files, keep in mind that changing elements of the TML file, such as the name of a column or table, may affect dependents. This is specifically true if you are editing TML files outside ThoughtSpot. When you change the name of a table in a TML file, and then import that file into ThoughtSpot, ThoughtSpot automatically updates that table name in any dependents, such as Answers that use the table as a data source. However, if you download multiple TML files from one ThoughtSpot cluster, then change the table name in TML, and upload all the files to a brand-new cluster, ThoughtSpot doesn’t know that the dependents should use that table. You must also change the table name in the dependents.

TML export of sets is only available through the export of the parent object. If a set is used in an answer then exporting the answer with associated objects will export the set definition. This is a separate file.

A single set file or multiple set TML files can be imported using the TML import utility located in the Data tab.

Set owners and ThoughtSpot administrators can edit a set’s TML definition in the Search Data panel.

A set’s owner property can only be edited by the ThoughtSpot administrator. Ownership can be changed in the TML using the optional owner TML property.

Syntax of the Sets TML file

The TML file for Sets has a specific syntax.

See the TML parameters for Sets for details about the keywords used in this example.

See Limitations of working with TML files for more information about actions you can’t perform using TML.

You may not see each of these parameters in your own TML files, depending on whether each variable is explicitly defined. For example, if your Set has no formulas, the formulas variable does not appear. You can add that variable in the TML file to add formulas.

To reduce ambiguity, you may need to add the optional fqn parameter to your TML file when you reference source tables. This is necessary if you have multiple tables with the same name. If you do not add the fqn parameter, and the table you reference does not have a unique name, the file import fails.

Column sets

Column set with bins
guid: <set_guid>
cohort:
  name: <set_name>
  description: This is a multi-line description of the set
    Description line 2
  config:
    cohort_type: SIMPLE
    anchor_column_id: Amount
    bins:
      minimum_value: 0.0
      maximum_value: 100.0
      bin_size: 10.0
    cohort_grouping_type: BIN_BASED
  worksheet:
    id: Dunder Mifflin Sales
    name: Dunder Mifflin Sales
Column set with conditions
guid: <set_guid>
cohort:
  name: <set_name>
  config:
    null_output_value: Ungrouped values
    combine_non_group_values: false
    cohort_type: SIMPLE
    anchor_column_id: date
    groups:
    - name: 2020 Black Friday
      conditions:
      - operator: EQ
        value:
        - 27/11/2020
       column_name: date
      combine_type: ALL
    - name: 2021 Black Friday
      conditions:
      - operator: EQ
        value:
        - 26/11/2021
        column_name: date
      combine_type: ALL
    - name: 2022 Black Friday
      conditions:
      - operator: EQ
        value:
        - 25/11/2022
        column_name: date
      combine_type: ALL
    - name: 2023 Black Friday
      conditions:
      - operator: EQ
        value:
        - 24/11/2023
        column_name: date
      combine_type: ALL
    - name: 2024 Black Friday
      conditions:
      - operator: EQ
        value:
        - 29/11/2024
        column_name: date
      combine_type: ALL
    - name: 2025 Black Friday
      conditions:
      - operator: EQ
        value:
        - 28/11/2025
        column_name: date
      combine_type: ALL
    - name: 2026 Black Friday
      conditions:
      - operator: EQ
        value:
        - 27/11/2026
        column_name: date
      combine_type: ALL
    - name: 2027 Black Friday
      conditions:
      - operator: EQ
        value:
        - 26/11/2027
       column_name: date
      combine_type: ALL
    - name: 2028 Black Friday
      conditions:
      - operator: EQ
        value:
        - 24/11/2028
        column_name: date
      combine_type: ALL
    - name: 2029 Black Friday
      conditions:
      - operator: EQ
        value:
        - 23/11/2029
        column_name: date
      combine_type: ALL
    - name: 2030 Black Friday
      conditions:
      - operator: EQ
        value:
        - 29/11/2030
        column_name: date
      combine_type: ALL
    cohort_grouping_type: GROUP_BASED
  worksheet:
    id: Dunder Mifflin Sales
    name: Dunder Mifflin Sales

Query sets

Query set with columns
guid: <set_guid>
cohort:
  name: <set_name>
  answer:
    tables:
    - id: Dunder Mifflin Sales
      name: Dunder Mifflin Sales
    search_query: "[Customer Code] [Amount]"
    answer_columns:
    - name: Customer Code
    - name: Total Amount
    table:
      table_columns:
      - column_id: Customer Code
        show_headline: false
      - column_id: Total Amount
        show_headline: false
      ordered_column_ids:
      - Customer Code
      - Total Amount
      client_state: ""
    display_mode: TABLE_MODE
  config:
    null_output_value: Ungrouped values
    combine_non_group_values: true
    cohort_type: ADVANCED
    anchor_column_id: Customer Code
    groups:
    - name: 0-100
      conditions:
      - operator: BW
        value:
        - "0"
        - "100"
      column_name: Total Amount
      combine_type: ALL
    - name: 100-200
      conditions:
      - operator: BW
        value:
        - "101"
        - "200"
      column_name: Total Amount
      combine_type: ALL
    cohort_grouping_type: GROUP_BASED
    hide_excluded_query_values: false
    group_excluded_query_values: Excluded values
  worksheet:
    id: Dunder Mifflin Sales
    name: Dunder Mifflin Sales
Query set with conditions
guid: <set_guid>
cohort:
  name: <set_name>
  answer:
    tables:
    - id: Dunder Mifflin Sales
      name: Dunder Mifflin Sales
    search_query: "[Customer Code] count [Order ID]"
    answer_columns:
    - name: Customer Code
    - name: Number of Order ID
    table:
      table_columns:
      - column_id: Customer Code
        show_headline: false
      - column_id: Number of Order ID
        show_headline: false
      ordered_column_ids:
      - Customer Code
      - Number of Order ID
      client_state: ""
      client_state_v2: "{\"tableVizPropVersion\": \"V1\",\"columnProperties\": [{\"columnId\": \"Customer Code\",\"columnProperty\": {}},{\"columnId\": \"Number of Order ID\",\"columnProperty\": {}}]}"
    display_mode: TABLE_MODE
  config:
    cohort_type: ADVANCED
    anchor_column_id: Customer Code
    return_column_id: Number of Order ID
    cohort_grouping_type: COLUMN_BASED
    hide_excluded_query_values: true
  worksheet:
    id: Dunder Mifflin Sales
    name: Dunder Mifflin Sales

TML parameters for Sets

These parameters and their definitions are specific to Sets; this list doesn’t contain every parameter in every TML file. Similarly, the parameter definitions may vary from object to object, since the parameters may have different roles in different objects.

a - d e - o p - v

aggregation

anchor_column_id

answer

answer_columns

bin_size

bins

client_state

cohort

cohort_grouping_type

cohort_type

column_id

column_type

combine_non_group_values

combine_type

conditions

config

custom_name

data_type

description

display_mode

expr

formulas

fqn

group_excluded_query_values

groups

guid

headline_aggregation

hide_excluded_query_values

id

maximum_value

minimum_value

name

null_output_value

operator

ordered_column_ids

owner

return_column_id

search_query

table

table_columns

tables

worksheet
aggregation

The default aggregation of the output for a formula.

Aggregation options depend on the data type.

Possible values are SUM, COUNT, AVERAGE, MAX, MIN, COUNT_DISTINCT, NONE, STD_DEVIATION, and VARIANCE

Default: SUM.

anchor_column_id

Defines the identifier of the column that the set is associated with.

answer (query sets)

Top-level container for all object definitions within an answer.

answer_columns (query sets)

A list of columns generated by the search query.

bin_size

Size of bin.

bins

Container for group configuration for bin-based column sets.

client_state (query sets)

A JSON string with more advanced chart and table configuration.

cohort

A top-level container for all object definitions within a cohort.

cohort_grouping_type

Describes the type of grouping contained in a set.

cohort_type

Describes the type of set, either column or query set.

column_id (query sets)

Describes how the column appears in the query. For example, if you sorted by Quarter in your search, from the Commit Date column, the column_id of the column is Quarter(Commit Date).

column_type (query sets)

The type of data the output of the formula represents.

Possible values: MEASURE or ATTRIBUTE. The default depends on the data_type.

If the data type is INT or BIGINT, the formula output’s column_type defaults to Measure.

If the data type is BOOL, VARCHAR, DOUBLE, FLOAT, DATE, DATETIME, or TIME, the formula output’s column_type defaults to Attribute.

combine_non_group_values

When set to true, combines all values which do not belong to any group.

combine_type

Defines how multiple group conditions should be combined for group-based column sets. Options are ALL or ANY.

conditions

Conditions for each group for group-based column sets.

config

Container for all cohort configurations.

custom_name (query sets)

Optional display name for a column.

data_type (query sets)

The data type of the formula output. If the data type is INT32 or INT64, the formula output’s column_type defaults to Measure. If the data type is BOOL, VARCHAR, DOUBLE, FLOAT, DATE, DATETIME, or TIME, the formula output’s column_type defaults to Attribute.

description

The text that describes an Answer.

display_mode (query sets)

Determines whether the answer displays as a chart or a table. Specify either CHART_MODE or TABLE_MODE.

expr (query sets)

The definition of the formula. This should be the same as the formula expression in the formula editor.

formulas (query sets)

The list of formulas in the Answer.

Each formula is identified by name, the expr (expression), and an optional id attribute.

fqn

The source table’s GUID. You can find this string of letters and numbers at the end of the URL for that table or connection.

For example, in https://<company>.thoughtspot.com/#/data/tables/34226aaa-4bcf-4d6b-9045-24cb1e9437cb, the GUID is 34226aaa-4bcf-4d6b-9045-24cb1e9437cb.

Use this optional parameter to reduce ambiguity and identify a specific table, if you have multiple tables with the same name. When exporting a TML file, you have the option to Export FQNs of referenced objects, which ensures that the TML files you export contain FQNs for the underlying tables and connections. If you do not add the fqn parameter, and the connection or table you reference does not have a unique name, the file import fails.

group_excluded_query_values

Name for combined group values which are not part of Query Set query.

groups

Container for group configuration for group-based column sets.

guid

The GUID for the Answer. You can find this string of letters and numbers at the end of the URL for an object.

headline_aggregation (query sets)

Specifies the type of aggregation the headline uses.

Can be COUNT, COUNT_DISTINCT, SUM, MIN, MAX, AVERAGE, or TABLE_AGGR.

hide_excluded_query_values

Set to true to hide values which are not part of the Query Set query.

id (query sets)

Specifies the id of an object, such as table or formula.

For answer_columns, id refers to how the column appears in the query. For example, if you sorted by Quarter in your search, from the Commit Date column, the id of the column is Quarter(Commit Date). Refer to Components of a Search Query to understand syntax.

For formulas within answers, id refers to the display name of the formula. If you do not give your formula a name, it appears as 'Untitled Formula'.

maximum_value

Maximum value for bin.

minimum_value

Minimum value for bin.

name

The name of an object. Applies to formula, answer, liveboard, table, and so on.

For answer_columns, name refers to how the column appears in the query. For example, if you sorted by Quarter in your search, from the Commit Date column, the name of the column is Quarter(Commit Date). Refer to Components of a Search Query to understand syntax.

In the parameter_overrides section for an Answer or Liveboard, name refers to the Parameter name.

null_output_value

Name for combined group values which are not part of any group in group-based sets.

operator

Operator for group conditions for group-based column sets.

ordered_column_ids (query sets)

A list of columns, in the order they appear in the table.

owner

The owner of a column or query set.

return_column_id

Return column for column-based query sets.

search_query (query sets)

A string that represents the fully disambiguated search query. Refer to Components of a Search Query to understand syntax.

table (query sets)

Contains configuration for the answer, if it displays in table format.

table_columns (query sets)

The columns in an Answer that is being displayed in table format.

tables (query sets)

List of tables used by the Answer. Each table is identified by name.

worksheet

Container for worksheet id and name to which the cohort belongs.

Limitations of working with TML files

There are certain limitations to the changes you can apply by editing Sets through TML.

  • Formulas and columns can either have a new name, or a new expression. You can’t change both, unless migrating or updating the Worksheet two times.

  • You can’t create or export TML files for R- or Python-powered visualizations.

  • You can’t modify joins at the table level from the Worksheet, view, or Answer TML file. You can only override the joins for that specific Worksheet, view, or Answer. To modify table-level joins, you must edit the source table’s TML file.

  • Changing the filter order for Answers in the UI doesn’t change the filter order in the TML file.

Was this page helpful?
×