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 - d	e - o	p - v
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 key locked name ordered_column_ids override_value	parameter_overrides parameter_values properties search_query show_headline table table_columns tables type value

a - d

e - o

p - v

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

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.

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 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 Model 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 Model, view, or Answer TML file. You can only override the joins for that specific Model, 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?Give us feedback!

ThoughtSpot is the Modern Analytics Cloud company. Our Live Analytics services deliver personalized, actionable insights at the point of impact for every user, at every level.

Product

By Role

By Department

Solutions

About Us

Connect

(800) 508-7008