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.

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

axis_configs

chart

chart_columns

client_state

cohort_grouping_type

cohort_type

column_id

column_type

custom_name

data_type

description

display_mode

expr

formulas

fqn

guid

headline_aggregation

id

key

locked

name

ordered_column_ids

override_value

owner

parameter_overrides

parameter_values

properties

search_query

show_headline

table

table_columns

tables

type

value
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

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

answer_columns

A list of columns generated by the search query.

axis_configs

Specifies the columns for each axis on a chart.

If you are displaying a column chart with a line chart overlaying it, for example, you would need to specify more than one axis_config.

chart

Contains configuration for the Answer, if it displays in chart format.

chart_columns

A list of columns in the chart.

client_state

A JSON string with more advanced chart and table configuration.

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

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

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.

custom_name

Optional display name for a column.

data_type

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

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

expr

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

formulas

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.

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

Specifies the type of aggregation the headline uses.

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

id

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

In the parameter_overrides section, id refers to the Parameter’s GUID.

key

Name of the Parameter referenced in a formula in an Answer.

In the parameter_overrides section, key refers to the Parameter’s GUID.

locked

The 'automatically select my chart' option in the UI. If set to true, the chart type does not change, even when you change the search query.

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.

ordered_column_ids

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

override_value

The value a Parameter is set to in an Answer, if different from the default value.

owner

The owner of a column or query set.

parameter_overrides

Contains information on the value a Parameter is set to in an Answer, if different from its default value. If there is no override_value line, the Parameter is set to the default value.

parameter_values

Container for the Parameters in an Answer.

properties

The list of the properties of the output for a formula within an Answer.

Each formula’s output can have the following properties, depending on its definition: column_type and aggregation.

search_query

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

show_headline

Determines whether to show the headline for this column. true shows the headline.

table

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

table_columns

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

tables

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

type

Within the chart section of an Answer TML file, this is the chart type.

Possible values: COLUMN, BAR, LINE, PIE, SCATTER, BUBBLE, STACKED_COLUMN, AREA, PARETO, COLUMN, GEO_AREA, GEO_BUBBLE, GEO_HEATMAP, GEO_EARTH_BAR, GEO_EARTH_AREA, GEO_EARTH_GRAPH, GEO_EARTH_BUBBLE, GEO_EARTH_HEATMAP, WATERFALL, TREEMAP, HEATMAP, STACKED_AREA, LINE_COLUMN, FUNNEL, LINE_STACKED_COLUMN, PIVOT_TABLE, SANKEY, GRID_TABLE, SPIDER_WEB, WHISKER_SCATTER, STACKED_BAR, or CANDLESTICK.

value

The configured value of the Parameter referenced in a formula in the last saved state of the Answer.

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 import manually compressed .zip files. You can only import .zip files that you exported from ThoughtSpot: a custom set of TML files, an object and its associated data sources, or multiple objects of the same type that you exported from the object list page.

  • 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?
×