TML for Liveboards

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

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

The TML file for Liveboards has a specific syntax.

See the TML parameters for Liveboards 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 you do not have any filters on your Liveboard, the filters parameter does not appear. You can add that variable to the TML file to specify filters for your Liveboard.

guid: <liveboard_guid>
liveboard:
  name: <liveboard_name>
  description:
    This is a multi-line description of the Liveboard.
    Description line 2
  visualizations:
  - id: <viz_id_1>
    answer:
    This section includes all the Answer specification for a visualization, from name to display_mode, in the TML for Answers article.
    viz_guid: <vizualization_1_guid>>
  - id: <viz_id_2>
    answer:
    This section includes all the Answer TML for a second visualization. In this case, the visualization is a headline.
    display_headline_column: <headline_column>
    viz_guid: <vizualization_2_guid>>
  filters:
  - column:
   - <primary_filter_column_name_1>
   - <linked_filter_column_name_2>
   - <linked_filter_column_name_n>
    oper: <filter_operator>
    values: <filtered_values>
    - value 1
    - value 2
    - value n
    excluded_visualizations:
    - excluded_viz_id_1
    - excluded_viz_id_2
  - column: <filtered_column_name_2>
   ...
  layout:
    tabs:
    - name: <tab_1_name>
      description: <tab_1_description>
      tiles:
      - visualization_id: <visualization_id_1>
        x: <viz_1_horizontal_location>
        "y": <viz_1_vertical_location>
        height: <viz_1_height>
        width: <viz_1_width>
      - visualization_id: <visualization_id_2>
        x: <viz_2_horizontal_location>
        "y": <viz_2_vertical_location>
        height: <viz_2_height>
        width: <viz_2_width>
      - visualization_id: <visualization_id_3>
        size: <visualization_3_size>
    - name: <tab_2_name>
      description: <tab_2_description>
      tiles:
      ...
    - name: <tab_n_name>
      description: <tab_n_description>
      tiles:
      ...
  parameter_overrides:
  - key: <parameter_guid>
    value:
      name: <parameter_name>
      id: <parameter_guid>
      override_value: <parameter_override_value>

TML parameters for Liveboards

These parameters and their definitions are specific to Liveboards; 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 - i k - t v - y

answer

column

description

display_headline_column

excluded_visualizations

filters

guid

height

id

key

layout

liveboard

name

oper

override_value

parameter_overrides

size

tabs

value

values

visualization_id

visualizations

viz_guid

width

x

"y"
aggregation

The default aggregation of the Worksheet, view, or table column, or the 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 or visualization within a Liveboard.

column

The id of the column(s) being filtered on. When a Liveboard contains linked filters, or filters that affect visualizations based on more than one Worksheet, the primary filter column appears first in the list of columns in the TML. The linked filter column appears after the primary filter column.

description

The text that describes an object: a liveboard, tab, and so on.

display_headline_column

If the visualization is a headline, this parameter specifies the column the headline comes from.

excluded_visualizations

A list of visualizations the Liveboard editor chose to exclude from the filter. Only appears when using selective filters.

filters

Contains specifications for Liveboard filters.

guid

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

height

The height of the Liveboard visualization.

id

Specifies the id of an object, such as visualizations.

For Answers, including Answers within Liveboards, 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, including an Answer in a Liveboard.

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

layout

Specifies the Liveboard layout, in the order that a visualization_id is listed.

liveboard

Top-level container for all object definitions within the Liveboard or SpotIQ result.

name

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

For Answers, including Answers within Liveboards, 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.

oper

The operator of the Liveboard filter. Accepted operators are "in", "not in", "between", =<, !=, <=, >=, >, or <.

override_value

The value a Parameter is set to in a Liveboard or Answer, if different from the default value. Only appears if you change the Parameter value in Liveboard Edit mode and save it.

parameter_overrides

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

size

The size of a visualization in a Liveboard, if using ThoughtSpot’s predetermined sizes. The options are EXTRA_SMALL, SMALL, MEDIUM, LARGE, LARGE_SMALL, MEDIUM_SMALL, and EXTRA_LARGE.

tabs

List of tabs in the Liveboard.

value

The configured value of the Parameter referenced in a formula in the last saved state of the Liveboard or an Answer within a Liveboard.

values

The values being filtered (excluded or included) in a Liveboard.

visualization_id

The id of a visualization.

Used to specify the Liveboard’s layout.

visualizations

The visualizations in a Liveboard: tables, charts, and headlines.

viz_guid

The GUID for the Liveboard visualization. The GUID provides a distinct way to identify the Liveboard visualization, even if it has the same name as another Liveboard visualization.

You can find this string of letters and numbers at the end of the URL for a Liveboard visualization. Under the visualization’s more more menu icon menu, select Copy link. The link copies to your clipboard. The second string of letters and numbers in the URL is the visualization GUID.

width

The width of the Liveboard visualization.

x

The horizontal location of the Liveboard visualization, relative to the upper left of the Liveboard.

"y"

The vertical location of the Liveboard visualization, relative to the upper left of the Liveboard.

Limitations of working with TML files

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

Was this page helpful?
×