TML

TML

ThoughtSpot developed its own scriptable approach for exporting, enhancing, and migrating Worksheets, views, tables, Liveboards, Monitor alerts, and Answers. Use TML (ThoughtSpot Modeling Language) to modify a ThoughtSpot object in a flat-file format. Users can model data and build out sophisticated dashboards in the test environment, before deploying to all users.

Structure of a TML file🔗

To work with TML files for Worksheets, views, SQL views, tables, Answers, Liveboards, and Monitor alerts in ThoughtSpot, you can download these objects as a flat file in .TML format, modify, and subsequently upload the TMLs either to the same or a different cluster.

The TML syntax varies per object type. However, all TMLs follow a general pattern that allows programmatic edits. ThoughtSpot offers a lot of flexibility within its set of data objects, and there is no particular hierarchy to TML files, but rather just some rules.

See the following pages for the detailed syntax of TML files for each object type:

For TML modification tips and recommendations, see TML modification.

TML import and export via REST API🔗

The TML API endpoints allow you to programmatically export, validate, and import scriptable TML files. You can use these API endpoints to automate the change management and deployment processes between your development and production environments. With TML API, you can easily migrate your ThoughtSpot content from one environment to another by automating the entire change management process and thereby reducing the risk of human error.

Note

If using older versions of TML files for Liveboards, ensure that your TML file has the object name as liveboard. Replace any pinboard occurrences with liveboard before import.

Import a TML🔗

To import a modified TML object, your account must have the DATAMANAGEMENT (Can manage data) or ADMINISTRATION (Can administer ThoughtSpot) privilege.

You can import single or multiple objects using the tml/import API. If you are importing TML files one at a time, include the fqn property to distinguish objects that have the same name. If you have multiple connections or tables with the same name and the Connection or Table you reference in your TML does not have a unique name, it can lead to invalid object references. Adding fqn helps ThoughtSpot differentiate a Table from another with the same name.

By default, the fqn parameter is not present in the TML file. However, you can export TML with FQNs and use it during the import.

To import TML representation of the metadata objects into ThoughtSpot, use one of the the following API endpoints:

There are multiple kinds of imports possible. They are:

  • PARTIAL imports all objects that validate successfully, and ignores objects that do not validate successfully.

  • ALL_OR_NONE imports the objects that validate successfully.

  • VALIDATE_ONLY validates the objects but does not import them.

Note

If you import only a Worksheet object, it may take some time for the Worksheet to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards.

However, if you import a Worksheet along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use.

Visit Import a TML object for more information.

Export a TML🔗

To export the TML data, your account must have the DATAMANAGEMENT (Can manage data) or ADMINISTRATION (Can administer ThoughtSpot) privilege..

It must be noted that the default format to export the objects is YAML is v1, and JSON in v2 APIs. To export the TML representation of the metadata objects from ThoughtSpot in JSON or YAML format, use one of the following endpoints:

There are several export options available with these APIs:

Export associated objects and connections

  • export_associated
    When set to true, exports the associated objects for the export_ids specified in the API request. The API exports any underlying worksheets, tables, or views for a given object. By default, the API does not export these underlying objects.

  • export_dependent
    Specifies if the Tables of the referenced Connection object must be included in the export.

  • export_connection_as_dependent
    Specifies if a Connection object must be included as a dependent object when exporting a Table, Worksheet, Answer, or Liveboard TML.

Export FQNs

When export_fqn=true, the API exports the FQNs of the referenced objects in the TML data. For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Worksheet. Note that the FQN of a referenced object is the same as the GUID of that object.

ThoughtSpot recommends adding the fqn property before importing the TML objects into the system, because only the name of a referenced object is not sufficient to identify the referenced object during TML import. For example, if your ThoughtSpot instance has two worksheets with the same name, the TML import for a Liveboard that uses one of these worksheets would fail unless the Liveboard TML includes the FQN of the referenced Worksheet. The export_fqn attribute is useful when ThoughtSpot has multiple objects with the same name and you want to eliminate ambiguity during TML import. The export_fqn=true property adds the FQNs of the referenced objects in the TML export API response and saves the manual effort of adding FQNs for TML import.

Export schema

Specifies the schema version to use during TML export. By default, the API request uses v1 schema for Worksheets. If you are using Models, set export_schema_version to v2. Models are supported as new datasets from 9.10.0.cl onwards.

Visit Export a TML object for more information.

TML modification🔗

ThoughtSpot offers a lot of flexibility within its set of data objects, and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on TML modification.

Limitations of working with TML files🔗

There are certain limitations to the changes you can apply by editing a ThoughtSpot object through TML. Visit Limitations of working with TML files for detailed information.

Deployment and version control of TML objects🔗

For information about version control and TML deployment, see the following pages: