From eb9c784fdbc2ae75b43c906e8681de54675d46f1 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 11 Aug 2026 22:23:30 +0530 Subject: [PATCH 01/10] SCAL-318536 --- modules/ROOT/pages/embed-pinboard.adoc | 6 +++-- modules/ROOT/pages/filters_overview.adoc | 6 +++-- modules/ROOT/pages/runtime-filters.adoc | 28 ++++++++++++++--------- modules/ROOT/pages/runtime-overrides.adoc | 9 ++++---- 4 files changed, 30 insertions(+), 19 deletions(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 0f2c70d79..80de55335 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -296,8 +296,10 @@ To view specific data across the tables and charts on an embedded Liveboard, use [IMPORTANT] ==== -The SDK processes up to 49 runtime filters per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. For more information, see +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. For more information, see xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. ==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index d4c0d9849..f76e75d8f 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -28,8 +28,10 @@ You can define xref:runtime-filters.adoc[runtime filters] and xref:runtime-param [NOTE] ==== * Runtime filters do not display as UI filter components. -* The SDK processes at most 49 entries per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. See +* Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. ==== diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 338c9a5d5..d228cbec0 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -46,28 +46,34 @@ This attribute is defined as `val1`, `val2`, `val3` in the object URLs and REST Some operators like `EQ` and `LE` accept a single operand, whereas `BW_INC_MAX`, `BW_INC_MIN`, `BW_INC`, `BW`, and `IN` accept multiple operands. === Maximum filter count +ThoughtSpot enforces separate filter count limits depending on how runtime filters are applied: -The SDK processes a maximum of 49 runtime filters per embedded object. +URL-based runtime filters:: -The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the +URL-based runtime filters are capped at exactly 50. This limit is fixed and cannot be configured. The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the parsing loop runs from index `1` up to (but not including) `50` (`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. -This applies to both input paths: - -* URL query parameters: filter values appended to the embed URL -(`col1=`, `op1=`, `val1=`, `col2=`, …) -* `runtimeFilters` embed config property: filters passed as an array in the -SDK initialization config for `LiveboardEmbed`, `AppEmbed`, and -`SearchEmbed` - [IMPORTANT] ==== When the number of runtime filters exceeds 49, filters beyond that index are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the first 49 filters -without any indication that additional filters were discarded. This silent-drop behavior means that, if your application passes 60 runtime filters, the last 11 are ignored without any notification to the developer. Always validate filter counts in your application before passing them to the SDK. +without any indication that additional filters were discarded. +==== + +Embed payload runtime filters (Visual Embed SDK):: + +When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and +`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 filters. + +ThoughtSpot administrators can configure this limit for their instance. The value must be between 1 and 1000. +To check or update the configured limit, contact your ThoughtSpot administrator. + +[IMPORTANT] +==== +Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. ==== === Supported data types diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 4176940fc..96ef02ad6 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -21,10 +21,11 @@ Developers can set runtime filters in the Visual Embed SDK for the following emb After the object loads, runtime filters can be xref:runtime-filters.adoc#_adjust_runtime_filters_using_sdk_events[adjusted using the SDK events]. -WARNING: The SDK processes at most 49 entries per embed. Any objects at index 50 or -beyond are silently dropped without an error or warning. See -xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for -more information. +WARNING: Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a +ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +limit are silently dropped without an error or warning. See +xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. == Runtime Parameters From e85138325ed6bb92b40bafbf28a0acaa6b260311 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 11 Aug 2026 22:42:41 +0530 Subject: [PATCH 02/10] SCAL-318536 --- modules/ROOT/pages/runtime-filters.adoc | 8 -------- 1 file changed, 8 deletions(-) diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index d228cbec0..de21f1bf3 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -55,14 +55,6 @@ parsing loop runs from index `1` up to (but not including) `50` (`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. -[IMPORTANT] -==== -When the number of runtime filters exceeds 49, filters beyond that index are -silently dropped. No error is thrown, no warning is emitted, and no embed -event is fired. The embedded object renders using only the first 49 filters -without any indication that additional filters were discarded. -==== - Embed payload runtime filters (Visual Embed SDK):: When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and From cdc94a8c83647a948fbeb91b22c040b752302331 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 10:11:46 +0530 Subject: [PATCH 03/10] edited based on feedback --- modules/ROOT/pages/embed-pinboard.adoc | 2 +- modules/ROOT/pages/filters_overview.adoc | 2 +- modules/ROOT/pages/runtime-filters.adoc | 6 +++--- modules/ROOT/pages/runtime-overrides.adoc | 8 +++++--- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 80de55335..b0c39e1d5 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -298,7 +298,7 @@ To view specific data across the tables and charts on an embedded Liveboard, use ==== Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. For more information, see xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit]. ==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index f76e75d8f..fe4672d0d 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -30,7 +30,7 @@ You can define xref:runtime-filters.adoc[runtime filters] and xref:runtime-param * Runtime filters do not display as UI filter components. * Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. ==== diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index de21f1bf3..745ab1618 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -58,10 +58,10 @@ through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. Embed payload runtime filters (Visual Embed SDK):: When you pass runtime filters as an array in the SDK initialization config for `LiveboardEmbed`, `AppEmbed`, `SpotterEmbed` and -`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 filters. +`SearchEmbed` using the `runtimeFilters` property in the Visual Embed SDK, ThoughtSpot applies a configurable limit. The default and maximum value is 1000 runtime filters. + +Contact ThoughtSpot support to configure this limit for your instance. The value for the number of filters must be between 1 and 1000. -ThoughtSpot administrators can configure this limit for their instance. The value must be between 1 and 1000. -To check or update the configured limit, contact your ThoughtSpot administrator. [IMPORTANT] ==== diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 96ef02ad6..44093dd9d 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -21,12 +21,14 @@ Developers can set runtime filters in the Visual Embed SDK for the following emb After the object loads, runtime filters can be xref:runtime-filters.adoc#_adjust_runtime_filters_using_sdk_events[adjusted using the SDK events]. -WARNING: Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. +[IMPORTANT] +==== +Runtime filter limits vary by input path. URL-based runtime filters are capped at 50. When using the Visual Embed SDK `runtimeFilters` property, the limit is configurable by a -ThoughtSpot administrator, with a default and maximum of 1,000. Filters beyond the enforced +ThoughtSpot administrator, with a default and maximum of 1,000 runtime filters. Filters beyond the enforced limit are silently dropped without an error or warning. See xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more information. - +==== == Runtime Parameters Parameters allow users to visualize data by running different scenarios with adjustable values. You can use Parameters within formulas when analyzing your data via Search, Liveboards, or Answers. From 21fa9bb3dcd52d82b9845a730609ae07a11aef66 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 12:29:40 +0530 Subject: [PATCH 04/10] collections sdk support --- modules/ROOT/pages/collections.adoc | 8 ++--- .../ROOT/pages/customize-nav-full-embed.adoc | 30 +++++++++++++++++++ 2 files changed, 34 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 4a5cf27ca..62cabb52c 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -9,10 +9,10 @@ ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows. -[NOTE] -==== -The Collections APIs are in Beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support. -==== +You can also embed the Collections page directly in your application using the Visual Embed SDK. +To navigate users to the Collections page in full application embedding, set `pageId` to `Page.Collections` in `AppViewConfig`. +For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page]. + == Before you begin diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index b90c71995..92d34d7b5 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -104,6 +104,31 @@ const embed = new AppEmbed("#embed", { == Command palette availability in embed In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. +== Navigate to the Collections page + +To set the Collections page as the default landing page for full application embedding, use `Page.Collections` in the `pageId` property of `AppViewConfig`. + +// SOURCE: https://github.com/thoughtspot/visual-embed-sdk/blob/master/src/embed/app.ts + +[source,JavaScript] +---- +import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed('#tsEmbed', { + // ... other embed view config + pageId: Page.Collections, + showPrimaryNavbar: true, +}); +embed.render(); +---- + +You can also use `navigateToPage` to route users to the Collections page programmatically after the app loads: + +[source,JavaScript] +---- +appEmbed.navigateToPage('collections'); +---- + == Customize the left navigation panel on the home page In the V3 and V4 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Spotter*, *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides the left navigation only on the home page. @@ -181,6 +206,11 @@ To show or hide the *Scheduled Liveboards* section in the | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported +| `HomeLeftNavItem.Collections` + +To show or hide the *Collections* menu item in the *Insights* left navigation panel. +| [tag greenBackground tick]#✓# Supported +| [tag greenBackground tick]#✓# Supported + |==== From 238fb9322060d9f4f0df40916461f484df416d13 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 12 Aug 2026 13:48:17 +0530 Subject: [PATCH 05/10] highlighted coll changes --- modules/ROOT/pages/collections.adoc | 4 ++-- modules/ROOT/pages/customize-nav-full-embed.adoc | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/collections.adoc b/modules/ROOT/pages/collections.adoc index 62cabb52c..614c2d713 100644 --- a/modules/ROOT/pages/collections.adoc +++ b/modules/ROOT/pages/collections.adoc @@ -9,9 +9,9 @@ ThoughtSpot now provides REST APIs that enable developers to organize different ThoughtSpot objects into an organizational container called *Collections*. These objects can be Liveboards, Answers, data models, tables, and even other Collections. Collections provide a powerful way to manage your data assets, making discovery and collaboration easier, while ensuring the integrity of embedded workflows. -You can also embed the Collections page directly in your application using the Visual Embed SDK. +#You can also embed the Collections page directly in your application using the Visual Embed SDK. To navigate users to the Collections page in full application embedding, set `pageId` to `Page.Collections` in `AppViewConfig`. -For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page]. +For more information, see xref:customize-nav-full-embed.adoc#_navigate_to_the_collections_page[Navigate to the Collections page].# == Before you begin diff --git a/modules/ROOT/pages/customize-nav-full-embed.adoc b/modules/ROOT/pages/customize-nav-full-embed.adoc index 92d34d7b5..f28daee1d 100644 --- a/modules/ROOT/pages/customize-nav-full-embed.adoc +++ b/modules/ROOT/pages/customize-nav-full-embed.adoc @@ -104,7 +104,7 @@ const embed = new AppEmbed("#embed", { == Command palette availability in embed In ThoughtSpot application, users can open the link:https://docs.thoughtspot.com/cloud/latest/thoughtspot-homepage#command-palette[command palette] by pressing kbd:[Cmd+K] on macOS or kbd:[Ctrl+K] on Windows to quickly navigate to objects and perform actions. However, when you embed ThoughtSpot, this feature is disabled and embedded pages include only the standard object search experience. -== Navigate to the Collections page +== #Navigate to the Collections page# To set the Collections page as the default landing page for full application embedding, use `Page.Collections` in the `pageId` property of `AppViewConfig`. @@ -207,7 +207,7 @@ To show or hide the *Scheduled Liveboards* section in the | [tag greenBackground tick]#✓# Supported | `HomeLeftNavItem.Collections` + -To show or hide the *Collections* menu item in the *Insights* left navigation panel. +#To show or hide the *Collections* menu item in the *Insights* left navigation panel.# | [tag greenBackground tick]#✓# Supported | [tag greenBackground tick]#✓# Supported From ba2c7be7d296a516cdcf12c155101c02860519ab Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 10:11:30 +0530 Subject: [PATCH 06/10] added Ramjith's feedback --- modules/ROOT/pages/runtime-filters.adoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 745ab1618..f1bbcf510 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -51,9 +51,8 @@ ThoughtSpot enforces separate filter count limits depending on how runtime filte URL-based runtime filters:: URL-based runtime filters are capped at exactly 50. This limit is fixed and cannot be configured. The internal constant `MAX_RUNTIME_FILTERS` is set to `50`, but the -parsing loop runs from index `1` up to (but not including) `50` -(`index < MAX_RUNTIME_FILTERS`). This means filter values `col1`/`op1`/`val1` -through `col49`/`op49`/`val49` are processed; `col50` and above are ignored. +parsing loop runs from index `1` up to `50`. This means filter values `col1`/`op1`/`val1` +through `col50`/`op50`/`val50` are processed. Embed payload runtime filters (Visual Embed SDK):: @@ -65,7 +64,8 @@ Contact ThoughtSpot support to configure this limit for your instance. The value [IMPORTANT] ==== -Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. +* Regardless of the filter path, filters beyond the enforced limit are silently dropped. No error is thrown, no warning is emitted, and no embed event is fired. The embedded object renders using only the filters within the allowed count. Always validate filter counts in your application before passing them to the SDK. +* Runtime filters must be numbered sequentially, starting from `col1`. The parser reads filters in order, like `col1`, `col2`, `col3`, and stops as soon as a number is missing. ==== === Supported data types From 3949c7b83b4c2c455ce80c95c21373a0951d7696 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 13:23:30 +0530 Subject: [PATCH 07/10] objectid --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 92 ++++++++++++++++++- 1 file changed, 91 insertions(+), 1 deletion(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 3096ec818..155eeef77 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -16,7 +16,7 @@ The following figure illustrates the object model hierarchy in ThoughtSpot withi image::./images/object_model_hierarchy.png[Object Model Hierarchy] -== Object identifiers +== #Object identifiers# Every object in ThoughtSpot has a globally unique ID (GUID), visible in URLs and in REST API responses as the `id` or `metadata_id` property. GUIDs are unique within a ThoughtSpot instance and thus cannot repeat in different Orgs. Objects have an additional `obj_id` property that is *user-settable* and *unique per Org*. It appears as `metadata_obj_id` in responses from the `/metadata/search` REST API. @@ -25,6 +25,96 @@ Each Org can have one object with a particular `obj_id`. The combination of `org `obj_id` allows you to export TML that can be imported into any Org on any instance, letting ThoughtSpot determine the object's GUID automatically without requiring any additional effort on your part. +=== Supported object types + +Currently, `obj_id` is supported for the following object types: + +// SOURCE: PRD doc section "Requirements"; SCAL-317366 description + +* Answers +* Data Model +* Logical Tables +* Liveboards +* Visualizations +* Collections +* Personalized Views + +=== obj_id format and constraints + +// SOURCE: PRD doc section "Identity Constraints and Object-ID Specification"; SCAL-314582 +`obj_id` values must meet the following requirements: + +[cols="2,3", options="header"] +|=== +|Constraint | Requirement + +|Allowed characters | Lowercase alphanumeric, dots, and hyphens: `[a-z0-9.-]` +|Casing | Strictly lowercase +|Maximum length | 64 characters +|GUID exclusion | Must not match a standard GUID format to prevent ambiguity +|=== + +*Valid examples:* `sales.pipeline.v1`, `finance-ledger-prod`, `ingestion-worker-01` + +=== obj_id resolution + +// SOURCE: PRD doc section "Deterministic Keying and Distributed Consistency"; SCAL-317366 +When you pass an identifier to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: + +. `obj_id` (user-defined identifier) +. GUID +. Name + +This precedence means you can use `obj_id` anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. + +[NOTE] +==== +`obj_id` resolution is scoped to the Org. An `obj_id` value is unique within a single Org. The `org_id` + `obj_id` combination uniquely identifies an object across the entire ThoughtSpot instance. +==== + +=== Setting and updating obj_id + +You can set or update `obj_id` values using the following REST API endpoints: + +* `POST /api/rest/2.0/metadata/update-obj-id` + +Updates the `obj_id` for one or more metadata objects. Accepts the object's GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). + +// SOURCE: deploy-with-tml-apis.adoc; SCAL-317366 +[,json] +---- +{ + "metadata": [ + { + "metadata_identifier": "c1e4043a-4524-4fcb-a20f-9e7aff4dc972", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +Or, using the current `obj_id`: + +[,json] +---- +{ + "metadata": [ + { + "current_obj_id": "sales-pipeline-v1-c1e4043a", + "new_obj_id": "sales-pipeline-v1" + } + ] +} +---- + +The request accepts an array, so you can update `obj_id` for multiple objects in a single API call. + +[NOTE] +==== +Objects are assigned an automatic `obj_id` after the first change to the object once the feature is enabled on your instance. The auto-generated format appends the first segment of the GUID: for example, `RetailSalesRAD-KPIs-c1e4043a`. If the `metadata_obj_id` property in the `/metadata/search` response is `null`, the object has not been updated since the feature was enabled. +==== + +For information about using `obj_id` in CI/CD workflows, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] and xref:development-and-deployment.adoc[Development and deployment]. + == Data modeling You must create a data model with at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] before you can use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. From a14f67ba93cd55a44b42e6f794d803b505232fdf Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 17 Aug 2026 16:16:46 +0530 Subject: [PATCH 08/10] lang corrections --- .../ROOT/pages/intro-thoughtspot-objects.adoc | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index 155eeef77..b88e78e56 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -6,9 +6,9 @@ :page-pageid: thoughtspot-objects :page-description: -ThoughtSpot is a business intelligence and data analytics platform that helps you explore, analyze, and share real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. +ThoughtSpot is a business intelligence and data analytics platform for exploring, analyzing, and sharing real-time business analytics and interactive insights. Besides being an interactive data analytics platform, ThoughtSpot provides robust, guided search functionality that business users can use to search data instantly. ThoughtSpot is different from other BI tools because ThoughtSpot Search is the core of the ThoughtSpot system. -Before you look at the rest of the developer documentation, please review this page to understand how ThoughtSpot works relative to other tools you may be familiar with. +Review this page to understand how ThoughtSpot's architecture differs from other BI tools before proceeding with the developer documentation. == Object model hierarchy @@ -23,7 +23,7 @@ Objects have an additional `obj_id` property that is *user-settable* and *unique Each Org can have one object with a particular `obj_id`. The combination of `org_id` + `obj_id` is unique per instance, so it is equivalent to the object's GUID. -`obj_id` allows you to export TML that can be imported into any Org on any instance, letting ThoughtSpot determine the object's GUID automatically without requiring any additional effort on your part. +`obj_id` enables TML export and import across Orgs and instances, allowing ThoughtSpot to automatically determine the object's GUID without manual GUID mapping. === Supported object types @@ -59,13 +59,13 @@ Currently, `obj_id` is supported for the following object types: === obj_id resolution // SOURCE: PRD doc section "Deterministic Keying and Distributed Consistency"; SCAL-317366 -When you pass an identifier to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: +When an identifier is passed to a REST API endpoint that accepts an `object_identifier`, ThoughtSpot resolves it in the following order: . `obj_id` (user-defined identifier) . GUID . Name -This precedence means you can use `obj_id` anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. +This resolution order enables `obj_id` to be used anywhere a GUID or name is accepted in the REST API v2.0 endpoints that support the `object_identifier` field. Backward compatibility with existing GUID-based and name-based integrations is fully maintained. [NOTE] ==== @@ -74,7 +74,7 @@ This precedence means you can use `obj_id` anywhere a GUID or name is accepted i === Setting and updating obj_id -You can set or update `obj_id` values using the following REST API endpoints: +`obj_id` values can be set or updated using the following REST API endpoints: * `POST /api/rest/2.0/metadata/update-obj-id` + Updates the `obj_id` for one or more metadata objects. Accepts the object's GUID (`metadata_identifier`) or its current `obj_id` (`current_obj_id`). @@ -106,7 +106,7 @@ Or, using the current `obj_id`: } ---- -The request accepts an array, so you can update `obj_id` for multiple objects in a single API call. +The request accepts an array, allowing multiple objects to be updated in a single API call. [NOTE] ==== @@ -116,7 +116,7 @@ Objects are assigned an automatic `obj_id` after the first change to the object For information about using `obj_id` in CI/CD workflows, see xref:deploy-with-tml-apis.adoc[Deploy with TML APIs] and xref:development-and-deployment.adoc[Development and deployment]. == Data modeling -You must create a data model with at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] before you can use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. +A data model requires at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] and one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to use link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] to create content. Most often, there will be multiple *Tables* with a variety of link:https://docs.thoughtspot.com/cloud/latest/tables-join[joins, window=_blank] defined in ThoughtSpot, and a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] that brings those tables together into a presentable analytics model for end users. Data engineers with the *Can manage data* privilege can add connections either link:https://docs.thoughtspot.com/cloud/latest/connections[in the UI, window=_blank] or via xref:connections.adoc[REST API]. Connections are owned and accessible only to their creator, who then imports *Tables* from the connection. Once imported, tables can be shared with other ThoughtSpot groups and users. @@ -141,7 +141,7 @@ ThoughtSpot Search data creates a table or chart view based on the query in the Search data serves the role of report builder or widget designer, while *Liveboards* serve the role of dashboards in other tools. A single search can be saved as a link:https://docs.thoughtspot.com/cloud/latest/answers[*Answer*, window=_blank] object, or the search result can be pinned to a Liveboard. -A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_blank] is a collection of many visualizations presented in a defined layout. You do not create the visualizations on a Liveboard directly; they are created from search data results and then pinned to a Liveboard. You can create a new Liveboard from the *Liveboards* page and then add a visualization from the search data result, or you can create a new Liveboard when pinning an Answer retrieved from search data. +A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_blank] is a collection of visualizations in a defined layout. Visualizations are created from search data results and pinned to a Liveboard; they cannot be created directly within the Liveboard. New Liveboards can be created from the *Liveboards* page and visualizations from search data results added to them, or new Liveboards can be created when pinning an Answer retrieved from search data. === Content creation workflow @@ -151,9 +151,9 @@ To create content: 2. Save the search result as an *Answer* or pin it to a Liveboard as a visualization. === Visualizations on a Liveboard -You can add any number of visualizations from search results to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*. +Any number of visualizations from search results can be added to a Liveboard object. Pinned visualizations exist only within the Liveboard and are independent of objects saved as *Answers*. -Each time you pin a search result, a separate new visualization is created on the Liveboard. +Each time a search result is pinned, a separate new visualization is created on the Liveboard. To edit a visualization on a Liveboard: From 7355110b663befbef5b7fa6341d04f88ead3ad40 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Tue, 18 Aug 2026 12:02:46 +0530 Subject: [PATCH 09/10] split the data report apis --- .../pages/common/nav-in-product-help.adoc | 3 +- modules/ROOT/pages/common/nav-rest-api.adoc | 3 +- modules/ROOT/pages/data-apis-v2.adoc | 334 ++++++++++++++++ modules/ROOT/pages/deprecated-features.adoc | 2 +- ...report-v2-api.adoc => report-apis-v2.adoc} | 374 ++---------------- modules/ROOT/pages/rest-apiv2-changelog.adoc | 10 +- modules/ROOT/pages/spotter-agent-apis.adoc | 4 +- modules/ROOT/pages/whats-new.adoc | 2 +- src/components/SecondaryHeader/index.tsx | 2 +- src/configs/doc-configs.js | 2 +- 10 files changed, 377 insertions(+), 359 deletions(-) create mode 100644 modules/ROOT/pages/data-apis-v2.adoc rename modules/ROOT/pages/{data-report-v2-api.adoc => report-apis-v2.adoc} (53%) diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 73d3dedd9..2d9f1a12c 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -221,7 +221,8 @@ REST APIs *** link:{{navprefix}}/rest-apiv2-users-search[Search users] *** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] *** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/fetch-data-and-report-apis[Data APIs] +** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] *** link:{{navprefix}}/spotter-agent-instructions[Spotter AI agent instructions] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index 3ab94642e..fa8b242f4 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -19,7 +19,8 @@ REST APIs *** link:{{navprefix}}/rest-apiv2-users-search[Search users] *** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] *** link:{{navprefix}}/rest-apiv2-metadata-search[Search metadata] -** link:{{navprefix}}/fetch-data-and-report-apis[Data and Report APIs] +** link:{{navprefix}}/fetch-data-and-report-apis[Data APIs] +** link:{{navprefix}}/report-apis[Report APIs] ** link:{{navprefix}}/runtime-sort[Runtime sorting] ** link:{{navprefix}}/spotter-api[Spotter APIs] *** link:{{navprefix}}/spotter-agent-apis[AI APIs (Spotter Agent and Spotter 3)] diff --git a/modules/ROOT/pages/data-apis-v2.adoc b/modules/ROOT/pages/data-apis-v2.adoc new file mode 100644 index 000000000..bf259489d --- /dev/null +++ b/modules/ROOT/pages/data-apis-v2.adoc @@ -0,0 +1,334 @@ += Data APIs +:toc: true +:toclevels: 3 + +:page-title: data-apis +:page-pageid: fetch-data-and-report-apis +:page-description: Data APIs + +ThoughtSpot provides the following REST API v2 endpoints to fetch data: + +* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. +* xref:#_fetch_liveboard_data_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. +* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. + +If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. + +[NOTE] +To download a Liveboard or Answer as a PDF, PNG, CSV, or XLSX file instead of retrieving its data as JSON, see xref:report-apis-v2.adoc[Report APIs]. + +== Search data API + +The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. + +=== Data source +To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. + +You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. + +To find the GUID of the Model, View, or Table, use one of the following methods: + +Get data object GUID via API:: + +Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + + ++ +.**Example** +[source,JSON] +---- + "metadata": [ + { + "identifier": "my_model", + "type": "LOGICAL_TABLE" + } + ] +---- + ++ +If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. + +Find the GUID of the data object via UI:: +. Log in to your ThoughtSpot application instance: +. Navigate to **Data workspace**. ++ +---- +https:///#/data/tables/ +---- ++ +. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. +. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: ++ +---- +https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f +---- + +. Copy the GUID. + +=== Search query + +include::{path}/search-query-string.adoc[] + +.**Example** +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Authorization: Bearer {access-token} + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "query_string": "[sales][store]", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", +}' +---- + +//// +=== Using tokens generated from Spotter APIs as raw data + +For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. + +==== Request example + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", + "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +}' +---- + +==== API response + +If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. +//// + +== Fetch Liveboard Data API +To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. + +The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. + +=== Liveboard data request example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", + "data_format": "COMPACT", + "visualization_identifiers": [ + "a9655c18-9855-4a73-9e7b-ff4fb6da334b", + "bf4c9814-82c1-4ec4-b879-57eae2134cb4", + "8c46d2b6-94c7-4ba7-a628-6e74e297f973", + "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" + ] +}' +---- + +[#transient-lb-content] +=== Liveboard data with unsaved changes + +include::{path}/transient-lb-content.adoc[] + +.**Sample browser fetch request** + +[source,TypeScript] +---- +const embedRef = useEmbedRef(); + const handleFilterChanged: MessageCallback = () => { + embedRef.current + .trigger(HostEvent.getExportRequestForCurrentPinboard) + .then((transientPinboardContent) => { + console.log(transientPinboardContent.data); + + const payload = { + metadata_identifier: "abc", + data_format: "COMPACT", + record_offset: 0, + record_size: 10, + transient_content: JSON.stringify(transientPinboardContent.data), + }; + + fetch( + `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, + { + method: "POST", + headers: { + Authorization: + "Bearer xxx", + Accept: "application/json", + "Content-Type": "application/json", + }, + body: JSON.stringify(payload), + } + ) + .then((response) => response.json()) + .then(console.log) + .catch(console.log); + }); + }; + + return ( + + ); +---- + +See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. + +To download a Liveboard with unsaved changes as a file, see xref:report-apis-v2.adoc#transient-lb-content-report[Liveboard data with unsaved changes] in the Report APIs documentation. + + +== Fetch Answer Data API + +To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. + +The API request body must include the name or GUID of the saved Answer. + +=== Answer data request example +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ + -H 'Authorization: Bearer {access-token}'\ + -H 'Accept: application/json'\ + -H 'Content-Type: application/json' \ + --data-raw '{ + "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", +}' +---- + +[#pagination] +== Pagination settings for Data APIs + +When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: + +[source,JSON] +---- +{ + "data_format": "COMPACT", + "record_offset": 0, + "record_size": 10 +} +---- + +[WARNING] +==== +Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. +==== + +The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. + +== Runtime overrides +The Data API endpoints and the xref:report-apis-v2.adoc[Report API endpoints] support the following runtime overrides: + +* Runtime filters +* Runtime sorting of columns +* Runtime Parameters + +=== Runtime filters +To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", +} +---- + +To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. + +[source,JSON] +---- +"runtime_filter": { + "col1": "type", + "op1": "EQ", + "val1": "roasted", + "col2": "tea", + "op2": "EQ", + "val2": "barley" +} +---- + +Some operators such as allow more than one value in the `val` parameter: + +[source,JSON] +---- + "runtime_filter": { + "col1": "tea", + "op1": "CONTAINS", + "val1": [ + "barley", + "mint" + ], + "col2": "type", + "op2": "CONTAINS", + "val2": [ + "roasted", + "loose leaves" + ] +} +---- + +For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. + +=== Runtime parameters + +To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. + +To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5 + } +---- + +To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. + +[source,JSON] +---- + "runtime_param_override": { + "param1": "Double List Param", + "paramVal1": 0.5, + "param2": "Date Param", + "paramVal2": 1696932000 + } +---- + +For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. + +=== Runtime sort + +To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. + + +[source,JSON] +---- + "runtime_sort": { + "sortCol1": "sales", + "asc1": true, + "sortCol2": "region", + "asc2": false + } +---- + +For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index d90d833e3..39857dbe9 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -147,7 +147,7 @@ Impact on your instance:: * For new users, API calls to the `POST /api/rest/2.0/report/liveboard` endpoint for PNG exports with `include_cover_page` and `include_filter_page` will result in an error. Use the new PNG export options. //If you still have to use these options for your ThoughtSpot instance contact ThoughtSpot support to revert to these legacy settings. -For more information on PNG export, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. +For more information on PNG export, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. Recommended action:: * We recommend transitioning to the new flow for PNG exports, as the `include_cover_page` and `include_filter_page` attributes will be removed in a future release. diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/report-apis-v2.adoc similarity index 53% rename from modules/ROOT/pages/data-report-v2-api.adoc rename to modules/ROOT/pages/report-apis-v2.adoc index a73d16087..74c50cb30 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/report-apis-v2.adoc @@ -1,224 +1,22 @@ -= Data and Report APIs += Report APIs :toc: true :toclevels: 3 -:page-title: data-apis -:page-pageid: fetch-data-and-report-apis -:page-description: Data and Report APIs +:page-title: report-apis +:page-pageid: report-apis +:page-description: Report APIs -== Data APIs -ThoughtSpot provides the following REST API v2 endpoints to fetch data: +ThoughtSpot provides the following REST API v2 endpoints to download or export data as a file: -* xref:#_search_data_api[`POST /api/rest/2.0/searchdata`] to search data from a given data source. -* xref:#_fetch_liveboard_api[`POST /api/rest/2.0/metadata/liveboard/data`] to get data from a Liveboard. -* xref:#_fetch_answer_data_api[`POST /api/rest/2.0/metadata/answer/data`] to get data from a saved Answer. - -If Role-Based Access Control (RBAC) is enabled, the `DATADOWNLOADING` (Can download Data) privilege is required to use these APIs. Alternatively, if the granular data download RBAC privileges are enabled for your ThoughtSpot instance, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) is required. - -=== Search data API - -The `/api/rest/2.0/searchdata` endpoint requires you to specify the data source object ID and a query string for a successful API call. You can also define additional parameters such as `runtime_filter`, `runtime_sort`, and `runtime_param_override` to apply runtime overrides on the data set. - -==== Data source -To search data via API call, you require at least view access to the data source object. The data source object can be a Model, View, or Table. - -You can specify the data source object GUID in the `logical_table_identifier`. The search data endpoint doesn't support searching data from multiple Models, Views, or Tables in a single API request. - -To find the GUID of the Model, View, or Table, use one of the following methods: - -Get data object GUID via API:: - -Send an API request to the `/api/rest/2.0/metadata/search` endpoint with the following parameters in the metadata array: + - -+ -.**Example** -[source,JSON] ----- - "metadata": [ - { - "identifier": "my_model", - "type": "LOGICAL_TABLE" - } - ] ----- - -+ -If you don't know the exact name of the data source object, specify the metadata `type` as `LOGICAL_TABLE` in your API request, and then copy the GUID of the data object from the API response. - -Find the GUID of the data object via UI:: -. Log in to your ThoughtSpot application instance: -. Navigate to **Data workspace**. -+ ----- -https:///#/data/tables/ ----- -+ -. On the **Data workspace** > **Data objects** page, select the data object. For example, if the data source object is a Model, click **Models** and then open the Model. -. In the address bar of the web browser, note the GUID of the data source object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: -+ ----- -https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f ----- - -. Copy the GUID. - -==== Search query - -include::{path}/search-query-string.adoc[] - -.**Example** -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Authorization: Bearer {access-token} - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "query_string": "[sales][store]", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", -}' ----- - -//// -==== Using tokens generated from Spotter APIs as raw data - -For every natural language query and follow-up question, Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via search data API. - -===== Request example - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/searchdata' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "query_string": "by [city], [product], [item type] = [item type].'\''jackets'\'', [region] = [region].'\''west'\'', sort by sum [sales] descending", - "logical_table_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -}' ----- - -===== API response - -If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. -//// - -=== Fetch Liveboard Data API -To get data from a Liveboard object and its visualizations via `POST /api/rest/2.0/metadata/liveboard/data` endpoint, your user account must have at least view access to the Liveboard specified in the API request. - -The API request body must include the name or GUID of the Liveboard to fetch data. To get specific visualizations from a given Liveboard, add the names or GUIDs of the visualizations in the `visualization_identifiers` array. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "d084c256-e284-4fc4-b80c-111cb606449a", - "data_format": "COMPACT", - "visualization_identifiers": [ - "a9655c18-9855-4a73-9e7b-ff4fb6da334b", - "bf4c9814-82c1-4ec4-b879-57eae2134cb4", - "8c46d2b6-94c7-4ba7-a628-6e74e297f973", - "f6ef5d1f-cddb-4547-8b66-af4d5f4da5ad" - ] -}' ----- - -[#transient-lb-content] -==== Liveboard data with unsaved changes - -include::{path}/transient-lb-content.adoc[] - -.**Sample browser fetch request** - -[source,TypeScript] ----- -const embedRef = useEmbedRef(); - const handleFilterChanged: MessageCallback = () => { - embedRef.current - .trigger(HostEvent.getExportRequestForCurrentPinboard) - .then((transientPinboardContent) => { - console.log(transientPinboardContent.data); - - const payload = { - metadata_identifier: "abc", - data_format: "COMPACT", - record_offset: 0, - record_size: 10, - transient_content: JSON.stringify(transientPinboardContent.data), - }; - - fetch( - `https://{ThoughtSpot-Host}/api/rest/2.0/metadata/liveboard/data`, - { - method: "POST", - headers: { - Authorization: - "Bearer xxx", - Accept: "application/json", - "Content-Type": "application/json", - }, - body: JSON.stringify(payload), - } - ) - .then((response) => response.json()) - .then(console.log) - .catch(console.log); - }); - }; - - return ( - - ); ----- - -See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. - - -=== Fetch Answer Data API - -To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, you need at least view access to the saved Answer. - -The API request body must include the name or GUID of the saved Answer. - -==== Example -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/metadata/answer/data' \ - -H 'Authorization: Bearer {access-token}'\ - -H 'Accept: application/json'\ - -H 'Content-Type: application/json' \ - --data-raw '{ - "metadata_identifier": "f605dbc7-db19-450b-8613-307118f74c3c", -}' ----- - - -== Report APIs - -ThoughtSpot provides the following REST API v2 endpoints to fetch data: - -* xref:_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + +* xref:#_liveboard_report_api[`POST /api/rest/2.0/report/liveboard`] + Download a Liveboard and its visualizations in PDF, PNG, CSV, or XLSX file format. * xref:#_answer_report_api[`POST /api/rest/2.0/report/answer`] + Download data from a saved Answer in PDF, PNG, CSV, or XLSX file format. -=== Liveboard Report API +[NOTE] +To retrieve data as JSON instead of downloading a file, see xref:data-apis-v2.adoc[Data APIs]. + +== Liveboard Report API To download a Liveboard report via `/api/rest/2.0/report/liveboard` API, you need at least view access to the Liveboard specified in the API request. @@ -237,7 +35,7 @@ To download a personalized view of the Liveboard, specify the view name in the ` * If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PDF or PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== -==== File Formats +=== File Formats The default `file_format` is *CSV*. @@ -252,7 +50,7 @@ For *CSV* downloads, * It does not support any additional parameters to customize the page orientation and `include_cover_page`, `include_filter_page`, logo, footer text, and page numbers. * Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. -===== Sample API payload for CSV downloads +==== Sample API payload for CSV downloads [source,cURL] ---- @@ -278,7 +76,7 @@ For *XLSX* downloads, * Charts are exported as tabular data. Downloaded reports may include columns not seen in the visualization if they were used as tokens in the underlying search query. * New pivot tables generated in .xlsx workbooks using this API endpoint retain their complete visual formatting and structural integrity. -===== Sample API payload for XLSX downloads +==== Sample API payload for XLSX downloads [source,cURL] ---- @@ -305,7 +103,7 @@ When `page_size = CONTINUOUS`, the `include_filter_page` option works to show/hi * `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size = CONTINUOUS`. Valid values are integers in the range of 45 and 175. -===== Sample API payload for PDF downloads +==== Sample API payload for PDF downloads [source,cURL] ---- @@ -347,7 +145,7 @@ For *PNG* downloads, you can now define ==== -===== Sample API payload for PNG downloads +==== Sample API payload for PNG downloads [source,cURL] ---- @@ -372,7 +170,7 @@ curl -X POST \ }' ---- -==== Override filters +=== Override filters If the Liveboard has filters applied, and you want to override the filters before downloading the Liveboard, you can specify the filters in the `override_filters` array. @@ -425,12 +223,12 @@ curl -X POST \ }' ---- -[#transient-lb-content] -==== Liveboard data with unsaved changes +[#transient-lb-content-report] +=== Liveboard data with unsaved changes include::{path}/transient-lb-content.adoc[] -===== Sample browser fetch request +==== Sample browser fetch request [source,JavaScript] ---- @@ -454,7 +252,7 @@ include::{path}/transient-lb-content.adoc[] See also, link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_getexportrequestforcurrentpinboard[HostEvent.getExportRequestForCurrentPinboard]. -=== Answer Report API +== Answer Report API To download Answer data via `/api/rest/2.0/report/answer` API, you need at least view access to the saved Answer. @@ -468,7 +266,7 @@ The API supports exporting saved Answers, pinned Answers from a Liveboard, and S * If the granular Role-Based Access Control (RBAC) is enabled, the `CAN_DOWNLOAD_DETAILED_DATA` (Can download detailed data) privilege is required to export in the PDF, XLSX or CSV formats, and the `CAN_DOWNLOAD_VISUALS` (Can download visuals) privilege is required for PNG exports. In this case the `DATADOWNLOADING` privilege ceases to exist. ==== -==== Example +=== Example [source,cURL] ---- @@ -525,12 +323,12 @@ Valid range: `80%` to `500%`. You can now export the PNG of any Answer in any aspect ratio and any scaling or zoom level. Just configure, scale, and export exactly what you need. [#exportSpotterData] -==== Export data generated from Spotter APIs +=== Export data generated from Spotter APIs To export results generated from Spotter APIs such as `/api/rest/2.0/ai/answer/create`, `/api/rest/2.0/ai/agent/converse/sse`, and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse`, include the session ID and generation number in the `POST` request body. When downloading a Spotter-generated Answer, do not specify the metadata object ID, because you will be exporting the data generated from a conversation session with Spotter and not a saved Answer. -===== Request example +==== Request example [source,cURL] ---- @@ -549,12 +347,12 @@ curl -X POST \ * `generation_number` indicates the Answer generation number. * `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG, CSV, XLSX, or PDF file. By default, the API exports this data in PNG file format. -===== API Response +==== API Response If the API request is successful, ThoughtSpot returns the data in the specified file format. You can download the file to use it later or import it into your application environment. //// -===== Response codes +==== Response codes [width="100%" cols="2,4"] [options='header'] |=== @@ -567,124 +365,8 @@ If the API request is successful, ThoughtSpot returns the data in the specified |=== //// -== Pagination settings for Data APIs - -When you make REST API calls to some v2 Data endpoints to query data, the API may return many rows of data in response. By default, the following parameters are set in API requests to the v2 Data API endpoints: - -[source,JSON] ----- -{ - "data_format": "COMPACT", - "record_offset": 0, - "record_size": 10 -} ----- - -[WARNING] -==== -Do not set `record_size` to `-1`. On ThoughtSpot instances with a large number of objects or users, this can lead to slow responses, excessive logging, and out-of-memory failures. Specify an explicit `record_size` and iterate through pages programmatically. -==== - -The APIs return a maximum of 100000 rows of data at any given time. If you must retrieve a higher number of rows in an API call, contact ThoughtSpot Customer Support to increase the row size limit. However, if the record size and number of rows are high, the API may take a while to fetch the data, and the request may time out. - -== Runtime overrides -The Data API endpoints support the following runtime overrides: - -* Runtime filters -* Runtime sorting of columns -* Runtime Parameters - -=== Runtime filters -To add runtime filters, in the `runtime_filter` property, add the `col1`, `op1`, and `val1` parameters JSON key-value format: - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", -} ----- - -To add additional filters, increment the number at the end of each parameter for each filter: for example, col2, op2, val2, and so on. - -[source,JSON] ----- -"runtime_filter": { - "col1": "type", - "op1": "EQ", - "val1": "roasted", - "col2": "tea", - "op2": "EQ", - "val2": "barley" -} ----- - -Some operators such as allow more than one value in the `val` parameter: - -[source,JSON] ----- - "runtime_filter": { - "col1": "tea", - "op1": "CONTAINS", - "val1": [ - "barley", - "mint" - ], - "col2": "type", - "op2": "CONTAINS", - "val2": [ - "roasted", - "loose leaves" - ] -} ----- - -For more information, see xref:runtime-filters.adoc#rtOperator[Supported runtime filter operators] and xref:runtime-filters.adoc#_rest_api_v2_0_endpoints[Apply runtime filters via REST APIs]. - -=== Runtime parameters - -To add runtime Parameters, in the `runtime_param_override` property, add the `param1, and `paramVal1` parameters JSON key-value format. The Parameter value must be defined as per the data type. For example, `Date Param` and `Date List Param` Parameters, specify Epoch time as value. - -To apply Parameter overrides on Liveboards and Answers, ensure that the Parameters are configured in the Model used for generating Liveboard visualizations and Answer. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5 - } ----- - -To add additional Parameter overrides, increment the number at the end of each parameter: for example, paramVal2, and so on. - -[source,JSON] ----- - "runtime_param_override": { - "param1": "Double List Param", - "paramVal1": 0.5, - "param2": "Date Param", - "paramVal2": 1696932000 - } ----- - -For more information, see xref:runtime-parameters.adoc[Runtime Parameter overrides]. - -=== Runtime sort - -To sort columns on a Liveboard or Answer, define runtime sort properties in `runtime_sort` as a key-value pair in JSON format. The `runtime_sort` object allows `sortCol1` and `asc1` properties. To sort more columns, increment the number at the end of the parameter for each key: for example, `sortCol2`, `asc2`, `sortCol3`, `asc3`, and so on. - - -[source,JSON] ----- - "runtime_sort": { - "sortCol1": "sales", - "asc1": true, - "sortCol2": "region", - "asc2": false - } ----- - -For more information, see xref:runtime-sort.adoc#_rest_api_v2_0[Runtime sorting of columns]. +== Pagination and runtime overrides +The Report API endpoints support the same runtime overrides as the Data API endpoints. For more information, see xref:data-apis-v2.adoc#_runtime_overrides[Runtime overrides]. +For information about pagination, record size, and the maximum row limit that apply to the Data API endpoints, see xref:data-apis-v2.adoc#pagination[Pagination settings for Data APIs]. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index 22e0cfcaf..bd72e1316 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -217,7 +217,7 @@ Automatic file naming:: The API now automatically names exported files based on the Answer title and appends the correct file extension (`.png`, `.pdf`, `.csv`, or `.xlsx`). Contact ThoughtSpot Support to enable these settings for PNG downloads on your ThoughtSpot instance. -For more information, see xref:data-report-v2-api.adoc#_answer_report_api[Answer report API documentation]. +For more information, see xref:report-apis-v2.adoc#_answer_report_api[Answer report API documentation]. === Share metadata API: Collections support [beta betaBackground]^Beta^ @@ -288,7 +288,7 @@ The `POST /api/rest/2.0/report/liveboard` API endpoint enhances the PDF download * `"page_size": "CONTINUOUS"` for a seamless PDF export that matches the full length of your Liveboard. Unlike the A4 format, which introduces forced page breaks between visualizations, this continuous flow maintains your exact design and intended layout. * `zoom_level` offers various download size options to suit the viewer's screen dimensions, thereby enhancing legibility. This can be set only when `page_size` is specified as `CONTINUOUS`. -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API documentation]. +For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API documentation]. === Metadata search API enhancements @@ -445,7 +445,7 @@ The `same_as_parent` parameter specifies if the configuration should inherit set === Liveboard Report API enhancements You can now download Liveboard reports in the CSV and XLSX formats through the `POST /api/rest/2.0/report/liveboard` API endpoint. Both these options are Early Access features. -For more information, see xref:data-report-v2-api.adoc[Data and Report APIs]. +For more information, see xref:report-apis-v2.adoc[Report APIs]. === Email customization API enhancements @@ -752,7 +752,7 @@ In addition to these parameters, you can also define the following properties fo * `image_scale` * `include_header` -For more information, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard Report API]. +For more information, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard Report API]. === REST API Java SDK @@ -794,7 +794,7 @@ Filters metadata objects by the user-defined object ID. This parameter returns d === Report APIs The Liveboard export API (`/api/rest/2.0/report/liveboard`) now allows overriding filters applied to a Liveboard. The `override_filters` array allows specifying several types of filters and updates the Liveboard data during export. -For more information, see xref:data-report-v2-api.adoc#_override_filters[Override filters]. +For more information, see xref:report-apis-v2.adoc#_override_filters[Override filters]. == Version 10.6.0.cl, March 2025 diff --git a/modules/ROOT/pages/spotter-agent-apis.adoc b/modules/ROOT/pages/spotter-agent-apis.adoc index 5ea2587af..caea17b5e 100644 --- a/modules/ROOT/pages/spotter-agent-apis.adoc +++ b/modules/ROOT/pages/spotter-agent-apis.adoc @@ -1083,7 +1083,7 @@ If the conversation session is not found or has expired, the API returns an erro [#process_results] == Process results generated from a conversation session -To export or download the Answer data generated by the Spotter APIs, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API. +To export or download the Answer data generated by the Spotter APIs, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API. The `session_id` and `gen_no` values from the `answer` event metadata are required to identify the answer to export. @@ -1106,7 +1106,7 @@ The `file_format` parameter accepts `PDF`, `PNG`, `CSV`, or `XLSX`. [NOTE] ==== -Using tokens generated by the Spotter API in a xref:data-report-v2-api.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:data-report-v2-api.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. +Using tokens generated by the Spotter API in a xref:data-apis-v2.adoc#_search_data_api[Search Data API] request can return invalid column errors, because these tokens may reference formulas or columns not present in the data model. Instead, use the xref:report-apis-v2.adoc#exportSpotterData[Answer report] API and include the session ID and generation number obtained from the Spotter API in your API request to retrieve the data. ==== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56a89557d..c0cec74b8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -443,7 +443,7 @@ Current period inclusion in rolling date filters:: The rolling date filters with the **Last ** and **Next ** filter types support including current period. Developers can disable, show, or hide this option using `isThisPeriodInDateFiltersEnabled` or `Action.IncludeCurrentPeriod`. Liveboard PNG export:: -The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:data-report-v2-api.adoc#_liveboard_report_api[Liveboard report API documentation]. +The PNG export workflow in the `/api/rest/2.0/report/liveboard` REST API is enhanced to provide high-resolution PNG files. The legacy PNG workflow is deprecated in 26.4.0.cl. For more information about breaking changes and deprecation guidelines, see xref:deprecated-features.adoc[Deprecation announcements]. For information about the new PNG download workflow, see xref:report-apis-v2.adoc#_liveboard_report_api[Liveboard report API documentation]. --- diff --git a/src/components/SecondaryHeader/index.tsx b/src/components/SecondaryHeader/index.tsx index 42361b8d3..e472489b4 100644 --- a/src/components/SecondaryHeader/index.tsx +++ b/src/components/SecondaryHeader/index.tsx @@ -102,7 +102,7 @@ export const CATEGORY_PAGEIDS: Record = { 'collections', 'connections', 'connection-config', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', 'rest-apiv2-metadata-search', - 'fetch-data-and-report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', + 'fetch-data-and-report-apis', 'report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', 'rest-api-getstarted', 'api-auth-session', 'catalog-and-audit', 'rest-api-pagination', 'runtime-sort', 'v1v2-comparison', 'graphql-guide', 'webhooks-rest-api', 'rest-v2-changelog', 'rest-v1-changelog', diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 19ebabe2b..d5e37c73f 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -117,7 +117,7 @@ module.exports = { 'rest-api-v2', 'rest-apiv2-reference', 'restV2-playground', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', - 'rest-apiv2-metadata-search', 'fetch-data-and-report-apis', + 'rest-apiv2-metadata-search', 'fetch-data-and-report-apis', 'report-apis', 'rest-api-sdk', 'rest-api-sdk-typescript', 'rest-api-sdk-java', 'rest-api-getstarted', 'api-auth-session', 'catalog-and-audit', 'rest-api-pagination', 'runtime-sort', 'v1v2-comparison', From e1bfe2a79e8a35e9b973a6a1e15826008b8ba9f2 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Wed, 19 Aug 2026 17:25:51 +0530 Subject: [PATCH 10/10] split the tml file --- .../pages/common/nav-in-product-help.adoc | 2 + modules/ROOT/pages/common/nav-rest-api.adoc | 2 + modules/ROOT/pages/open-issues.adoc | 2 +- modules/ROOT/pages/rest-apiv2-changelog.adoc | 6 +- modules/ROOT/pages/tml-export.adoc | 83 +++ modules/ROOT/pages/tml-import.adoc | 413 +++++++++++++++ modules/ROOT/pages/tml.adoc | 487 +----------------- modules/ROOT/pages/whats-new.adoc | 2 +- src/components/SecondaryHeader/index.tsx | 1 + src/configs/doc-configs.js | 2 +- 10 files changed, 511 insertions(+), 489 deletions(-) create mode 100644 modules/ROOT/pages/tml-export.adoc create mode 100644 modules/ROOT/pages/tml-import.adoc diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 2d9f1a12c..2f6f8dd4e 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -233,6 +233,8 @@ REST APIs ** link:{{navprefix}}/style-customization-apis[Style customization APIs] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] +*** link:{{navprefix}}/tml-import[Import TML] +*** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] diff --git a/modules/ROOT/pages/common/nav-rest-api.adoc b/modules/ROOT/pages/common/nav-rest-api.adoc index fa8b242f4..a01e7dbcc 100644 --- a/modules/ROOT/pages/common/nav-rest-api.adoc +++ b/modules/ROOT/pages/common/nav-rest-api.adoc @@ -31,6 +31,8 @@ REST APIs *** link:{{navprefix}}/spotter-nl-instructions[Data model instructions APIs ^BETA^] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] +*** link:{{navprefix}}/tml-import[Import TML] +*** link:{{navprefix}}/tml-export[Export TML] ** link:{{navprefix}}/collections[Collections] ** link:{{navprefix}}/connections[Connections] ** link:{{navprefix}}/connection-config[Connection configuration] diff --git a/modules/ROOT/pages/open-issues.adoc b/modules/ROOT/pages/open-issues.adoc index 37d91ef2c..718fc29f6 100644 --- a/modules/ROOT/pages/open-issues.adoc +++ b/modules/ROOT/pages/open-issues.adoc @@ -78,7 +78,7 @@ On exporting and reimporting TML in YAML format in the REST API v2 Playground, t This issue occurs because when reimporting TML invalid characters are added to the TML YAML content in the Playground resulting in an invalid syntax error. **Workaround**: + -See xref:tml.adoc#yamlReimport[YAML reimport in the REST API v2 Playground]. +See xref:tml-import.adoc#yamlReimport[YAML reimport in the REST API v2 Playground]. |===== diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index bd72e1316..f21342428 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -30,7 +30,7 @@ Two new fields have been added to the TML for Personalized Views. You can see th * A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. * Personalized Views now carry an `obj_id` field for stable cross-environment object identity, consistent with other object types. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability in TML]. +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability in TML]. Collections `obj_id` support::: // SOURCE: SCAL-317357 @@ -863,7 +863,7 @@ Allows you to specify if all objects should be imported during the TML import op * `enable_large_metadata_validation` + Indicates if the TMLs with large and complex metadata should be validated before the import. + -For more information about these attributes, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. +For more information about these attributes, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. TML import API:: @@ -925,7 +925,7 @@ Validates and imports TML objects asynchronously. Use this API endpoint when imp * `POST /api/rest/2.0/metadata/tml/async/status` + Fetches task status for the async TML import operations. -For more information, see xref:tml.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. +For more information, see xref:tml-import.adoc#_import_tml_objects_asynchronously[Import TML objects asynchronously]. === API enhancements diff --git a/modules/ROOT/pages/tml-export.adoc b/modules/ROOT/pages/tml-export.adoc new file mode 100644 index 000000000..bdaf32488 --- /dev/null +++ b/modules/ROOT/pages/tml-export.adoc @@ -0,0 +1,83 @@ += Export TML +:toc: true +:toclevels: 2 + +:page-title: Export TML +:page-pageid: tml-export +:page-description: Export the TML representation of ThoughtSpot metadata objects via REST API +// SOURCE: SCAL-307283, SCAL-317357 + +[#export-tml] +To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. + +The default format to export the objects is YAML in 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: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) +* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) + +To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: + +* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) +* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) + +There are several export options available with these APIs: + +== Metadata specification for Answers +To export a specific metadata object, specify the name or ID of the object. + +For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. + +== Export associated objects + +To export associated objects, set the following attributes: + +* `export_associated` + +When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, 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, Model, 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 Model. +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 Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. +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. + +For more information about using FQNs during import, see xref:tml-import.adoc#import-tml[Import TML]. + +== Export schema + +Specifies the schema version to use during TML export. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. +The v1 schema is used for Worksheet objects (Deprecated). + +== Additional export options for REST API v2 +Following are some additional attributes which can be set for exporting objects: + +* `include_obj_id_ref` + +When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. + +* `include_guid` + +When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `include_obj_id` + +When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. +* `export_with_associated_feedbacks` + +When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object +* `export_column_security_rules` [beta betaBackground]^Beta^ + +When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. +* `export_with_column_aliases` [beta betaBackground]^Beta^ + +When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. + +== Export in a batch +This API operation supports exporting User, User Group, and Role objects only. +To export objects in a batch, set the following additional attributes: + +* `batch_size` + +Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. + +* `batch_offset` + +Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. + +For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. diff --git a/modules/ROOT/pages/tml-import.adoc b/modules/ROOT/pages/tml-import.adoc new file mode 100644 index 000000000..562ae15f7 --- /dev/null +++ b/modules/ROOT/pages/tml-import.adoc @@ -0,0 +1,413 @@ += Import TML +:toc: true +:toclevels: 2 + +:page-title: Import TML +:page-pageid: tml-import +:page-description: Import the TML representation of ThoughtSpot metadata objects via REST API +// SOURCE: SCAL-307283, SCAL-317357 + +[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-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 xref:tml-export.adoc#_export_fqns[export TML with FQNs] and use it during the import. + +You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. + +To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: + +* +++POST /api/rest/2.0/metadata/tml/import+++ (REST API v2) +* xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) + +//While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. + +There are multiple kinds of imports possible: + +* `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. +* `PARTIAL_OBJECT` (only applicable to REST API v2) +imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. + +You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. + +[NOTE] +==== +If you import only a Model object, it may take some time for the Model 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 Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. +==== + +[#personalized-views-portability] +== Personalized Views portability [earlyAccess eaBackground]#Early Access# + +Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. + +To enable this feature for your instance, contact your ThoughtSpot administrator. + +Two new fields are added to the TML, make it easier to migrate Personalized Views between environments without creating duplicates. + +`author`::: +A new `author` field is added to the Personalized View TML during export. This field is used to delegate ownership to another user during import. + +`obj_id`::: +A new `obj_id` field provides stable cross-environment object identity for inter-Org deployments. Use the same `obj_id` value across environments to ensure consistent identity during migrations. + + + +=== Example for a Personalized View TML with Object ID + +[source,yaml] +---- + views: + - view_guid: ff83055b-a867-43e7-978e-106e907e1912 + obj_id: California-LT-ff83855b + name: California - LT + view_filters: + - column: + - Retail Sales - Classic::Store State + oper: in + values: + - California + is_public: false + author: + username: user1 + user_email: user1@thoughtspot.com +---- + +=== Limitation without this feature enabled + +ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/personalized-liveboard-views[personalized Liveboard views] let users apply filters and save configurations as named views on a Liveboard. +In multi-environment deployments (for example, a Dev instance and a Prod instance), these user-saved views can be lost when a Liveboard is updated and re-imported using the xref:#import-tml[TML import API] or the UI *Import TML* option. +If the import is performed by an administrator account, all personalized views saved by end users are removed as part of this replacement. + +Why this happens?:: + +Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. ++ +This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. + +Workarounds:: +. Import as a non-admin user - ++ +The simplest workaround is to perform the final TML import in the production environment using a *non-admin user account* that has edit access to the Liveboard, rather than an admin account. +Because non-admin users do not have the authority to overwrite user-linked metadata during import, ThoughtSpot preserves the existing personalized views attached to the Liveboard. +. Embed existing saved views in the TML before import - ++ +You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. + +== Import TML objects asynchronously +The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. + +To allow mutually exclusive import tasks to run in parallel, process TML objects asynchronously, and check import task status, ThoughtSpot provides the following APIs: + +* +++POST /api/rest/2.0/metadata/tml/async/import+++ + +Creates an import TML tasks and processes TMLs asynchronously + +* +++POST /api/rest/2.0/metadata/tml/async/status+++ + +Fetches status of import tasks + +=== Schedule import tasks + +You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: + +[width="100%" cols="2,4,1"] +[options='header'] +|==== +|Form parameter|Description| Default +|`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ +|`create_new` + +__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` +|`all_orgs_context` + +__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. + +__Requires Org administration privileges to access TML objects across all Orgs.__| `false` + +|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: + +* `PARTIAL` + +Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. +* `ALL_OR_NONE` + +Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. +* `VALIDATE_ONLY` + +Validates the objects but does not import them. +* `PARTIAL_OBJECT` + +Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. +| `PARTIAL_OBJECT` + +|`skip_diff_check` + +__Optional__ +|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` +|`enable_large_metadata_validation` + +__Optional__ + |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). +|`false` +|==== +//// + + +|`skip_cdw_validation_for_tables` + +__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` +//// +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_tmls": [ + "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" + ], + "create_new": true, + "all_orgs_context": false, +}' +---- + +==== Example response + +If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: + +[source,JSON] +---- +{ + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "075c322f-b000-4776-9c44-89e13420980c", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": null, + "task_status": "IN_QUEUE", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": null, + "in_progress_at": null, + "completed_at": null, + "total_object_count": 2, + "object_processed_count": null, + "modified_at": null, + "author_display_name": "UserA" +} +---- + +===== Response codes + +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML Import Task submitted successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error +|==== + +=== Fetch status of the TML import task + +To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. + +In the request body, include the following attributes: + +[width="100%" cols="2,4,1"] +[options='header'] +|==== +|Form parameter|Description| Default +|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ +| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + + +* `COMPLETED` + +* `IN_QUEUE` + +* `IN_PROGRESS` + +* `FAILED` +| __None__ +|`author_identifier` + +__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ +|`include_import_response` + +__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` +|`record_offset` + +__Optional__ |__Integer__. The offset point, starting from where the task status should +be included in the response. | `0` +|`record_size` + +__Optional__ a|__Integer__. The number of task statuses to include in the +response starting from offset position. + +[NOTE] +==== +The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. +==== +| `5` + +|==== + +[IMPORTANT] +==== +You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. +==== + +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "record_offset": 0, + "record_size": 5, + "include_import_response": true, + "task_ids": [ + "c8c8c4da-0bc8-4460-8039-cfa7fd598335" + ], + "task_status": [ + "COMPLETED" + ], + "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" +}' +---- + +==== Example response + +If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. +If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. + +[source,JSON] +---- +{ + "status_list": [ + { + "tenant_id": "default-tenant-id", + "org_id": 0, + "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", + "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", + "import_response": { + "object": [ + { + "filename": "tml_0", + "zip_filename": "zip_tml_0", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 0 + }, + { + "filename": "tml_1", + "zip_filename": "zip_tml_1", + "response": { + "status": { + "status_code": "ERROR", + "error_message": "Invalid YAML/JSON syntax in file." + } + }, + "request_index": 1 + } + ], + "status": { + "status_code": "OK", + "error_code": 0, + "error_message": "" + } + }, + "task_status": "COMPLETED", + "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", + "import_policy": "PARTIAL_OBJECT", + "created_at": 1732601184212, + "in_progress_at": 1732601184255, + "completed_at": 1732601184476, + "total_object_count": 2, + "object_processed_count": 2, + "modified_at": 1732601184476, + "author_display_name": "UserA" + } + ], + "last_batch": true +} +---- + +===== Response codes + +[options="header", cols="1,4"] +|==== +|HTTP status code|Description +|**200**|Async TML import task status fetched successfully +|**400**|Invalid request +|**401**|Unauthorized access +|**403**|Forbidden access +|**500**|Unexpected Error +|==== + +[#yamlReimport] +== 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. + ++ + +[div videoContainer] +-- +video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] +-- ++ +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: ++ +[source,JSON] +---- +{ + "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 other TML. ++ +[source,JSON] +---- +{ + "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. ++ + +[div videoContainer] +-- +video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] +-- diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 127583da2..c0451c9c9 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -40,494 +40,16 @@ Worksheets are deprecated in ThoughtSpot and replaced by Models from 10.12.0.cl 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 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. - -You can also set the `skip_diff_check` to `true` to skip diff check before processing TMLs for imports. This attribute helps identify the objects that haven’t been changed since the last import or TML update, and eliminates importing redundant objects. - -To import TML representation of the metadata objects into ThoughtSpot, use one of the following API endpoints: - -* +++POST /api/rest/2.0/metadata/tml/import+++ (REST API v2) -* xref:tml-api.adoc#import[POST /tspublic/v1/metadata/tml/import] (REST API v1) - -//While the v1 API accepts a string containing a JSON array of TML objects to upload, in YAML or JSON format, the v2 accepts it only in the JSON format. - -There are multiple kinds of imports possible: - -* `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. -* `PARTIAL_OBJECT` (only applicable to REST API v2) -imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. - -You can also specify additional parameters to set the Org context and skip CDW validation checks for Table TMLs. - -[NOTE] -==== -If you import only a Model object, it may take some time for the Model 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 Model along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. -==== - -[#personalized-views-portability] -=== Personalized Views portability [earlyAccess eaBackground]#Early Access# - -Personalized Views support improved portability across ThoughtSpot environments. When importing a Personalized View TML set the `enable_personalized_view_upsert` to `true` in the API request to `POST /api/rest/2.0/metadata/tml/import`. ThoughtSpot then checks the target environment for an existing Personalized View with a matching `obj_id`. If a match is found, the import updates the existing view rather than creating a duplicate. If no match is found, a new Personalized View is created. - -To enable this feature for your instance, contact your ThoughtSpot administrator. - -Two new fields are added to the TML, make it easier to migrate Personalized Views between environments without creating duplicates. - -`author`::: -A new `author` field is added to the Personalized View TML during export. This field is used to delegate ownership to another user during import. - -`obj_id`::: -A new `obj_id` field provides stable cross-environment object identity for inter-Org deployments. Use the same `obj_id` value across environments to ensure consistent identity during migrations. - - - -==== Example for a Personalized View TML with Object ID - -[source,yaml] ----- - views: - - view_guid: ff83055b-a867-43e7-978e-106e907e1912 - obj_id: California-LT-ff83855b - name: California - LT - view_filters: - - column: - - Retail Sales - Classic::Store State - oper: in - values: - - California - is_public: false - author: - username: user1 - user_email: user1@thoughtspot.com ----- - -==== Limitation without this feature enabled - -ThoughtSpot's link:https://docs.thoughtspot.com/cloud/latest/personalized-liveboard-views[personalized Liveboard views] let users apply filters and save configurations as named views on a Liveboard. -In multi-environment deployments (for example, a Dev instance and a Prod instance), these user-saved views can be lost when a Liveboard is updated and re-imported using the xref:tml.adoc[TML import API] or the UI *Import TML* option. -If the import is performed by an administrator account, all personalized views saved by end users are removed as part of this replacement. - -Why this happens?:: - -Personalized views are stored as user-owned objects linked to the Liveboard’s GUID. When an admin imports a Liveboard TML that matches an existing GUID, the import operation overwrites the Liveboard, and the associated user views are not carried forward. -+ -This happens because personalized views are created and usually owned by end users in a different environment (likely a Prod instance). They are not included in Liveboard TML files exported from a development or staging environment, so the import has no record of them. - -Workarounds:: -. Import as a non-admin user - -+ -The simplest workaround is to perform the final TML import in the production environment using a *non-admin user account* that has edit access to the Liveboard, rather than an admin account. -Because non-admin users do not have the authority to overwrite user-linked metadata during import, ThoughtSpot preserves the existing personalized views attached to the Liveboard. -. Embed existing saved views in the TML before import - -+ -You can export the current saved views from the production Liveboard, append them to the updated TML, and then import the combined TML. - -== Import TML objects asynchronously -The REST v1 and v2 `metadata/tml/import` APIs import TML objects synchronously. When you try to import large and complex metadata objects, the synchronous import operation takes more time to process data and sometimes can result in a timeout error. - -To allow mutually exclusive import tasks to run in parallel, process TML objects asynchronously, and check import task status, ThoughtSpot provides the following APIs: - -* +++POST /api/rest/2.0/metadata/tml/async/import+++ + -Creates an import TML tasks and processes TMLs asynchronously - -* +++POST /api/rest/2.0/metadata/tml/async/status+++ + -Fetches status of import tasks - -=== Schedule import tasks - -You can import TML objects asynchronously by scheduling TML import tasks via `POST` request to POST `/api/rest/2.0/metadata/tml/async/import` API endpoint. You can send the following parameters in the API request body: - -[width="100%" cols="2,4,1"] -[options='header'] -|==== -|Form parameter|Description| Default -|`metadata_tmls` |__Array of strings__. Array of the TML strings. |__None__ -|`create_new` + -__Optional__ |__Boolean__. To create TML objects with new GUIDs during import, specify `true`. By default, ThoughtSpot updates the existing objects that have the same GUID as the objects you are importing. | `false` -|`all_orgs_context` + -__Optional__ |__Boolean__. Specify if import operation must be run for all Orgs on your instance. - -__Requires Org administration privileges to access TML objects across all Orgs.__| `false` - -|`import_policy` a|__String__. Available from 10.5.0.cl. Policy to follow during import. The allowed values are: - -* `PARTIAL` + -Imports objects that validate successfully. Skips the objects that do not validate successfully and their dependent objects if any. -* `ALL_OR_NONE` + -Imports all objects that validate successfully. If the import fails for one object, no objects will be imported. -* `VALIDATE_ONLY` + -Validates the objects but does not import them. -* `PARTIAL_OBJECT` + -Imports objects that validate successfully and skips the objects that do not validate successfully. If the import fails for a visualization object in a Liveboard TML, the Liveboard will be imported without that visualization object. Similarly, if importing a relationship in a logical table fails, the table TML will be imported with warnings in the API response. -| `PARTIAL_OBJECT` - -|`skip_diff_check` + -__Optional__ -|__Boolean__. When set to `true`, skips the diff check before processing TML objects for import. By default, ThoughtSpot compares each TML object against its last imported version and skips objects that have not changed, which reduces unnecessary reimports. Set to `true` to bypass this check and reimport all objects regardless of whether they have changed. |`false` -|`enable_large_metadata_validation` + -__Optional__ - |__Boolean__. Available from 10.5.0.cl. Enables validation for large metadata objects. Set to `true` if the database contains multiple thousands of tables. When enabled, it allows for schema validation of one table at a time and helps circumvent the metadata fetching limitations of the Cloud Data Warehouse (CDW). -|`false` -|==== -//// - - -|`skip_cdw_validation_for_tables` + -__Optional__ |__Boolean__. Skips Cloud Data Warehouse validation for table TML imports. | `false` -//// -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/import' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "metadata_tmls": [ - "{\\\"guid\\\": \\\"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\\\",\\\"liveboard\\\": {\\\"name\\\": \\\"Total Sales\\\",\\\"visualizations\\\": [{\\\"id\\\": \\\"Viz_1\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total quantity purchased, Total sales by region\\\",\\\"description\\\": \\\"test\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[region] [quantity purchased] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total quantity purchased\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"region\\\",\\\"Total quantity purchased\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total quantity purchased\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"region\\\"],\\\"y\\\": [\\\"Total quantity purchased\\\",\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"f6701821-5630-49cd-b26f-f98bebb4e98e\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total quantity purchased\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"1e086aef-236d-4cf0-8909-9e04e04a1ac4\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": true}},{\\\\\\\"id\\\\\\\": \\\\\\\"7be648d3-c791-43e4-bb13-63fea808f326\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"region\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total quantity purchased\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"b8b38851-5980-40a1-bd88-608b7a9c6e86\\\"},{\\\"id\\\": \\\"Viz_2\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales in a year\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [store] [date].monthly [date].'\''this year'\''\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Month(date)\\\"},{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"store\\\",\\\"Month(date)\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"LINE\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Month(date)\\\"},{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"Month(date)\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"store\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"feb33c4a-614b-4623-9d12-1c4cf2250801\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"e89293cb-d10a-40d5-b787-81be33cc8b81\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Month(date)\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"6a4acb32-9036-4d4c-a830-f2b06966a322\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"39e5242e-43d0-4ef7-8673-73b12433e0c5\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (85226)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"arizona (86001)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (91006)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"california (94702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80301)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#8C62F5\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"colorado (80920)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FF8142\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06110)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#ABC7F9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"connecticut (06854)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B5ECF2\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"delaware (19702)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FDE9AF\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30022)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#9BE5CB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"georgia (30329)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#D1C0FB\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"idaho (83704)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFCCB3\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60062)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2359B6\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"illinois (60642)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#369FAA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"indiana (46250)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#BF982A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"iowa (50266)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#049160\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"maryland (21045)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#6A4ABA\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (01701)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#C26232\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"massachusetts (02215)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (48103)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#82DFE9\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"michigan (49512)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCD977\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55369)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#56D3A8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"minnesota (55420)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#B094F8\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"missouri (63144)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FFA97E\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59106)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#163772\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"montana (59718)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#22636B\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89052)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#785F1A\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"nevada (89145)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#025B3C\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new hampshire (03860)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#422E75\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"new jersey (07936)\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#7A3D1F\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"7efc7b0e-e680-44a4-ba9c-3bd5d7272367\\\"},{\\\"id\\\": \\\"Viz_3\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by item type and region\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[sales] [item type] [region]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"item type\\\"},{\\\"name\\\": \\\"region\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"item type\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"region\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"item type\\\",\\\"region\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"STACKED_COLUMN\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"item type\\\"},{\\\"column_id\\\": \\\"region\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"item type\\\"],\\\"y\\\": [\\\"Total sales\\\"],\\\"color\\\": [\\\"region\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"responsiveLayoutPreference\\\\\\\": \\\\\\\"AUTO_ON\\\\\\\",\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"a330db6d-3714-4b5f-aed7-cca5ab679502\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"96ac1ce3-7efd-455e-a569-2cd0792b5f95\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"item type\\\\\\\"]}}],\\\\\\\"systemSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"92153012-664c-458e-9a74-6138c5030838\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"east\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#06BF7F\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"midwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#FCC838\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"south\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#48D1E0\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"southwest\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#71A1F4\\\\\\\"},{\\\\\\\"serieName\\\\\\\": \\\\\\\"west\\\\\\\",\\\\\\\"color\\\\\\\": \\\\\\\"#2E75F0\\\\\\\"}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"9de47a0e-6f20-40ba-9a52-3374ee530f09\\\"},{\\\"id\\\": \\\"Viz_4\\\",\\\"answer\\\": {\\\"name\\\": \\\"Total sales by state\\\",\\\"tables\\\": [{\\\"id\\\": \\\"(Sample) Retail - Apparel\\\",\\\"name\\\": \\\"(Sample) Retail - Apparel\\\"}],\\\"search_query\\\": \\\"[state] [store] [sales]\\\",\\\"answer_columns\\\": [{\\\"name\\\": \\\"Total sales\\\"},{\\\"name\\\": \\\"state\\\"},{\\\"name\\\": \\\"store\\\"}],\\\"table\\\": {\\\"table_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"state\\\",\\\"show_headline\\\": false},{\\\"column_id\\\": \\\"store\\\",\\\"show_headline\\\": false}],\\\"ordered_column_ids\\\": [\\\"state\\\",\\\"store\\\",\\\"Total sales\\\"],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"tableVizPropVersion\\\\\\\": \\\\\\\"V1\\\\\\\"}\\\"},\\\"chart\\\": {\\\"type\\\": \\\"GEO_AREA\\\",\\\"chart_columns\\\": [{\\\"column_id\\\": \\\"Total sales\\\"},{\\\"column_id\\\": \\\"state\\\"},{\\\"column_id\\\": \\\"store\\\"}],\\\"axis_configs\\\": [{\\\"x\\\": [\\\"state\\\"],\\\"y\\\": [\\\"Total sales\\\"]}],\\\"client_state\\\": \\\"\\\",\\\"client_state_v2\\\": \\\"{\\\\\\\"version\\\\\\\": \\\\\\\"V4DOT2\\\\\\\",\\\\\\\"chartProperties\\\\\\\": {\\\\\\\"chartSpecific\\\\\\\": {}},\\\\\\\"axisProperties\\\\\\\": [{\\\\\\\"id\\\\\\\": \\\\\\\"e4943da4-f159-470c-836b-7c6c55d59c2f\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"Y\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"Total sales\\\\\\\"],\\\\\\\"isOpposite\\\\\\\": false}},{\\\\\\\"id\\\\\\\": \\\\\\\"b99d582a-b215-4381-89ad-280c451979e3\\\\\\\",\\\\\\\"properties\\\\\\\": {\\\\\\\"axisType\\\\\\\": \\\\\\\"X\\\\\\\",\\\\\\\"linkedColumns\\\\\\\": [\\\\\\\"state\\\\\\\"]}}],\\\\\\\"systemMultiColorSeriesColors\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"Total sales\\\\\\\",\\\\\\\"colorMap\\\\\\\": [{\\\\\\\"serieName\\\\\\\": \\\\\\\"state\\\\\\\",\\\\\\\"color\\\\\\\": [\\\\\\\"#ffffb2\\\\\\\",\\\\\\\"#fddd87\\\\\\\",\\\\\\\"#fba35d\\\\\\\",\\\\\\\"#f75534\\\\\\\",\\\\\\\"#f9140a\\\\\\\",\\\\\\\"#d70315\\\\\\\",\\\\\\\"#b10026\\\\\\\"]}]}]}\\\"},\\\"display_mode\\\": \\\"CHART_MODE\\\"},\\\"viz_guid\\\": \\\"4ab1ed61-2930-46d4-af6f-778279d7414a\\\"}],\\\"filters\\\": [{\\\"column\\\": [\\\"region\\\"],\\\"oper\\\": \\\"in\\\",\\\"values\\\": [\\\"Midwest\\\"],\\\"is_mandatory\\\": false,\\\"is_single_value\\\": false,\\\"display_name\\\": \\\"region\\\"}],\\\"layout\\\": {\\\"tabs\\\": [{\\\"name\\\": \\\"Tab 1\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_1\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_4\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"2c4014b5-a606-4639-8ad0-01032ff3fc13\\\"},{\\\"name\\\": \\\"Tab 2\\\",\\\"description\\\": \\\"\\\",\\\"tiles\\\": [{\\\"visualization_id\\\": \\\"Viz_2\\\",\\\"x\\\": 0,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6},{\\\"visualization_id\\\": \\\"Viz_3\\\",\\\"x\\\": 6,\\\"y\\\": 0,\\\"height\\\": 8,\\\"width\\\": 6}],\\\"id\\\": \\\"185b4875-e7c5-43d2-a9bc-0a404107a3ec\\\"}]}}}\", \"info\": { \"filename\": \"Copy of Total Sales.liveboard.tml\", \"name\": \"Copy of Total Sales\", \"id\": \"2ed8192a-1e9d-47d1-810d-52b14cb0e9fe\", \"type\": \"liveboard\", \"status\": { \"status_code\": \"OK\" } }" - ], - "create_new": true, - "all_orgs_context": false, -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot schedules an import task, and returns the task name and ID in the API response: - -[source,JSON] ----- -{ - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "075c322f-b000-4776-9c44-89e13420980c", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": null, - "task_status": "IN_QUEUE", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": null, - "in_progress_at": null, - "completed_at": null, - "total_object_count": 2, - "object_processed_count": null, - "modified_at": null, - "author_display_name": "UserA" -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML Import Task submitted successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error -|==== - -=== Fetch status of the TML import task - -To fetch the status of a scheduled import task, send a `POST` request to the `POST /api/rest/2.0/metadata/tml/async/status` API endpoint. - -In the request body, include the following attributes: - -[width="100%" cols="2,4,1"] -[options='header'] -|==== -|Form parameter|Description| Default -|`task_ids` |__Array of strings__. Task IDs assigned to the scheduled TML async import operations. | __None__ -| `task_status` | __Array of strings__. Status of the scheduled import tasks to filter on. The following options are available: + - -* `COMPLETED` + -* `IN_QUEUE` + -* `IN_PROGRESS` + -* `FAILED` -| __None__ -|`author_identifier` + -__Optional__ |__String__. GUID of the author who initiated the import request. | __None__ -|`include_import_response` + -__Optional__ |__Boolean__. Specify whether to include import response in the task status objects.| `false` -|`record_offset` + -__Optional__ |__Integer__. The offset point, starting from where the task status should -be included in the response. | `0` -|`record_size` + -__Optional__ a|__Integer__. The number of task statuses to include in the -response starting from offset position. - -[NOTE] -==== -The maximum limit for the `record_size` that user can pass in an API request is 50. If the `record_size` exceeds this threshold, the API returns a bad request error. To extend the `record_size` limit, contact ThoughtSpot Support. -==== -| `5` -|`include_import_response`|__Boolean__. Specify whether to include the import response when fetching status for the import task. - -|==== - -[IMPORTANT] -==== -You can poll up to 100 API requests per minute to get details of your TML import tasks. The API returns an error if you exceed this rate limit. -==== - -==== Example request - -[source,cURL] ----- -curl -X POST \ - --url 'https://{ThoughtSpot-host}/api/rest/2.0/metadata/tml/async/status' \ - -H 'Accept: application/json' \ - -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer {AUTH_TOKEN}' \ - --data-raw '{ - "record_offset": 0, - "record_size": 5, - "include_import_response": true, - "task_ids": [ - "c8c8c4da-0bc8-4460-8039-cfa7fd598335" - ], - "task_status": [ - "COMPLETED" - ], - "author_identifier": "95ac814f-eb01-4625-93c7-c7624b29d226" -}' ----- - -==== Example response - -If the API request is successful, ThoughtSpot returns the status details of the TML async import tasks. -If Orgs are enabled on your instance, the API returns task status only for objects within the current Org context. - -[source,JSON] ----- -{ - "status_list": [ - { - "tenant_id": "default-tenant-id", - "org_id": 0, - "task_id": "c8c8c4da-0bc8-4460-8039-cfa7fd598335", - "task_name": "ASYNC_TML_26:Nov:2024-06:06:24", - "import_response": { - "object": [ - { - "filename": "tml_0", - "zip_filename": "zip_tml_0", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 0 - }, - { - "filename": "tml_1", - "zip_filename": "zip_tml_1", - "response": { - "status": { - "status_code": "ERROR", - "error_message": "Invalid YAML/JSON syntax in file." - } - }, - "request_index": 1 - } - ], - "status": { - "status_code": "OK", - "error_code": 0, - "error_message": "" - } - }, - "task_status": "COMPLETED", - "author_id": "08c6b203-ff6e-4ed8-b923-35ebbbfef27b", - "import_policy": "PARTIAL_OBJECT", - "created_at": 1732601184212, - "in_progress_at": 1732601184255, - "completed_at": 1732601184476, - "total_object_count": 2, - "object_processed_count": 2, - "modified_at": 1732601184476, - "author_display_name": "UserA" - } - ], - "last_batch": true -} ----- - -===== Response codes - -[options="header", cols="1,4"] -|==== -|HTTP status code|Description -|**200**|Async TML import task status fetched successfully -|**400**|Invalid request -|**401**|Unauthorized access -|**403**|Forbidden access -|**500**|Unexpected Error -|==== - - -== Export a TML -To export the TML data, your account must have the `DATAMANAGEMENT` (Can manage data) or `ADMINISTRATION` (Can administer ThoughtSpot) privilege. - -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: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml[**POST** /api/rest/2.0/metadata/tml/export] (REST API v2) -* xref:tml-api.adoc#export[**POST** /tspublic/v1/metadata/tml/export] (REST API v1) - -To export the TML representation of the metadata objects in a *batch*, use one of the following endpoints: - -* link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fapi-endpoints%2Fmetadata%2Fexport-metadata-tml-batched[**POST** /api/rest/2.0/metadata/tml/export/batch] (REST API v2) -* xref:tml-api.adoc#BatchExport[**POST** /tspublic/v1/metadata/tml/export/batch] (REST API v1) - -There are several export options available with these APIs: - -=== Metadata specification for Answers -To export a specific metadata object, specify the name or ID of the object. - -For Answer objects, the `identifier` is optional, and you can define parameters such as `session_identifier` and `generation_number` instead. These attributes can be used to export unsaved Answers generated from Spotter queries or Answers that do not have the name and ID assigned. - -=== Export associated objects - -To export associated objects, set the following attributes: - -* `export_associated` + -When set to `true`, exports the associated objects for the `export_ids` specified in the API request. The API exports any underlying Models, 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, Model, 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 Model. -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 Models with the same name, the TML import for a Liveboard that uses one of these Models would fail unless the Liveboard TML includes the FQN of the referenced object. -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. For link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank], set `export_schema_version` to v2. -The v1 schema is used for Worksheet objects (Deprecated). - -=== Additional export options for REST API v2 -Following are some additional attributes which can be set for exporting objects: - -* `include_obj_id_ref` + -When set to `true`, exports the object ID of the referenced object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. - -* `include_guid` + -When set to `true`, exports the guid of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `include_obj_id` + -When set to `true`, exports the object ID of the object. This flag will work only when the object ID feature is enabled. Contact ThoughtSpot Support to enable the feature. -* `export_with_associated_feedbacks` + -When set to `true`, exports the TML of an object along with all feedback, such as Spotter or Sage feedback, associated with that object. No feedback file will be exported if there are no feedback entries associated with the object -* `export_column_security_rules` [beta betaBackground]^Beta^ + -When set to `true`, exports the column-level security rules defined on the object. Contact ThoughtSpot Support to enable the feature. -* `export_with_column_aliases` [beta betaBackground]^Beta^ + -When set to `true`, export column aliases of the Model if the data Model includes any link:https://docs.thoughtspot.com/cloud/latest/column-aliases[column aliases, window=_blank]. - -=== Export in a batch -This API operation supports exporting User, User Group, and Role objects only. -To export objects in a batch, set the following additional attributes: - -* `batch_size` + -Exports the specified number of objects in a single API request. A batch size of up to 200 objects is allowed for a single API operation. - -* `batch_offset` + -Offsets the API response by the specified number. Batch offset value defines the starting position of the records for the results returned by the API. - -For more information, see the API documentation in REST API v2 Playground and xref:tml-api.adoc[Export a TML object using REST API v1]. - +* xref:tml-import.adoc[Import TML] +* xref:tml-export.adoc[Export TML] == TML modification -ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. Visit this page for detailed information on xref:modify-tml.adoc[TML modification]. +Visit this page for detailed information on xref:modify-tml.adoc[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 link:https://docs.thoughtspot.com/cloud/latest/tml#_limitations_of_working_with_tml_files[Limitations of working with TML files, window=_blank] for detailed information. -[#yamlReimport] -=== 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. - -+ - -[div videoContainer] --- -video::./images/tml-export.mp4[width=100%,options="autoplay,loop"] --- -+ -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: -+ -[source,JSON] ----- -{ - "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. -+ -[source,JSON] ----- -{ - "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. -+ - -[div videoContainer] --- -video::./images/import-tml.mp4[width=100%,options="autoplay,loop"] --- - == Deployment and version control of TML objects For information about version control and TML deployment, see the following pages: @@ -545,5 +67,4 @@ ThoughtSpot instances act as a constantly running service, so deployment only in But this changed with the link:https://developers.thoughtspot.com/docs/git-integration[Git integration] feature. ThoughtSpot now allows you to connect your deployment instance to a Git repository, push TML files to CI/CD pipelines, and deploy commits from your Git repository to your production environment. However, ThoughtSpot’s Git integration does not support moving objects within the same Org or application instance. For example, it does not support moving objects in an environment where xref:multitenancy-without-orgs[multi-tenancy is implemented using groups]. -/// - +//// diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index c0cec74b8..157dc8543 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -97,7 +97,7 @@ Two new fields have been added to the TML for Personalized Views: * A new `author` field is added to the Personalized View TML during export. This field is used to assign ownership during import. * Personalized Views now support `obj_id` for stable cross-environment object identity. -For more information, see xref:tml.adoc#personalized-views-portability[Personalized Views portability]. +For more information, see xref:tml-import.adoc#personalized-views-portability[Personalized Views portability]. --- diff --git a/src/components/SecondaryHeader/index.tsx b/src/components/SecondaryHeader/index.tsx index e472489b4..b645275a1 100644 --- a/src/components/SecondaryHeader/index.tsx +++ b/src/components/SecondaryHeader/index.tsx @@ -99,6 +99,7 @@ export const CATEGORY_PAGEIDS: Record = { ], 'rest-api': [ 'rest-apis', 'api-user-management', 'rbac', 'spotter-api', 'audit-logs', 'tml', + 'tml-import', 'tml-export', 'collections', 'connections', 'connection-config', 'rest-apiv2-getstarted', 'api-authv2', 'rest-apiv2-js', 'rest-apiv2-search', 'rest-apiv2-users-search', 'rest-apiv2-groups-search', 'rest-apiv2-metadata-search', diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index d5e37c73f..209ea45ef 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -125,7 +125,7 @@ module.exports = { 'session-api', 'user-api', 'group-api', 'role-api', 'security-api', 'admin-api', 'database-api', 'orgs-api', 'search-data-api', 'materialization-api', 'liveboard-data-api', 'liveboard-export-api', 'push-data', 'logs-api', - 'audit-logs', 'tml', 'collections', 'connections', + 'audit-logs', 'tml', 'tml-import', 'tml-export', 'collections', 'connections', 'connection-config', 'connections-api', 'api-user-management', 'rbac', 'webhooks-rest-api', 'rest-v2-changelog', 'rest-v1-changelog', ],