TML

Table of Contents

Structure of a TML file
TML import and export via REST API
TML modification
Limitations of working with TML files
- YAML reimport in REST API v2 Playground
Deployment and version control of TML objects

ThoughtSpot Modeling Language (TML) is a scriptable format developed by ThoughtSpot for exporting, modifying, and migrating metadata objects such as Models, Views, Tables, Liveboards, and Answers. TML files allow you to manage and version control these objects outside the ThoughtSpot UI, supporting workflows like bulk changes, migration between environments, and programmatic edits via REST API. Users can use TML to model data and build analytics content in the test environment in a flat-file format, and then import and deploy it in their environments.

Structure of a TML file🔗

To work with TML files for Models, 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.

TML modification🔗

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.

YAML reimport in REST API v2 Playground🔗

If you are using the REST API Playground to import TML in YAML format, note that copying YAML content directly in the input field will likely result in the Invalid YAML/JSON syntax in file error. When you copy the YAML output from the export TML API response in the Playground, the copied content is wrapped in quotation marks and include escaped newline characters (\n). When you paste this content directly in the metadata_tml input field, the API Playground double-escapes characters or removes necessary newline (\n) characters. Due to improper formatting, the YAML input becomes invalid for import, resulting in the Invalid YAML/JSON syntax in file error.

To work around this issue, follow these steps:

After you export TML in the Playground, use the copy to clipboard option to copy the YAML output from the API response as shown in this video.

The output copied from the API response is enclosed in quotation marks ("). For example, "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n".
Paste the YAML output copied from the export TML API response into a text editor.
Remove the quotation marks, update the TML, and ensure that the YAML is properly formatted:
guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n name: Liveboard 1\n
When importing TML in the Playground, do not paste the YAML directly into the metadata_tmls input field. Instead, use the JSON editor to add the YAML.

To open the JSON editor, click View JSON.
In the JSON preview, you’ll see the following code:

{
  "metadata_tmls": [
    "metadata_tmls3",
    "metadata_tmls5",
  ],
  "import_policy": "PARTIAL",
  "create_new": false,
  "all_orgs_context": false
}

Remove the text in the metadata_tmls array and paste your YAML content inside the array. If you are importing more than one TML, use a comma after pasting a TML YAML and then add YAML for the otehr TML.
```
{
  "metadata_tmls": [
    "guid: a162289a-c1ab-427e-9985-8fb5f7c7e539\nliveboard:\n  name: Liveboard 1\n"
  ],
  "import_policy": "PARTIAL",
  "create_new": false,
  "all_orgs_context": false
}
```
You may see double-escaped characters in JSON preview. For example, \\n instead \n. However, these will not be imported in the actual payload.
To submit the request, click Try it Out.

In the following video, you can see that pasting YAML directly in the metadata_tmls form field results in an error due to additional quotation marks and improper formatting. Using the JSON editor, you can paste the YAML inside the array and import TML successfully.

Deployment and version control of TML objects🔗

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