TML for tables
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 tables, 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 tables, see Import and export TML files.
The syntax examples in this article contain every possible parameter in TML files for tables.
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 file for tables has a specific syntax.
See the TML parameters for tables 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 did not define any RLS rules, the
rls_rules variable does not appear.
You can add that variable in the TML file to specify RLS rules.
Refer to TML for joins for more information on the functionality and syntax of table joins in TML.
To reduce ambiguity, you may need to add the optional
guid: <table_guid> table : name: <table_name> description: <table_description> db: <database_name> schema: <schema_name> db_table: <database_table_name> connection: name: <connection_name> fqn: <optional_connection_GUID> columns: - name: <column_name_1> db_column_name: <database_column_name> data_type: [ BOOL | VARCHAR | DOUBLE | FLOAT | INT32 | INT64 | DATE | TIME ] properties: column_type: [ MEASURE | ATTRIBUTE ] aggregation: [ SUM | COUNT | AVERAGE | MAX | MIN | COUNT_DISTINCT | NONE | STD_DEVIATION | VARIANCE] index_type: [ DONT_INDEX | DEFAULT | PREFIX_ONLY | PREFIX_AND_SUBSTRING | PREFIX_AND_WORD_SUBSTRING ] index_priority: <index_priority> synonyms: <synonym_1> <synonym_2> is_attribution_dimension: [true | false] is_additive: [ true | false ] calendar: [ default | calendar_name ] format_pattern: <format_pattern_string> currency_type: is_browser : true OR column : <column_name> OR iso_code : <valid_ISO_code> is_hidden: [ true | false ] geo_config: latitude : true OR longitude : true OR country : true OR region_name: - country : <name_supported_country> - region_name : <region_name_in_UI> OR custom_file_guid: <custom_map_guid> geometryType: <custom_map_geometry_type> spotiq_preference: <spotiq_preference_string> db_column_properties: data_type: [ BOOL | VARCHAR | DOUBLE | FLOAT | INT32 | INT64 | DATE | TIME ] - name: <column_name_2> - name: <column_name_n> rls_rules: tables: - name: <table_name_1> id: <optional_table_id> fqn: <optional_table_GUID> - name: <table_name_2> - name: <table_name_n> joins: - name: <join_name_1> source: <source_table_name> destination: <destination_table_name> type: [RIGHT_OUTER | LEFT_OUTER | INNER | OUTER] on: <join_expression_string> is_one_to_one: [ false | true ] table_paths: - id: <table_path_name_1> table: <table_name_1> join_path: - join: - <join_name_1> - <join_name_n> - id: <table_path_name_2> table: <table_name_2> join_path: - join: - <join_name_2> - id: <table_path_name_n> table: <table_name_n> join_path: - join: - <join_name_n> rules: - name: <rls_rule_name_1> expr: <rls_rule_expression_1> - name: <rls_rule_name_2> expr: <rls_rule_expression_2> - name: <rls_rule_name_n> expr: <rls_rule_expression_n> joins_with: - name: <join_name_1> description: <optional_join_description_1> destination: name: <destination_table_name_1> fqn: <optional_table_guid_1> on: <join_expression_string_1> type: [RIGHT_OUTER | LEFT_OUTER | INNER | OUTER] is_one_to_one: [ false | true ] - name: <join_name_2> - name: <join_name_n>
These parameters and their definitions are specific to tables; 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 - e||f - j||n - t|
The default aggregation of the view column.
Aggregation options depend on the data type.
Possible values are
Specifies the calendar used by a date column.
Can be the Gregorian calendar (
default), a fiscal calendar, or any custom calendar.
The id of the column(s) being filtered on.
The type of data the column represents.
The columns in the table.
A way to identify the external data warehouse connection that the table or column resides in. To add tables or columns to an external connection, you must specify this parameter.
The source of the currency type.
The GUID for a custom map uploaded by an administrator.
The data type of the column.
The database that a table resides in. Note that this is not the same as the data warehouse (Falcon, Amazon Redshift, or Snowflake, for example).
The name of the column in the database. Note that this database is not the same as the data warehouse (Amazon Redshift, or Snowflake, for example).
The properties of the column in the database. Note that this database is not the same as the data warehouse (Amazon Redshift or Snowflake, for example).
The name of the table in the database. Note that this database is not the same as the data warehouse (Falcon, Amazon Redshift, or Snowflake, for example).
The text that describes an object: a
join, and so on.
The name of the destination table or view for a join.
The definition of the row-level security (RLS) rule. The syntax for variables in TML should be the same as the syntax of the variables in the rule on the table.
The format pattern string that controls the display of a number, date, or currency column.
The table or connection’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
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
fqnparameter, and the connection or table you reference does not have a unique name, the file import fails.
Specifies the geographic information of a column. See Add a geographical data setting.
latitude : true
for columns that specify the latitude
longitude : true
for columns that specify the longitude
country : true
for columns that specify the country
for specifying a region in a country
Uses two paired parameters:
region_name: <region_name_in_UI>; can be State, Postal Code, District, and so on.
custom_file_guid: <custom map GUID>
for columns that use a custom map. Must be followed by
for columns that use a custom map. Must be preceded by
custom_file_guid. Accepts the following values:
Specifies the geometry type of the TopoJSON file. Required for geographical configuration of Worksheet or table columns that use a custom map. Accepts the following values:
The GUID for the table. You can find this string of letters and numbers at the end of the URL for an object.
Specifies the id of an object, such as
A value (1-10) that determines where to rank a column’s name and values in the search suggestions
ThoughtSpot prioritizes columns with higher values.
Controls extended aggregate options for attribute columns.
For attribute columns that have a numeric data type (
INTEGER) or a date data type (
Controls if the column is an attribution dimension.
Used in managing chasm traps.
falseto designate a column as not producing meaningful attributions across a chasm trap
Specifies the cardinality of the join. This is an optional parameter.
Specific join, used in defining higher-level objects, such as table paths.
Specification of a composite join as a list of distinct
joinattributes list relevant joins, previously defined in the
joins, by name.
Contains a list of joins between the tables and views.
If you edit the joins in the Worksheet or View TML file, you are only editing the joins for that specific Worksheet or view. You are not editing the joins at the table level. To modify table-level joins, you must edit the source table’s TML file.
Each join is identified by
name, and the additional attributes of
Contains a list of external joins for which this table is the source. Each join is identified by
description, and the additional attributes of
The name of an object. Applies to
connection, and so on.
The join expression: the relationship definition, or the keys that your tables are joined on. For example,
[sale::Sale_Last Name] = [employee::Employee_Last Name] AND [sale::Sale_First Name] = [employee::Employee_First Name].
To alter a relationship definition, edit this parameter.
The list of properties of a table column.
Each column can have the following properties, depending on its definition:
A container for the full definition of row-level security rules for the table.
A conditional formatting rule.
A container for the names and expressions of row-level security rules for the table.
The schema that the table is a part of.
Name of the source table or view for a join.
Specifies whether to include a column in SpotIQ analysis. Specify
EXCLUDE, or this property defaults to include the column in SpotIQ Analysis.
Alternate names for the column, used in search.
See Hide a column.
Top-level container for all object definitions within the table.
The list of table paths.
Each table path is identified by the
id, and additional attributes of
List of tables used by the RLS rule.
Each table is identified by
The connection type.
Microsoft Azure, or
There are certain limitations to the changes you can apply by editing tables through TML.
Columns can either have a new name, or a new expression. You can’t change both, unless migrating or updating the Worksheet two times.
It isn’t possible to reverse the join direction in the TML script.
You can’t create new tables using TML files. You can only update existing tables.
You can only change logical tables using TML files. You can’t change the physical version of the table that exists in a database. When you change the
column_name, for example, the name changes in the application, but not in the physical table in the database.
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.
Joins only appear in the table TML file of the source table in a join, or the table on the Many side of a Many-to-One join. You can only add and edit table joins from the TML file of the table on the Many side of the join. You can’t view or modify table-level joins from the destination table’s TML file.
You can’t remove tables from a connection. You can only add them.
You can only delete table columns that have no dependents. If the table column has any dependents, ThoughtSpot returns an error when you try to import or validate the TML file. To delete a table column, you must first delete the dependents.
When deleting columns, you only delete ThoughtSpot’s record of the column. You don’t delete the column in your external database.
If there is an error in any row-level security (RLS) rule when importing a table, all RLS rules for the table are removed. ThoughtSpot warns you about this on import, and highlights the rule that is in an error state, so you can fix it or remove it.