TML for Answers

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 Answers, 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 Answers, see Import and export TML files.

The syntax examples in this article contain every possible parameter in TML files for Answers. 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.

Syntax of the Answer TML file

The TML file for Answers has a specific syntax.

See the TML parameters for Answers 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 Answer 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.

guid: <answer_guid>
answer:
  name: <answer_name>
  description:
    This is a multi-line description of the answer
    Description line 2
  tables:
  - id: <table_id>
    name: <table_name_1>
    fqn: <optional_GUID_of_table_name>
  formulas:
  - id: <formula_id_1>
    name: <formula_name_1>
    expr: <formula_definition_1>
    properties: <formula_properties_1>
      column_type: [ MEASURE | ATTRIBUTE ]
      data_type: [ BOOL | VARCHAR | DOUBLE | FLOAT | INT | BIGINT | DATE | DATETIME | TIMESTAMP | TIME ]
      aggregation: [ SUM | COUNT | AVERAGE | MAX | MIN |
                     COUNT_DISTINCT | NONE | STD_DEVIATION | VARIANCE]
  - id: <formula_id_2>
    name: <formula_name_2>
    expr: <formula_definition_2>
    properties: <formula_properties_2>
  - id: <formula_id_3>
    name: <formula_name_3>
    expr: <formula_definition_3>
    properties: <formula_properties_3>
  search_query: <search_query_string>
  answer_columns:
  - id: <column_id_1>
    name: <column_name_1>
    custom_name: <custom_name_1>
  - name: <column_name_2>
  table:
    table_columns:
    - column_id: <column_id_1>
      show_headline: [ true | false ]
      headline_aggregation: <headline_aggregation_string>
    - column_id: <column_id_2>
    ordered_column_ids:
    - column_id: <column_id_1>
    - column_id: <column_id_2>
    client_state: <client_state_string>
  chart:
    type: <chart_type>
    chart_columns: <chart_column_1>
    - column_id: <column_id_1>
    - column_id: <column_id_2>
    axis_configs: <axis_config_1>
    - x:
      - column_id: <column_id_x_axis>
    - y:
      - column_id: <column_id_y_axis>
      color:
      - column_id: <column_id_color>
    axis_configs: <axis_config_2>
    locked: [ true | false ]
    client_state: <client_state_string>
  display_mode: <display_mode_string>
  parameter_values:
  - key: <parameter_1_key>
    value: <parameter_1_value>
  - key: <parameter_2_key>
    value: <parameter_2_value>
  - key: <parameter_n_key>
    value: <parameter_n_value>
  parameter_overrides:
  - key: <parameter_guid>
    value:
      name: <parameter_name>
      id: <parameter_guid>
      override_value: <parameter_override_value>

TML parameters for Answers

These parameters and their definitions are specific to Answers; 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 - c d - l n - t

aggregation answer

answer_columns

axis_configs

chart

chart_columns

client_state

column_id

column_type

custom_name

data_type

description

display_mode

expr

formulas

fqn

guid

headline_aggregation

id

locked

name

ordered_column_ids

override_value

properties

search_query

show_headline

table

table_columns

tables

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

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.

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

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.

ordered_column_ids

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

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.

Limitations of working with TML files

There are certain limitations to the changes you can apply by editing Answers 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?
×