Answer TSL specification

Use ThoughtSpot Scripting Language to modify an Answer in a flat-file format. Then you can migrate the object to a different cluster, or restore it to the same cluster.

Scriptability for Answers and Pinboards is in Beta. To enable Scriptable Answers and Pinboards, contact ThoughtSpot Support.

To work with Scriptable Answers in ThoughtSpot, you can download Answers to a flat file in TSL, ThoughtSpot’s Scripting Language, modify it, and subsequently upload this file either to the same cluster, or to a different cluster. To learn how to export, change, and update Answers, see Migrate or restore Answers.

Starting with ThoughtSpot release 6.3, ThoughtSpot Scripting Language (TSL) is called ThoughtSpot Modeling Language (TML). Files from version 6.3 and later have a .tml extension. However, you can import files from 6.2.1 and earlier, with a .tsl extension, to 6.3 and later environments with no issue.

Syntax of the Answer TSL file

The TSL file for Scriptable Answers has a specific syntax.

See the Parameters section for details about the keywords used in this example.

You may not see each of these parameters in your own TSL files, depending on whether each variable is explicitly defined. For example, if you did not define any conditional formatting, the conditional_formatting variable does not appear. You can add that variable in the TSL file to specify conditional formatting.

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>
  - id : <optional_table_id_1>
  - fqn : <optional_GUID_of_table_name_1>
  joins :
  - name : <join_name_1>
    source : <source_table_name>
    destination : <destination_table_name>
    type : [RIGHT_OUTER | LEFT_OUTER | INNER | OUTER]
    on : <on_string>
    is_one_to_one : [ false | true ]
  - ...
  table_paths :
  - id : <table_path_name_1>
    table : <table_name_1>
    join_path :
    - {}
  formulas :
  - id : <formula_id_1>
    name : <formula_name_1>
    expr : <formula_definition_1>
    properties : <formula_properties_1>
      column_type : [ MEASURE | ATTRIBUTE ]
      data_type : [ Boolean | Text | Date | Datetime | Time
      | Numeric | Decimal ]
      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>
      conditional_formatting :
      - range :
        min : <conditional_formatting_minimum>
        max : <conditional_formatting_maximum>
      - rule : <conditional_formatting_rule_1>
          range :
            min : <conditional_formatting_minimum>
            max : <conditional_formatting_maximum>
          color : <color_string>
          plotAsBand : [ true | false ]
      - rule : <conditional_formatting_rule_2>
      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>
      conditional_formatting :
      - rule : <conditional_formatting_rule_1>
          range :
            min : <conditional_formatting_minimum>
            max : <conditional_formatting_maximum>
          color : <color_string>
          plotAsBand : [ true | false ]
      - rule : <conditional_formatting_rule_2>
    - 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 : [ CHART_MODE | TABLE_MODE ]

Parameters of the Answer TSL file

aggregation

The aggregation of the output for a formula within an Answer.
Aggregation options depend on the data type.

Possible values:

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.

color

Color to use for conditional formatting or for the columns of an Answer in chart form, in the form of a HEX value.

column_id

Specifies the way 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). Refer to Components of a Search Query to understand syntax.

column_type

The type of data the column represents. For a formula in an Answer, the column_type refers to the output of the formula.

Possible values:

MEASURE or ATTRIBUTE

The default depends on the data_type. If the data type is Numeric or Decimal, the formula output’s column_type defaults to Measure. If the data type is Boolean, Text, Date, Datetime, or Time, the formula output’s column_type defaults to Attribute.

conditional_formatting

Conditional formatting for the chart or table of an Answer.

custom_name

Optional display name for a column.

data_type

The data type of the formula output. If the data type is Numeric or Decimal, the formula output’s column_type defaults to Measure. If the data type is Boolean, Text, Date, Datetime, or Time, the formula output’s column_type defaults to Attribute. The possible data types are Boolean, Text, Date, Datetime, Time, Numeric, and Decimal.

description

The text that describes an object: a worksheet, a worksheet_column, answer, pinboard, and so on.

destination

Name of destination table or view of the join

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

formulas

The list of formulas in the Answer.
Each formula is identified by name, the expr (expression), and an optional id attribute.

fqn

The table’s GUID. You can find this string of letters and numbers at the end of the URL for that table. For example, in https://<company>.thoughtspot.com/#/data/tables/34226aaa-4bcf-4d6b-9045-24cb1e9437cb, the GUID is 34226aaa-4bcf-4d6b-9045-24cb1e9437cb.

headline_aggregation

Specifies the type of headline aggregation. Can be COUNT, COUNT_DISTINCT, SUM, MIN, MAX, AVERAGE, or TABLE_AGGR.

id

Specifies the way 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'.

is_one_to_one

Specifies the cardinality of the join

Possible values:

true, false

Default:

false

join_path

Specification of a composite join as a list of distinct join attributes
These join attributes list relevant joins, previously defined in the joins, by name.

Default:

{}

join_progressive

Specifies when to apply joins on a worksheet

Possible values:

true when joins are applied only for tables whose columns are included in the search, and false for all possible joins

Default:

true
See How the worksheet join rule works

joins

List of joins between tables and views, used by the data source, if it is a Worksheet.
Each join is identified by name, and the additional attributes of source, destination, type, and is_one_to_one.

layout

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

locked

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

max

Maximum value for conditional formatting.

min

Minimum value for conditional formatting.

name

The name of an object. Applies to worksheet, table,join, formula, answer, pinboard and so on.
For Answers, 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.

on

The keys that your tables are joined on.

ordered_column_ids

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

properties

The properties of the output for a formula within an Answer.
For Answers, each formula’s output can have the following properties, depending on its definition: column_type and aggregation.

plotAsBand

Specifies whether to plot the chart conditional formatting like a band on the Visualization. This is the 'fill chart' option in the UI.

range

Range for the conditional formatting to apply to, with a specified min and max.

rule

A conditional formatting rule.

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.

source

Name of source table or view of the join

table

Specific table, used in defining higher-level objects, such as table paths.
Defined as name within tables definition.
This parameter can also refer to the configuration for the Answer, if it displays in table format.

table_columns

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

table_paths

The list of table paths
Each table path is identified by the id, and additional attributes of table and join_path.

tables

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

type

This refers to both the join type and the chart type.

Possible values for the join type:

LEFT_OUTER for left outer join, RIGHT_OUTER for right outer join, INNER for inner join, OUTER for full outer join

Default:

INNER

Possible values for the chart type:

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 TSL files

There are certain limitations to the changes you can apply by editing an Answer through TSL.

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

  • It is not possible to reverse the join direction in the TSL script.

  • You cannot create Scriptable representations of R- or Python-powered visualizations.

Related Information

Was this page helpful?
×