diff --git a/modules/ROOT/pages/access-control-sharing.adoc b/modules/ROOT/pages/access-control-sharing.adoc index 783c7ebbe..46f559b5f 100644 --- a/modules/ROOT/pages/access-control-sharing.adoc +++ b/modules/ROOT/pages/access-control-sharing.adoc @@ -31,7 +31,7 @@ image::./images/shareability_access.png[Shareability with groups and users] Users *do not see the group* that provides them access to a given piece of content (the same content could be shared to multiple groups they belong to, or to them directly as well), nor do they see who shared content to them individually, although they can see the *author* of any content. === Sharing content -ThoughtSpot users can share objects such as Liveboards, Answers, Tables, Models, Worksheets, and Table columns. +ThoughtSpot users can share objects such as Liveboards, Answers, Tables, Models, and Table columns. Sharing provides either `read-only` or `edit` permissions on an object diff --git a/modules/ROOT/pages/admin-api.adoc b/modules/ROOT/pages/admin-api.adoc index 841545999..315b9711f 100644 --- a/modules/ROOT/pages/admin-api.adoc +++ b/modules/ROOT/pages/admin-api.adoc @@ -1151,7 +1151,7 @@ On successful deletion of the action, the API returns a response body indicating [#custom-action-assoc] == Associate a custom action to ThoughtSpot objects -ThoughtSpot supports associating custom actions to Liveboards, answers, and worksheets, To programmatically associate a custom action to a ThoughtSpot object, send a `POST` request to the `/tspublic/v1/admin/embed/actions/{actionid}/associations` API endpoint. +ThoughtSpot supports associating custom actions to Liveboards, Answers, and Models, To programmatically associate a custom action to a ThoughtSpot object, send a `POST` request to the `/tspublic/v1/admin/embed/actions/{actionid}/associations` API endpoint. === Resource URL ---- diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 627387ddc..0598d166e 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,38 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 1.42.0, October 2025 + +[width="100%" cols="1,4"] +|==== +|[tag greenBackground]#NEW FEATURE# a|*Runtime overrides in Spotter embed* +The Visual Embed SDK now supports runtime overrides in Spotter embed. + +* To apply runtime filters, use the `runtimeFilters` object +* To apply runtime Parameters, use the `runtimeParameters` object. + +|[tag greenBackground]#NEW FEATURE# a|*PNG images in Liveboard schedule notifications* +To enable embedding PNG images of Liveboards in scheduled job notifications sent to subscribers, the SDK provides the `isPNGInScheduledEmailsEnabled` boolean parameter. When set to true, scheduled emails will include a PNG image of the Liveboard. + +The SDK also provides the following action IDs: + +* `Action.PngScreenshotInEmail` + +Adds the option to include a PNG screenshot in the notification email body when scheduling emails in ThoughtSpot. +* `Action.RemoveAttachment` +Allows the user to remove an attachment from the email configuration in the schedule email dialog. +|[tag greenBackground]#NEW FEATURE# a|*Spotter embed* + +Action IDs:: +The following action IDs are available for Spotter embedding and are currently supported only in the `hiddenActions` array: + +* `Action.SpotterWarningsBanner` + +Action ID to control the visibility of the Spotter warnings banner in the UI. This banner displays general warnings or informational messages related to Spotter results or queries. +* `Action.SpotterWarningsOnTokens` + +Action ID to control the visibility of warning indicators on individual Spotter tokens parsed from a Spotter query. +* `Action.SpotterTokenQuickEdit` + +Action ID to enable or disable the link:https://docs.thoughtspot.com/cloud/latest/spotter-getting-started#quick-edits[quick edit functionality^] for Spotter tokens. +|==== + == Version 1.41.0, September 2025 [width="100%" cols="1,4"] diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 6b3759d93..8278520d1 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -596,7 +596,7 @@ Resets the existing user properties upon token generation and adds the new attri |`filter_rules` a|__Array of filter rules__. An array of runtime filter conditions to pass via token. Each rule in the array must include the following information: * `column_name` + -Name of the column in the data source object (Worksheet or Model). +Name of the column in the data source object (Model). * `operator` + Filter operator to use. For a complete list of supported operators, see xref:runtime-filters.adoc#rtOperator[filter operators]. * `values` + @@ -625,7 +625,7 @@ The values to filter on. To get all records, use `TS_WILDCARD_ALL` . |`parameter_values` a| __Array of Parameter values__. Parameter rules to apply. Each rule in the array must include the following attributes: * `name` + -Name of the column in the data source object (Worksheet or Model) +Name of the column in the data source object (Model) * `value` + The values to use. diff --git a/modules/ROOT/pages/catalog-and-audit.adoc b/modules/ROOT/pages/catalog-and-audit.adoc index 27af7750d..a945884b4 100644 --- a/modules/ROOT/pages/catalog-and-audit.adoc +++ b/modules/ROOT/pages/catalog-and-audit.adoc @@ -65,6 +65,6 @@ To see a user's privilege set, use the xref:user-api.adoc#get-user-details[user There are also `assignedGroups` and `inheritedGroups` arrays within the response, which contain the GUIDs of the groups the user belongs to. To see the privileges assigned to the groups, use the xref:group-api.adoc#get-ug-details[group API endpoint]. Using `GET /user` and `GET /group` endpoints together allows tracing what group membership gives the user their privileges. == Dependency tracking -The xref:dependency-apis.adoc[dependency REST APIs] allow you to see which content objects rely on a data object. You can request the dependencies of a *table* object, which will return *worksheets*, *answers*, *Liveboards* and other objects that use the *table*. +The xref:dependency-apis.adoc[dependency REST APIs] allow you to see which content objects rely on a data object. You can request the dependencies of a *table* object, which will return *models*, *answers*, *Liveboards* and other objects that use the *table*. -To go up the chain, from an object to what it depends upon, you need to either export and process the object's TML or use the `/metadata/details` API endpoint, which returns a very large and complex data structure. For example, the `tables` property of the TML of an Answer or Liveboard provides the name of the table, Worksheet, or view that the data comes from. Worksheet TML responses similarly have a property referencing the tables or views they connect to. +To go up the chain, from an object to what it depends upon, you need to either export and process the object's TML or use the `/metadata/details` API endpoint, which returns a very large and complex data structure. For example, the `tables` property of the TML of an Answer or Liveboard provides the name of the Table, Model, or view that the data comes from. Model TML responses similarly have a property referencing the tables or views they connect to. diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index c5c5ba6f8..048de7dda 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -134,8 +134,6 @@ *** link:{{navprefix}}/prerender[Prerender components] *** link:{{navprefix}}/lazy-load-fullHeight[Full height and lazy loading options] *** link:{{navprefix}}/prefetch[Prefetch static resources] -** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] -*** link:{{navprefix}}/pendo-integration[Pendo integration with embed] ** link:{{navprefix}}/VisualEmbedSdk[Visual Embed SDK Reference] include::generated/typedoc/CustomSideNav.adoc[] *** Custom styles @@ -154,15 +152,17 @@ include::generated/typedoc/CustomSideNav.adoc[] **** [.typedoc-Enumeration]#link:{{navprefix}}/Enumeration_PrefetchFeatures[PrefetchFeatures]# **** [.typedoc-Function]#link:{{navprefix}}/Function_executeTML[executeTML]# **** [.typedoc-Function]#link:{{navprefix}}/Function_exportTML[exportTML]# + ** Other embedding methods *** link:{{navprefix}}/embed-without-sdk[Embed without SDK] *** link:{{navprefix}}/custom-viz-rest-api[Create a custom visualization] -** link:{{navprefix}}/sf-integration[Integration with Salesforce] ** link:{{navprefix}}/troubleshoot-errors[Troubleshoot errors] + * link:{{navprefix}}/rest-apis[REST API] ** link:{{navprefix}}/rest-apis[Overview] ** link:{{navprefix}}/api-user-management[Users and group privileges] ** link:{{navprefix}}/rbac[Role-based access control] +** link:{{navprefix}}/spotter-api[Spotter APIs ^BETA^] ** link:{{navprefix}}/audit-logs[Audit logs] ** link:{{navprefix}}/tml[TML] ** link:{{navprefix}}/connections[Connections] @@ -171,7 +171,6 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/rest-apiv2-getstarted[Get started] *** link:{{navprefix}}/api-authv2[REST API v2.0 authentication] *** link:{{navprefix}}/rest-apiv2-js[REST API v2.0 in JavaScript] -*** link:{{navprefix}}/spotter-api[Spotter AI APIs ^BETA^] *** link:{{navprefix}}/rest-apiv2-search[REST API v2.0 Search endpoints] **** link:{{navprefix}}/rest-apiv2-users-search[Search users] **** link:{{navprefix}}/rest-apiv2-groups-search[Search groups] @@ -229,9 +228,13 @@ include::generated/typedoc/CustomSideNav.adoc[] *** link:{{navprefix}}/multitenancy-within-an-org[Multi-tenancy within an Org] *** link:{{navprefix}}/single-tenant-data-models[Single-tenant data models with Orgs] *** link:{{navprefix}}/orgs-api-op[Org administration] -** link:{{navprefix}}/vercel-integration[Vercel integration] ** link:{{navprefix}}/tse-cluster[Cluster maintenance and upgrade] - +* Integration with external tools +** link:{{navprefix}}/external-tool-script-integration[External tools and scripts] +** link:{{navprefix}}/pendo-integration[Pendo integration with embed] +** link:{{navprefix}}/mcp-integration[MCP server integration] +** link:{{navprefix}}/sf-integration[Integration with Salesforce] +** link:{{navprefix}}/vercel-integration[Vercel integration] * Additional references ** link:{{navprefix}}/embed-ts[About ThoughtSpot embedding] ** link:{{navprefix}}/get-started-tse[Embed licenses] diff --git a/modules/ROOT/pages/custom-actions-callback.adoc b/modules/ROOT/pages/custom-actions-callback.adoc index 1d11ed825..300c46dd3 100644 --- a/modules/ROOT/pages/custom-actions-callback.adoc +++ b/modules/ROOT/pages/custom-actions-callback.adoc @@ -16,7 +16,7 @@ Callback custom actions allow you to get data payloads from an embedded ThoughtS * Users with developer or admin privileges can create a callback custom action in the Developer portal. * Developers can set a callback action as a global or local action. * To access callback actions, users must have the **New Answer Experience** enabled on their application instance. -* Users with edit permissions to a Worksheet or visualization can add a local callback action to a visualization or Answer of their choice. +* Users with edit permissions to a Model or visualization can add a local callback action to a visualization or Answer of their choice. * Developers must register the callback in the Visual Embed SDK and define data classes and functions to parse and process the JSON data payload retrieved from the callback event. -- diff --git a/modules/ROOT/pages/custom-actions-edit.adoc b/modules/ROOT/pages/custom-actions-edit.adoc index 1b4bebdd3..3f803c60f 100644 --- a/modules/ROOT/pages/custom-actions-edit.adoc +++ b/modules/ROOT/pages/custom-actions-edit.adoc @@ -5,7 +5,7 @@ :page-pageid: edit-custom-action :page-description: You can set a custom action as a primary button or as a menu action in the More options or the contextual menu. -ThoughtSpot lets you add custom actions globally to all your visualizations. When creating a custom action, developers can set the action as *Global* or *Local*. By default, the global custom actions are placed in the **More** menu image:./images/icon-more-10px.png[the more options menu]. The local custom actions are not placed anywhere in the UI until they are assigned to a Worksheet, Liveboard visualization, or saved Answer. +ThoughtSpot lets you add custom actions globally to all your visualizations. When creating a custom action, developers can set the action as *Global* or *Local*. By default, the global custom actions are placed in the **More** menu image:./images/icon-more-10px.png[the more options menu]. The local custom actions are not placed anywhere in the UI until they are assigned to a Model, Liveboard visualization, or saved Answer. You can place a custom action as a primary button, in the **More** image:./images/icon-more-10px.png[the more options menu] menu, or the context menu that appears when a user right-clicks on an Answer or Liveboard visualization. For example, if you want to send only a single row of data instead of the entire data set obtained from a visualization, you can place the custom action in the contextual menu. diff --git a/modules/ROOT/pages/custom-actions-url.adoc b/modules/ROOT/pages/custom-actions-url.adoc index 62c6a22ed..e298883e6 100644 --- a/modules/ROOT/pages/custom-actions-url.adoc +++ b/modules/ROOT/pages/custom-actions-url.adoc @@ -19,7 +19,7 @@ ThoughtSpot allows you to add a custom action to trigger a data payload to a spe * Developers can limit custom action access to a specific user group. * To access a URL action, users must have the **New Answer Experience** enabled. * For URL actions to work in the embedded mode, you must add the URL domain to the CORS and CSP connect-src allowlist. -* Only ThoughtSpot users with edit permissions to a Worksheet or visualization can add a URL action to a Worksheet, visualization, or saved Answer. +* Only ThoughtSpot users with edit permissions to a Model or visualization can add a URL action to a Model, visualization, or saved Answer. -- [#creUrlAction] diff --git a/modules/ROOT/pages/custom-actions-viz.adoc b/modules/ROOT/pages/custom-actions-viz.adoc index 621827f97..0dc50f6b4 100644 --- a/modules/ROOT/pages/custom-actions-viz.adoc +++ b/modules/ROOT/pages/custom-actions-viz.adoc @@ -5,9 +5,9 @@ :page-pageid: add-action-viz :page-description: Add custom actions -ThoughtSpot lets you add custom actions globally to all your visualizations or locally to a specific visualization or Worksheet. By default, the actions created in the Developer portal are set as *Global* actions. Developers or administrators can choose to set an action as **Local** and allow their application users to assign it to a visualization or saved Answer of their choice. +ThoughtSpot lets you add custom actions globally to all your visualizations or locally to a specific visualization or Model. By default, the actions created in the Developer portal are set as *Global* actions. Developers or administrators can choose to set an action as **Local** and allow their application users to assign it to a visualization or saved Answer of their choice. -If custom actions are enabled on your instance, the UI displays these actions in the *Custom actions* panel on a saved Answer or visualization page. By default, local custom actions are not assigned to any visualization. Any ThoughtSpot user with edit access to a visualization, saved Answer, or Worksheet can add a local action to the objects of their choice. For example, if you want to send data from a specific visualization to the pre-configured URL or web page, you can assign a URL action to that visualization. +If custom actions are enabled on your instance, the UI displays these actions in the *Custom actions* panel on a saved Answer or visualization page. By default, local custom actions are not assigned to any visualization. Any ThoughtSpot user with edit access to a visualization, saved Answer, or Model can add a local action to the objects of their choice. For example, if you want to send data from a specific visualization to the pre-configured URL or web page, you can assign a URL action to that visualization. If you have access to a custom action, ThoughtSpot lets you perform the following tasks: @@ -103,4 +103,4 @@ To delete a custom action association: . Click the *Custom actions* icon image:./images/custom-action-icon.png[the Custom actions menu]. . In the **Custom actions **panel, click the delete icon next to that action that you want to remove. -For information about deleting a custom action assigned at the Worksheet level, see xref:custom-actions-worksheet.adoc[Add custom actions to a Worksheet]. \ No newline at end of file +For information about deleting a custom action assigned at the Model level, see xref:custom-actions-worksheet.adoc[Add custom actions to a Model]. \ No newline at end of file diff --git a/modules/ROOT/pages/custom-actions-worksheet.adoc b/modules/ROOT/pages/custom-actions-worksheet.adoc index 3906de5bc..3a3579d2b 100644 --- a/modules/ROOT/pages/custom-actions-worksheet.adoc +++ b/modules/ROOT/pages/custom-actions-worksheet.adoc @@ -1,36 +1,36 @@ -= Add custom actions to a Worksheet += Add custom actions to a Model :toc: true :page-title: Actions customization :page-pageid: add-action-worksheet -:page-description: Add custom actions to worksheets +:page-description: Add custom actions to Models -ThoughtSpot supports adding custom actions to the visualizations generated from a specific worksheet. The local custom actions created in the Developer portal appear on the worksheet page, so that you can assign these actions to the new visualizations built from that worksheet. +ThoughtSpot supports adding custom actions to the visualizations generated from a specific Model. The local custom actions created in the Developer portal appear on the Model page, so that you can assign these actions to the new visualizations built from that Model. [NOTE] ==== -When you assign a custom action to a worksheet, ThoughtSpot adds it to the Answers generated from that worksheet. +When you assign a custom action to a Model, ThoughtSpot adds it to the Answers generated from that Model. ==== == Before you begin * Make sure the custom actions are set as *Local*. -* Make sure you have edit permissions to modify the worksheet. +* Make sure you have edit permissions to modify the Model. * Make sure the link:https://docs.thoughtspot.com/cloud/latest/answer-experience-new[new Answer experience, window=_blank] is enabled on your cluster. -== Assign a custom action to a worksheet +== Assign a custom action to a Model -To add a custom action to a worksheet: +To add a custom action to a Model: -. Go to *Data* > *Data Objects* > *Worksheets*. -. Click the worksheet that you want to modify. +. Go to *Data* > *Data Objects* > *Models*. +. Click the Model that you want to modify. . Click the *Custom actions* tab. + A list of custom actions available on your instance is displayed. -. Note that the page shows the global custom actions that appear on all visualizations by default. These actions will be available on all answers generated from the worksheet. +. Note that the page shows the global custom actions that appear on all visualizations by default. These actions will be available on all answers generated from the Model. -. To assign a local custom action to a worksheet: +. To assign a local custom action to a Model: .. Click *Add action*. .. Select the custom action that you want to add. .. To specify the position of the action, select one of the following options: @@ -40,9 +40,9 @@ Sets the custom action as a primary menu action. + [NOTE] ==== -ThoughtSpot allows only one primary action on a visualization page. If visualizations generated from the worksheet already have a primary action, the new configuration overrides this setting. +ThoughtSpot allows only one primary action on a visualization page. If visualizations generated from the Model already have a primary action, the new configuration overrides this setting. -If a visualization built from this worksheet already has a primary action added locally at the visualization level, ThoughtSpot will retain this configuration and does not apply the primary action added at the worksheet level. +If a visualization built from this Model already has a primary action added locally at the visualization level, ThoughtSpot will retain this configuration and does not apply the primary action added at the Model level. ==== * *Menu* @@ -58,12 +58,12 @@ Adds the custom action as a menu item in the contextual menu. If you want to sen . Click *Save*. + -The custom action will be added to all Answers generated from this worksheet. +The custom action will be added to all Answers generated from this Model. == Verify the custom action placement . To view the action you just added, click *Home*. -. Set your worksheet as the data source, specify search tokens, and click **Go**. +. Set your Model as the data source, specify search tokens, and click **Go**. + . Verify if the action is added to the visualization page. @@ -72,9 +72,9 @@ The custom action will be added to all Answers generated from this worksheet. == Edit the position of a local action -To edit the position of a local custom action associated with a worksheet: +To edit the position of a local custom action associated with a Model: -. Navigate to the worksheet page. +. Navigate to the Model page. . Click *Custom actions*. . Click on the action that you want to edit, and then click the edit icon. . Modify the position and click **Save**. @@ -83,6 +83,6 @@ To edit the position of a local custom action associated with a worksheet: To delete a custom action association: -. Navigate to the worksheet page. +. Navigate to the Model page. . Click *Custom actions*. . Click on the action that you want to delete, and then click the delete icon. diff --git a/modules/ROOT/pages/custom-actions.adoc b/modules/ROOT/pages/custom-actions.adoc index 7b867ef23..a7f011da7 100644 --- a/modules/ROOT/pages/custom-actions.adoc +++ b/modules/ROOT/pages/custom-actions.adoc @@ -28,7 +28,7 @@ You must xref:customize-actions-menu.adoc[create custom actions] in the **Develo After a custom action has been created, there are several options for assigning how and where the custom action will appear: * xref:custom-actions-viz.adoc[Assign custom actions to an answer or a visualization on a Liveboard] -* xref:custom-actions-worksheet.adoc[Assign custom actions to a worksheet] +* xref:custom-actions-worksheet.adoc[Assign custom actions to a Model] * xref:custom-actions-edit.adoc[Set the menu position of a custom action] == Ways for embedding apps to receive custom actions diff --git a/modules/ROOT/pages/customize-actions-menu.adoc b/modules/ROOT/pages/customize-actions-menu.adoc index 89bb38f3a..29a2ee0c5 100644 --- a/modules/ROOT/pages/customize-actions-menu.adoc +++ b/modules/ROOT/pages/customize-actions-menu.adoc @@ -17,7 +17,7 @@ The custom actions feature in ThoughtSpot allows users to push data to external * Developers can limit a custom action's availability to a specific user group. * Developers or administrators can set an action as a **Global** or **Local** action. * Global actions appear as menu actions on all visualizations. -* ThoughtSpot users with edit privileges can add a local custom action to a worksheet, saved Answer, or visualization. +* ThoughtSpot users with edit privileges can add a local custom action to a Model, saved Answer, or visualization. -- == Custom actions page @@ -45,9 +45,9 @@ Authorized users can edit the position of a global action on a visualization or Local actions:: -Local actions are not assigned to any visualization by default. Developers can create a local action and let users add this action to a specific visualization or the answers built from a specific worksheet. +Local actions are not assigned to any visualization by default. Developers can create a local action and let users add this action to a specific visualization or the answers built from a specific Model. + -Any user with edit access to a visualization or worksheet can assign a local action xref:custom-actions-viz.adoc[to a specific visualization] or xref:custom-actions-worksheet.adoc[all new visualizations generated from a specific worksheet]. +Any user with edit access to a visualization or Model can assign a local action xref:custom-actions-viz.adoc[to a specific visualization] or xref:custom-actions-worksheet.adoc[all new visualizations generated from a specific Model]. [#access-control] User access control:: diff --git a/modules/ROOT/pages/customize-email-apis.adoc b/modules/ROOT/pages/customize-email-apis.adoc index 1399d3bed..b4e4d1cda 100644 --- a/modules/ROOT/pages/customize-email-apis.adoc +++ b/modules/ROOT/pages/customize-email-apis.adoc @@ -1,17 +1,17 @@ -= Customize email template [beta betaBackground]^Beta^ += Customize email template [earlyAccess eaBackground]#Early Access# :page-title: Customize notification email settings per Org :page-pageid: customize-email-apis :page-description: You can rebrand system-generated notifications and customize notification emails - ThoughtSpot now provides REST APIs that enable developers and administrators to customize the branding, content, and visibility of components in notification emails. ThoughtSpot embedded users receive notification emails for several events, including: * ThoughtSpot welcome emails * Sharing of Liveboards, visualizations, or saved answers * SpotIQ analysis results * KPI chart alerts +* Liveboard schedules These APIs support customizations of the following parameters of the email template at the Org level: @@ -60,6 +60,7 @@ In your `POST` request body, include the following parameters: |Parameter|Description |template_properties a|__String__. Required. A JSON map of customizable elements of the email. +|org_identifier a|__String__. Required. The unique ID or name of the Org for which the customization is being done. |===== ==== Example request @@ -93,8 +94,11 @@ curl -X POST \ "hideModifyAlert": false, "productName":"ThoughtSpot", "footerPhone":"(800) 508-7008", - "footerAddress":"444 Castro St, Suite 1000 Mountain View, CA 94041" + "footerAddress":"444 Castro St, Suite 1000 Mountain View, CA 94041", + "company_privacy_policy_url": "https://link-to-privacy-policy.com/", + "company_website_url": "https://your-website.com" } + "org_identifier": "OrgA" }' ---- @@ -119,9 +123,24 @@ Validation email delivery requires the mail service to be enabled for the Org. I == Search an email customization To search the email customization configuration set for the Org send a `POST` request to the `/api/rest/2.0/customization/email/search` API endpoint. +== Update an email customization +To update the email customization configuration set for the Org send a `POST` request to the `POST /api/rest/2.0/customization/email/update` API endpoint. + +=== Request parameters +In your `POST` request body, include the following parameters: + +[width="100%" cols="1,4"] +[options='header'] +|===== +|Parameter|Description + +|template_properties a|__String__. Required. A JSON map of customizable elements of the email which need an update. +|org_identifier a|__String__. Required. The unique ID or name of the Org for which the email customization is being updated. +|===== + == Delete an email customization -To remove an existing customization configuration for notification emails in your Org, send a `POST` request to the `/api/rest/2.0/customization/email/{template_identifier}/delete` API endpoint, with the `template_identifier` passed as a path parameter in the request URL . +To remove an existing customization configuration for notification emails in your Org, send a `POST` request to the `/api/rest/2.0/customization/email/delete` API endpoint, with the `org_identifier` passed as a parameter in the API request. == Additional references diff --git a/modules/ROOT/pages/data-report-v2-api.adoc b/modules/ROOT/pages/data-report-v2-api.adoc index 93354566f..41d7a841d 100644 --- a/modules/ROOT/pages/data-report-v2-api.adoc +++ b/modules/ROOT/pages/data-report-v2-api.adoc @@ -1,6 +1,6 @@ = Data and Report APIs :toc: true -:toclevels: 2 +:toclevels: 3 :page-title: data-apis :page-pageid: fetch-data-and-report-apis @@ -80,12 +80,38 @@ curl -X POST \ }' ---- +==== 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** +==== Example [source,cURL] ---- curl -X POST \ @@ -167,7 +193,7 @@ To get data from a saved Answer object via `/api/rest/2.0/metadata/answer/data`, The API request body must include the name or GUID of the saved Answer. -.**Example** +==== Example [source,cURL] ---- curl -X POST \ @@ -180,6 +206,7 @@ curl -X POST \ }' ---- + == Report APIs ThoughtSpot provides the following REST API v2 endpoints to fetch data: @@ -305,7 +332,7 @@ curl -X POST \ include::{path}/transient-lb-content.adoc[] -.**Sample browser fetch request** +===== Sample browser fetch request [source,JavaScript] ---- @@ -337,7 +364,7 @@ In the request body, specify the GUID or name of the Answer object as `metadata_ You can download the Answer data in the `CSV`, `XLSX`, `PNG`, and `PDF` format. The default `file_format` is `CSV`. -.**Example** +==== Example [source,cURL] ---- @@ -357,6 +384,49 @@ curl -X POST \ * HTML rendering is not supported for PDF exports of Answers with tables. ==== +[#exportSpotterData] +==== 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 + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "file_format": "CSV", + "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", + "generation_number": 2 +}' +---- + +* `session_identifier` refers to session ID returned in the Spotter API response. +* `generation_number` indicates the Answer generation number. +* `file_format` specifies the format of the output. You can export the Spotter-generated data as PNG or CSV file. By default, the API exports this data in PNG file format. + +===== 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 +[width="100%" cols="2,4"] +[options='header'] +|=== +|HTTP status code|Description +|**200**| Successful operation +|**400**| Invalid parameter +|**401**| Unauthorized access +|**401**| Forbidden request +|**500**| Internal error +|=== +//// + == 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: diff --git a/modules/ROOT/pages/dependency-apis.adoc b/modules/ROOT/pages/dependency-apis.adoc index 7e61cf401..33a75f78d 100644 --- a/modules/ROOT/pages/dependency-apis.adoc +++ b/modules/ROOT/pages/dependency-apis.adoc @@ -10,26 +10,27 @@ The `tspublic/v1/dependency` endpoints allow you to query dependent objects for Dependency in ThoughtSpot is defined as a relation between the referenced and referencing objects. If the referenced object cannot be deleted without first deleting the referencing object, the referenced object is considered as a dependent object. -Consider a Worksheet (`Worksheet1`) that has a derived logical column (`Column1`), which in turn has a reference to a base logical column (`Column2`). +Consider a Model (`Model1`) that has a derived logical column (`Column1`), which in turn has a reference to a base logical column (`Column2`). +//// [.widthAuto] image::./images/dependency.png[Dependent objects, width=auto] +//// +In this example, `Model1` has a dependency on `Column2`, which means that `Model1` is a referencing object and `Column2` is a referenced object. ThoughtSpot does not allow you to delete `Column2` if you have not deleted `Model1`, because the deletion of `Column2` will be prevented by the relationship between `Model1’s` `Column1` and `Column2`. Similarly, `Column1` has a dependency on `Column2`; that is, `Column1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` without first deleting `Column1`. -In this example, `Worksheet1` has a dependency on `Column2`, which means that `Worksheet1` is a referencing object and `Column2` is a referenced object. ThoughtSpot does not allow you to delete `Column2` if you have not deleted `Worksheet1`, because the deletion of `Column2` will be prevented by the relationship between `Worksheet1’s` `Column1` and `Column2`. Similarly, `Column1` has a dependency on `Column2`; that is, `Column1` is a referencing object and `Column2` is a referenced object. You cannot delete `Column2` without first deleting `Column1`. - -Before deleting a data object such as a Worksheet, table, or column, you must check if it has any dependent objects, and remove its associations. +Before deleting a data object such as a Model, table, or column, you must check if it has any dependent objects, and remove its associations. == Data object types The `tspublic/v1/dependency` endpoint allows you to query and edit dependency for the following data object types: -* `LOGICAL_TABLE` for data objects such as tables, worksheets, or views. +* `LOGICAL_TABLE` for data objects such as Tables, Models, or Views. * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_COLUMN` for columns of a table, Worksheet, or View. +* `LOGICAL_COLUMN` for columns of a Table, Model, or View. * `LOGICAL_RELATIONSHIP` for table joins. + @@ -37,7 +38,7 @@ A join combines columns from one or several data objects by using matching value * `PHYSICAL_COLUMN` for the underlying column objects that exist in the physical layer of the data repository. -* `PHYSICAL_TABLE` for the original underlying table that is mapped to a logical table, Worksheet, or View. Physical table mapping details are available only on ThoughtSpot instances that use the Falcon database, most commonly ThoughtSpot software instances. +* `PHYSICAL_TABLE` for the original underlying table that is mapped to a logical table, Model, or View. Physical table mapping details are available only on ThoughtSpot instances that use the Falcon database, most commonly ThoughtSpot software instances. [NOTE] ==== @@ -72,8 +73,8 @@ POST /tspublic/v1/dependency/listdependents |Form parameter|Description |`type` a|_String_. Type of the data object. Valid values are: -* `LOGICAL_TABLE` for data objects such as tables, worksheets, or views. -* `LOGICAL_COLUMN` for columns of a table, worksheet, or View. +* `LOGICAL_TABLE` for data objects such as Tables, Models, or Views. +* `LOGICAL_COLUMN` for columns of a table, Model, or View. * `LOGICAL_RELATIONSHIP` for table joins. * `PHYSICAL_COLUMN` for physical column objects * `PHYSICAL_TABLE` for a physical table @@ -149,7 +150,7 @@ If the `POST` operation is successful, the API returns a response body with depe [#get-column-dependents] == Get dependent objects for a column -To get the details of dependent objects for a logical column in a worksheet, table, or View, send a `GET` request to `/tspublic/v1/dependency/logicalcolumn` API endpoint. +To get the details of dependent objects for a logical column in a Model, Table, or View, send a `GET` request to `/tspublic/v1/dependency/logicalcolumn` API endpoint. === Resource URL ---- @@ -161,7 +162,7 @@ GET /tspublic/v1/dependency/logicalcolumn [options='header'] |==== |Query parameter|Description -|`id`|__Array of strings__. A JSON array of GUIDs of the columns of a Table, Worksheet, or View. +|`id`|__Array of strings__. A JSON array of GUIDs of the columns of a Table, Model, or View. |==== === Example request @@ -182,8 +183,7 @@ https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/dependency/logicalcolumn?id=% ---- === Example response -If the GET operation is successful, the API returns a list of dependent objects such as worksheets, Liveboard objects, and answers. - +If the GET operation is successful, the API returns a list of dependent objects such as Models, Liveboard objects, and answers. [source,JSON] ---- @@ -302,7 +302,7 @@ If the GET operation is successful, the API returns a list of dependent objects [#get-table-dependents] == Get dependent details for data objects -To get the details of dependent objects for a Worksheet, Table, or View, send a `GET` request to the `/tspublic/v1/dependency/logicaltable` API endpoint. +To get the details of dependent objects for a Model, Table, or View, send a `GET` request to the `/tspublic/v1/dependency/logicaltable` API endpoint. === Resource URL ---- @@ -313,7 +313,7 @@ GET /tspublic/v1/dependency/logicaltable [options='header'] |==== |Query parameter| Description -|`id`|__Array of strings__. The GUIDs of data objects such as a worksheet, tables, or views. +|`id`|__Array of strings__. The GUIDs of data objects such as a Models, Tables, or Views. |==== === Example request @@ -737,7 +737,7 @@ https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/dependency/physicaltable?id=% When a default Liveboard is assigned to a user group in ThoughtSpot, it is used for onboarding new users of that group. Users of this group can also mark the default Liveboard as a favorite and use its data source for a new search. -If a Liveboard is set as a default Liveboard for a user group, the `/tspublic/v1/dependency/pinboard` endpoint will return the user group as a dependent object for that Liveboard. This API endpoint does not return other dependent data objects such as tables, views, and worksheets. +If a Liveboard is set as a default Liveboard for a user group, the `/tspublic/v1/dependency/pinboard` endpoint will return the user group as a dependent object for that Liveboard. This API endpoint does not return other dependent data objects such as Tables, Views, and Models. === Resource URL ---- diff --git a/modules/ROOT/pages/deploy-with-tml-apis.adoc b/modules/ROOT/pages/deploy-with-tml-apis.adoc index dbbf47f18..eee2a74a3 100644 --- a/modules/ROOT/pages/deploy-with-tml-apis.adoc +++ b/modules/ROOT/pages/deploy-with-tml-apis.adoc @@ -164,7 +164,7 @@ The xref:development-and-deployment#linkBuildRelease[Build release process] sect ==== Import related TML files together ThoughtSpot does not consider object display name for a TML file, but does use name matching for data object references within a TML file. -All data objects are referenced as "tables" within TML, whether they are a ThoughtSpot table, Worksheet, View, SQL view, or any other data object type. +All data objects are referenced as "tables" within TML, whether they are a ThoughtSpot Table, Model, View, SQL view, or any other data object type. The following heuristic is used to find matching objects by name within `tables` or `joins` sections: @@ -174,7 +174,7 @@ The following heuristic is used to find matching objects by name within `tables` The best practice is to create and upload "packages" of related objects together at once: * Give data objects within a package unique names, even though not enforced by ThoughtSpot -* All Table objects that use the same Connection object and all Worksheets connected to those tables should be uploaded together in a single TML Import +* All Table objects that use the same Connection object and all Models connected to those Tables should be uploaded together in a single TML Import * If a data object already exists, swap out the *fqn* references to avoid the name matching heuristic ==== Storing new GUIDs in a mapping diff --git a/modules/ROOT/pages/deprecated-features.adoc b/modules/ROOT/pages/deprecated-features.adoc index 2a758389f..8db175032 100644 --- a/modules/ROOT/pages/deprecated-features.adoc +++ b/modules/ROOT/pages/deprecated-features.adoc @@ -82,7 +82,7 @@ a|xref:deprecated-features.adoc#_deprecated_parameter_in_rest_api_v2_0_authentic == Worksheet deprecation and removal -Starting with 10.4.0.cl, Worksheets are deprecated and disabled by default in ThoughtSpot. In ThoughtSpot Cloud 10.12.0.cl and later versions, the ability to create new Worksheets will be removed, and all existing Worksheets will be automatically migrated to Models. +Starting with 10.4.0.cl, Worksheets are deprecated and disabled by default in ThoughtSpot. In ThoughtSpot Cloud 10.12.0.cl and later versions, the ability to create new Worksheets will be removed, and all existing Worksheets will be automatically migrated to Models. Impact on your instance:: diff --git a/modules/ROOT/pages/developer-playground.adoc b/modules/ROOT/pages/developer-playground.adoc index 093044454..b02bfdd71 100644 --- a/modules/ROOT/pages/developer-playground.adoc +++ b/modules/ROOT/pages/developer-playground.adoc @@ -143,11 +143,11 @@ To explore the features available for embedding Natural Language Search: |==== | a|**Disable changing model** + -Disables the Worksheet selection option. Users can search data only from the Worksheet specified in the SDK. +Disables the data source selection option. Users can search data only from the data source object specified in the SDK. a|**Hide model selector** + -Hides Worksheet selector. Users can search data only from the Worksheet specified in the SDK. +Hides data source selector. Users can search data only from the data source object specified in the SDK. a|**Hide sample questions** diff --git a/modules/ROOT/pages/embed-action-ref.adoc b/modules/ROOT/pages/embed-action-ref.adoc index 49042ceb1..5fbf06799 100644 --- a/modules/ROOT/pages/embed-action-ref.adoc +++ b/modules/ROOT/pages/embed-action-ref.adoc @@ -563,13 +563,13 @@ The following actions are available on the *Data* page in the full app embedded |=== |Action string in SDK| Required SDK library|Action label in the UI |xref:Action.adoc#_share[`Action.Share`] a|`AppEmbed` | *Share* action on the *Data* > *Home* page. + -Allows sharing a Worksheet, Table, or View with another user or group. +Allows sharing a Model, Table, or View with another user or group. |xref:Action.adoc#_remove[`Action.Remove`] a|`AppEmbed` | *Delete* action on the *Data* > *Home* and *Data* > *Connections* pages + -Allows deleting a Worksheet, Table, or View. +Allows deleting a Model, Table, or View. |xref:Action.adoc#_exporttml[`Action.ExportTML`] a| `AppEmbed` | *Export TML* action on the *Data* > *Home* page + -Allows exporting a Worksheet, Table, or View as a TML file. +Allows exporting a Model, Table, or View as a TML file. |xref:Action.adoc#_edittml[`Action.EditTML`] a| `AppEmbed` | *Edit TML* action on the *Data* > *Home* page + -Opens the TML Editor that allows you to modify the TML file of Worksheet, Table, or View. +Opens the TML Editor that allows you to modify the TML file of Model, Table, or View. |xref:Action.adoc#_importtml[`Action.ImportTML`] a| `AppEmbed` | The *Import TML* menu action imports the TML representation of ThoughtSpot objects. |=== diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 22441c3ad..8a8c35d46 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -235,7 +235,8 @@ However, when updating filters using `HostEvent.UpdateFilters`, you must include [NOTE] ==== -For `PERIOD` filters, you must include the `datePeriod` attribute in the date filter object. +* For `PERIOD` filters, you must include the `datePeriod` attribute in the date filter object. +* To specify the exact date, date range, you can use the date format such as `YYYY-MM-DD`, `YYYY/MM/DD`. If using epoch format, ensure that they are specified as numbers and not as strings. For example, `[1743465599, 1754006399]`. ==== The following table lists the supported filter types and examples for each type: diff --git a/modules/ROOT/pages/embed-ts-react-app.adoc b/modules/ROOT/pages/embed-ts-react-app.adoc index 86d234312..3c893b47d 100644 --- a/modules/ROOT/pages/embed-ts-react-app.adoc +++ b/modules/ROOT/pages/embed-ts-react-app.adoc @@ -538,10 +538,10 @@ ts-data-app> npm start === Code sample The following code sample shows the following attributes and properties: -* A `SpotterEmbed` function with `worksheetId` prop to pass the ID of the data object. + +* A `SpotterEmbed` function with `worksheetId` prop to pass the ID of the data source object such as a Model. + [NOTE] ==== -Worksheets are deprecated and replaced by Models in ThoughtSpot. We recommend using Models as the data object for Spotter embed. +Worksheets are deprecated and replaced by Models in ThoughtSpot Cloud 10.12.0.cl and later versions. ==== * The `searchOptions` property to pass a search query string. @@ -654,7 +654,7 @@ Create the Spotter Agent component using `useSpotterAgent`, and pass the data so [source,TypeScript] ---- const { sendMessage: sendSpotterMessage } = useSpotterAgent({ - worksheetId: "YOUR_WORKSHEET_ID", // ID of the data source object (Model) to query data + worksheetId: "YOUR_MODEL_ID", // ID of the data source object (Model) to query data }); const [response, setResponse] = useState(null); const handleSend = async () => { @@ -693,7 +693,7 @@ init({ authType: AuthType.None, }); -const worksheetId = "YOUR_WORKSHEET_ID"; // Replace with your worksheet ID +const worksheetId = "YOUR_DATA_MODEL_ID"; // Replace with your worksheet ID const SpotterAgentComponent: React.FC = () => { const { sendMessage: sendSpotterMessage } = useSpotterAgent({ worksheetId }); diff --git a/modules/ROOT/pages/embed-without-sdk.adoc b/modules/ROOT/pages/embed-without-sdk.adoc index 82a0a7e90..e8d3e775e 100644 --- a/modules/ROOT/pages/embed-without-sdk.adoc +++ b/modules/ROOT/pages/embed-without-sdk.adoc @@ -118,7 +118,7 @@ The following example shows the URL format copied from the iFrame element. Note == Embed ThoughtSpot Search page in an iFrame -To ThoughtSpot Search in an iFrame, the data object GUID is required. The data source can be Worksheet, Table, or View. +To ThoughtSpot Search in an iFrame, the data object GUID is required. The data source can be Model, Table, or View. To find the GUID of the datasource object: @@ -129,7 +129,7 @@ If you are using the new experience, click the Application switcher image:./imag + `\https:///#/data/tables/` -. On the **Data** > **Home** page, click on data object type. For example, if the data source object is a Worksheet, click **Worksheets** and open the Worksheet. +. On the **Data** > **Home** page, click on data object type. For example, if the data source object is a Model, click **Models** and open the Model. . In the address bar of the web browser, note the GUID of the data object. For example, in the following address string, the GUID is `9d93a6b8-ca3a-4146-a1a1-e908b71b963f`: + `\https:///#/data/tables/9d93a6b8-ca3a-4146-a1a1-e908b71b963f` @@ -155,11 +155,11 @@ To embed the Natural Language Search page in the iFrame, use the following URL f `\https://{ThoughtSpot-Host}/?embedApp=true#/embed/insights/create-ai-answer` -To load the object with a pre-selected Worksheet or Model, use the following URL format: +To load the object with a pre-selected data source object, use the following URL format: `\https://{ThoughtSpot-Host}/?embedApp=true&worksheet={Worksheet_id}#/embed/insights/create-ai-answer` -To load the object with a pre-defined query to fetch data from a specific Worksheet, use the following URL format: +To load the object with a pre-defined query to fetch data from a specific Model, use the following URL format: `\https://{ThoughtSpot-Host}/?embedApp=true&query={query-string}&worksheet={worksheet_id}&executeSearch=true#/embed/insights/create-ai-answer` @@ -300,7 +300,7 @@ To customize ThoughtSpot components embedded in an iFrame, ThoughtSpot provides |`profileAndHelpInNavBarHidden` |__Boolean__. Hides the user profile and help menu (?) icons in the full application embedded view. |`query`|__String__. Search query string in the natural language format. You can use this parameter to define a query string when embedding the Natural Language Search component. |`searchTokenString` |__Array of strings__. Array of search keywords. For example, `[sales][region]`. For Natural Language Search embed, use `query`. -|`worksheet`|__String__. GUID of the Worksheet object to be used for Natural Language Search queries. +|`worksheet`|__String__. GUID of the data source object to be used for Natural Language Search queries. |`visibleAction`|__Array of strings__. Lists the actions to show in the embedded view. See xref:Action.adoc[Actions] for allowed values. |`visibleTabs` |__Array of strings__. GUIDs of the Liveboard tabs to show in the embedded Liveboard view. |===== diff --git a/modules/ROOT/pages/faqs.adoc b/modules/ROOT/pages/faqs.adoc index 27d91b07d..5ef9465e7 100644 --- a/modules/ROOT/pages/faqs.adoc +++ b/modules/ROOT/pages/faqs.adoc @@ -41,7 +41,7 @@ image::./images/lb-image.png[Liveboard] .What is a data source? [%collapsible] ==== -A data source is a data object, such as a Worksheet, Table, or View, from which users can search data and create Answers and visualizations. +A data source is a data object, such as a Model, Table, or View, from which users can search data and create Answers and visualizations. ==== @@ -284,7 +284,7 @@ For more information, see xref:custom-actions.adoc[Custom actions] and see xref: ==== * Did you select the *On by default on all visualizations* checkbox when creating a custom action? If yes, the action will appear in the **More** image:./images/icon-more-10px.png[the more options menu] menu of your visualization. If you want to add it to the contextual menu, edit the position of the action by using the edit icon in the *Custom actions* image:./images/custom-action-icon.png[custom action icon] panel on your visualization page. -* If you did not select the *On by default on all visualizations* checkbox in the custom action creation pop-up, the action will be designated as a `Local` action. You must assign this action to a visualization, saved Answer, or Worksheet of your choice and place it in the context menu. +* If you did not select the *On by default on all visualizations* checkbox in the custom action creation pop-up, the action will be designated as a `Local` action. You must assign this action to a visualization, saved Answer, or Model of your choice and place it in the context menu. [NOTE] By default, custom actions are visible only to users with administrator or developer privilege. To make the custom action available to your end users, select the user group in *Show Advanced Availability Settings* and allow access. diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index 5dad232b0..1be5a5c36 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -15,7 +15,7 @@ There are different types of filters, which can be applied in the following orde 1. xref:rls-rules.adoc[Row-level security (RLS) Rules] + Tied to the logged-in user and their group memberships. Completely secure and cannot be altered by the logged-in user. 2. xref:abac-user-parameters.adoc[Attribute-Based Access Control (ABAC) filter rules] + -Filters and Parameter rules applied on a Worksheet and assigned to a token. +Filters and Parameter rules applied on a Modeland assigned to a token. 3. xref:runtime-filters.adoc[Runtime filters] and xref:runtime-parameters.adoc[Runtime Parameters] + Set via the Visual Embed SDK or URL query parameters. Runtime filters do not display as UI filter components. 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + @@ -42,12 +42,12 @@ The ABAC filter rules and runtime filters are converted into SQL with the same l 1. clauses are appended via `AND` -2. filters are applied to exact matching Worksheet Column names +2. filters are applied to exact matching Model Column names Any data restrictions resulting from filter rules will be seen in the visible filter UI of the Liveboard filters and `search_query` filters layers, but there is no visible filter UI directly related to these filtering layers. -=== Worksheet filters -Worksheet objects can have Parameters, formulas, and filters. +=== Data Model filters +Models can have Parameters, formulas, and filters. End users cannot affect the formulas or filters, which are always applied, but any Parameters that are used in a formula can be set by these other methods. diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 35b92d0f4..8474cd352 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -1,22 +1,72 @@ = Customize full application embed :toc: true -:toclevels: 3 +:toclevels: 2 :page-title: Customize full application embedding :page-pageid: full-app-customize :page-description: Customize full application embedding -The xref:full-embed.adoc[AppEmbed component] embeds the entire ThoughtSpot application experience within another page. - == UI and navigation experience -The ThoughtSpot UI and navigation experience is available in two modes: + +In full application embedding, the ThoughtSpot UI and navigation are available in the following modes: * Classic experience (default) -* New navigation and Home page experience [earlyAccess eaBackground]#Early Access# +* xref:full-app-customize.adoc#_new_modular_home_page_with_a_sliding_navigation_panel[New modular home page with sliding navigation panel] [earlyAccess eaBackground]#Early Access# +* xref:full-app-customize.adoc#_new_navigation_and_home_page_experience_without_the_sliding_panel[New modular home page and navigation without the sliding panel] [earlyAccess eaBackground]#Early Access# + +=== New modular home page with a sliding navigation panel + +The new navigation and modular home page experience provides an intuitive and efficient navigation structure. It organizes the application menu into persona-based modules designed specifically to address users' needs. Each module has a menu selector with a visual icon, to allow users to switch between contexts easily. Users can slide out the left navigation panel by clicking the hamburger icon in the header. + +If your application instance has classic experience, you'll notice the following changes when the new experience is enabled: + +* A redesigned UI with a sliding navigation panel. +* The app selector icons for *Insights*, *Data workspace*, and *Develop* appear in the header section of the left navigation panel. This selector provides access to persona-based apps, replacing the old top navigation menu. The left navigation panel provides quick access to different modules and can be customized. +* The *Admin* module is available under the user settings section in the top right corner. +* The *Home* page is available in the *Insights* section. The Home page is customizable and includes features such as Natural Language Search, watchlist, favorites, a library of Answers and Liveboards, and trending charts. +* The *Insights* section in the left navigation panel provides quick access to the Home page, Answers, Liveboards, and more. The panel also includes a list of users' favorites. +* The top navigation panel includes the following components: +** A Hamburger icon to allow users to slide out or slide in the navigation panel. +** Object search bar with quick access to the library. +** An Alert icon that shows notifications +** Help icon to access documentation +** Org switcher to switch between Org contexts +** Access to *Profile*, *Admin settings* (if the user has administrator privilege), and *Sign out* options. + +The following figure shows the new navigation panel and modular Home page: + +[.bordered] +[.widthAuto] +image::./images/new-nav3.png[New home page] + +==== Modular Home page +The customizable home page in ThoughtSpot’s new experience is available in the *Insights* section. It allows users to personalize the layout and content modules. Users can reorder sections, such as watchlist, favorites, library, trending charts, and more. For full app embedding application users, developers can set a default layout to include only the modules they want. + +==== Configure new experience +The navigation and home page experience is turned off by default. Administrators can enable it on their instance at the cluster level for all users. When this feature is enabled on the instance, users can switch between classic and new experience by turning off or enabling the experience in their profile settings. On embedded applications, you'll need to enable this experience using the `discoveryExperience` property as shown in this example: -=== New navigation and Home page experience +[source,JavaScript] +---- +const embed = new AppEmbed('#tsEmbed', { + // Enable the new modular home page and navigation experience + modularHomeExperience: true, + // Set the top navigation bar in the embedded view + showPrimaryNavbar: true, + discoveryExperience: { + // Set the navigation bar to use the new sliding (icon-based) style + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, + // Set the home page to use the modular layout + homePage: 'Modular', + }, + //other options +}); +---- + +=== New navigation and Home page experience without the sliding panel -In the new navigation and Home page experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the header bar instead of the top navigation menu. The app selector consists of different persona-based contextual elements called apps. On clicking an app from the application, the page corresponding to that app opens. Each application module has a separate left navigation panel. +In the new navigation and Home page experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the top header bar. The app selector consists of different persona-based contextual elements to allow users to switch between contexts. Clicking an app in the app selector menu opens the corresponding application page. Each application module has a separate left navigation panel. + +If your application instance has classic experience, you'll notice the following changes in the UI: [.bordered] [.widthAuto] @@ -105,7 +155,7 @@ a| [%collapsible] ==== -=== Enable new experience mode for ThoughtSpot embedding +==== Enable new experience mode without the sliding panel By default, the new navigation and home page experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. [source,javascript] @@ -165,6 +215,7 @@ The following examples show valid strings for `path`: [options='header'] |===== |Page| Classic experience | New navigation and Home page experience +|Home| `path: "home"` | `path: "home"` |Answers| `path: "answers"`| `path: "home/answers"` |Saved Answer| `path: "saved-answer/"` |`path: "saved-answer/"` |Liveboards| `path: "pinboards"`| `path: "home/liveboards"` @@ -172,7 +223,7 @@ The following examples show valid strings for `path`: |SpotIQ analysis list|`path: "insights"`| `path: "home/spotiq-analysis"` |SpotIQ analysis page| `path: "insight/"`| `path: "insight/"` |Data| `path: "data/tables/"`| `path: "data/tables/"` -|Worksheet, tables, views|`path: "data/tables/"`| `path: "data/tables/"` +|Model, tables, views|`path: "data/tables/"`| `path: "data/tables/"` |Monitor| `path: "monitor"` | `path: "monitor"` + or + `path: "home/monitor-alerts"` @@ -197,41 +248,35 @@ Page changes within the `AppEmbed` component register as part of the embedding a The standard JavaScript `history.back()` function will cause the `AppEmbed` component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component. [#_search_experience_on_home_page] -== Search experience in full app embed - -The Home page search experience varies based on the settings on your instance. On instances running 10.1.0.cl or lower, the Search interface on the Home page provides a combined view of Natural Language Search and Object Search. On instances running 10.3.0.cl and later, the Home page search experience is split into separate components. - -* If your instance was upgraded from 10.1.0.cl to 10.5.0.cl, Natural Language Search will be set as the default search experience for the Home page and the split search experience will be turned off by default. For applications embedding full ThoughtSpot experience, the `isUnifiedSearchExperienceEnabled` property will be set to `true` in the SDK. Your users can continue to use the unified experience until its deprecation. Developers can choose to disable the unified search experience and customize the Home page search experience for their users if required. +== Customize Search experience in full app embed -* If your instance was upgraded from 10.3.0.cl or 10.4.0.cl to 10.5.0.cl or later, the split search experience will be enabled by default and the `isUnifiedSearchExperienceEnabled` property will be set to `false` in the SDK. As a result of this change, Object Search will be set as the default experience for the Home page in full application embedding. To enable AI Search for your embed application users, use one of the following options: +// ** Create a xref:embed-nls.adoc[Natural Language Search page using SageEmbed] and build a navigation to this page from your embedding application. -** xref:full-app-customize.adoc#_enable_ai_search[Switch to AI search] by setting `homePageSearchBarMode` to `aiAnswer` in the SDK. -** Create a xref:embed-nls.adoc[Natural Language Search page using SageEmbed] and build a navigation to this page from your embedding application. - -The following table lists the search components supported in full application embed and the configuration settings required for these components: +The search components available for full application embed and the configuration settings required for these components are listed in the following table: [width="100%", cols="4,8"] [options='header'] |===== |Type| Description -|Object Search a| Allows finding popular Liveboards and Answers from the recommended suggestions. On instances running 10.1.0.cl or lower, the Home page provides a combined interface with Object Search and Natural Language Search. On instances running 10.3.0.cl or later, with split search experience enabled, the Object Search will be the default search experience on the Home page. +|Object Search a| Allows finding popular Liveboards and Answers from the recommended suggestions. -The Object Search bar also appears on the top navigation bar if the top navigation bar visibility is enabled ( `showPrimaryNavbar: true`) in the SDK. +On instances running 10.1.0.cl or lower, the Home page provides a combined interface with Object Search and Natural Language Search. On instances running 10.3.0.cl or later, with split search experience enabled, the Object Search will be the default search experience on the Home page. -|Natural Language Search (legacy interface) a| Allows searching a data source using a natural language query string and get AI-generated Answers. -On instances running 10.3.0.cl or earlier, with split search experience disabled, the Natural Language Search (legacy interface) will be available along with Object Search on the Home page. However, on instances running 10.3.0.cl or later, split search is enabled by default, and due to this, the Home page will not show Natural Language Search as the default search experience. To enable Natural Language Search for embed users, set `homePageSearchBarMode` to `aiAnswer` in the SDK. - -For more information, see xref:full-app-customize.adoc#_enable_ai_search_without_spotter[Enable AI Search]. +The Object Search bar also appears on the top navigation bar if the top navigation bar visibility is enabled ( `showPrimaryNavbar: true`) in the SDK. -|Spotter | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + +|Spotter Search | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + If Spotter is enabled on your instance, and `homePageSearchBarMode: "aiAnswer"` property is set in the SDK along with split search enabled (`isUnifiedSearchExperienceEnabled: false`), the search experience on the Home page switches to Spotter in full application embed. For more information, see xref:full-app-customize.adoc#_enable_ai_search_with_spotter[Enable AI Search with Spotter]. - | Search data a| Allows searching a data source using keywords and search tokens. This experience is available if you have set the `pageId` attribute to `Page.Search` or enabled navigation to the Search page of your ThoughtSpot application. +|Natural Language Search (legacy interface) a| Allows searching a data source using a natural language query string and get AI-generated Answers. +On instances running 10.3.0.cl or earlier, with split search experience disabled, the Search interface on the Home page provides a combined view of Natural Language Search (legacy interface) and Object Search. However, on instances running 10.3.0.cl or later, split search is enabled by default. Due to this, the Home page will not show Natural Language Search as the default search experience. + +Note that the legacy Natural Language Search option is deprecated and replaced with Spotter Search. You can enable Natural Language Search with Spotter, by setting `homePageSearchBarMode` to `aiAnswer` in the SDK. |===== + //// New home page and navigation experience mode:: By default, the Object Search bar is displayed in the Search module on the embedded **Home** page: @@ -247,7 +292,7 @@ By default, the Object Search bar is displayed on the embedded **Home** page. image::./images/sageDisabledwithNav_classic.png[] //// -=== Customize Home page search experience +=== Home page search experience options Developers can customize the Search experience by setting the `homePageSearchBarMode` property in the SDK to a desired value: @@ -255,97 +300,100 @@ Developers can customize the Search experience by setting the `homePageSearchBar Displays Object Search bar on the **Home** page. ** `aiAnswer` + Displays the search bar for Natural Language Search -** `none` +** `none` + Hides the Search bar on the **Home** page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. -=== Enable AI Search +==== Enable AI Search To set AI Search as the default search experience on the Home page, use the settings shown in the following examples. -==== New Home page experience +==== Enable AI Search with Spotter (Recommended) +To set Spotter as the default search experience on the Home page, use the settings shown in the following examples. + +===== New Home page experience [source,javascript] ---- const embed = new AppEmbed("#embed", { modularHomeExperience: true, + isUnifiedSearchExperienceEnabled: "false", homePageSearchBarMode: "aiAnswer", }); ---- -Home page search experience:: -[.widthAuto] -[.bordered] -image::./images/sage-search-new-exp.png[] -AI Search page:: +Home page search experience:: +[.bordered] [.widthAuto] +image::./images/spotter-fullApp.png[] + +Spotter page;; [.bordered] -image::./images/sage-search-home.png[] +[.widthAuto] +image::./images/spotter-fullApp2.png[] -==== Home page classic experience +===== Home page classic experience [source,javascript] ---- const embed = new AppEmbed("#embed", { + isUnifiedSearchExperienceEnabled: "false", homePageSearchBarMode: "aiAnswer", }); ---- -Home page search experience:: - -[.widthAuto] +Home page search experience;; [.bordered] -image::./images/sage_search-home-classic.png[] - -AI Search page:: - [.widthAuto] +image::./images/spotter_search-home-classic.png[] + +Spotter page;; [.bordered] -image::./images/sage-search-home.png[] +[.widthAuto] +image::./images/spotter-fullApp2.png[] -=== Enable AI Search with Spotter -To set Spotter as the default search experience on the Home page, use the settings shown in the following examples. +==== Enable AI Search (legacy) +To enable Natural Language Search (legacy), use the settings shown in these examples: -==== New Home page experience +===== New Home page experience [source,javascript] ---- const embed = new AppEmbed("#embed", { modularHomeExperience: true, - isUnifiedSearchExperienceEnabled: "false", homePageSearchBarMode: "aiAnswer", }); ---- - Home page search experience:: - -[.bordered] [.widthAuto] -image::./images/spotter-fullApp.png[] - -Spotter page;; [.bordered] +image::./images/sage-search-new-exp.png[] + +AI Search page:: + [.widthAuto] -image::./images/spotter-fullApp2.png[] +[.bordered] +image::./images/sage-search-home.png[] -==== Home page classic experience +===== Home page classic experience [source,javascript] ---- const embed = new AppEmbed("#embed", { - isUnifiedSearchExperienceEnabled: "false", homePageSearchBarMode: "aiAnswer", }); ---- -Home page search experience;; -[.bordered] -[.widthAuto] -image::./images/spotter_search-home-classic.png[] +Home page search experience:: -Spotter page;; +[.widthAuto] [.bordered] +image::./images/sage_search-home-classic.png[] + +AI Search page:: + [.widthAuto] -image::./images/spotter-fullApp2.png[] +[.bordered] +image::./images/sage-search-home.png[] == Customize navigation controls The `AppEmbed` package in the Visual Embed SDK provides several parameters to hide or customize navigation controls. @@ -426,7 +474,7 @@ const embed = new AppEmbed("#embed", { }); ---- -== Hide columns on list pages (New experience) +== Hide columns on list pages You can hide the following columns on the *Liveboards* and *Answers* listing pages using the xref:AppViewConfig#_hiddenlistcolumns[hiddenListColumns] array: * Author @@ -446,7 +494,6 @@ To hide one or several columns on the list pages, pass the relevant list page co [source,javascript] ---- const embed = new AppEmbed("#embed", { - modularHomeExperience: true, // hide Author, Share, and Tags columns on Answers and Liveboards list page hiddenListColumns: [ListPageColumns.Author,ListPageColumns.Share,ListPageColumns.Tags] }); @@ -454,11 +501,9 @@ const embed = new AppEmbed("#embed", { [NOTE] ==== -* The column hiding feature is available in the new home page and navigation experience. -* The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button above the list. To hide both the column and the *Share* (xref:Action.adoc#_share[Action.Share]) button above the list, use the `hiddenActions` or `visibleActions` array. +The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button above the list. To hide both the column and the *Share* (xref:Action.adoc#_share[Action.Share]) button above the list, use the `hiddenActions` or `visibleActions` array. ==== - == Detect changes in the currently loaded page Various actions the user takes within the embedded ThoughtSpot application may cause navigation within ThoughtSpot. diff --git a/modules/ROOT/pages/get-started-tse.adoc b/modules/ROOT/pages/get-started-tse.adoc index db9a5ada7..87a7b20c0 100644 --- a/modules/ROOT/pages/get-started-tse.adoc +++ b/modules/ROOT/pages/get-started-tse.adoc @@ -26,7 +26,7 @@ If you want to explore or evaluate the embedding workflows and API experience be * The Developer Playground provides an instant view of the embedding possibilities and interactive coding experience. You can try embedding the ThoughtSpot application or its features in a sample app and get a quick preview of the developer experience. -* With Free Trial, you can load your own data and evaluate embedded analytics features for a period of 14 days, and then transition to a paid account. +* With Free Trial, you can load your own data and evaluate embedded analytics features, and then transition to a paid account. //// diff --git a/modules/ROOT/pages/git-configuration.adoc b/modules/ROOT/pages/git-configuration.adoc index 868512d66..0840dd56e 100644 --- a/modules/ROOT/pages/git-configuration.adoc +++ b/modules/ROOT/pages/git-configuration.adoc @@ -45,7 +45,7 @@ tscli git-integration enable == Confirm permissions within ThoughtSpot Orgs * To commit objects from Thoughtspot to a Git repository, your ThoughtSpot user account requires at least view permission for all objects that will be committed as part of the operation. -* To deploy or revert objects from a Git repository to ThoughtSpot, you require edit access to all objects that will be updated as part of the deployment. If the deployment contains Worksheets, Views, or Tables, users require **Can manage data** (`DATAMANAGEMENT`) privilege for deploy, commit, and revert operations. +* To deploy or revert objects from a Git repository to ThoughtSpot, you require edit access to all objects that will be updated as part of the deployment. If the deployment contains Models, Views, or Tables, users require **Can manage data** (`DATAMANAGEMENT`) privilege for deploy, commit, and revert operations. [#guid-map-and-config-files] == GUID mapping and configuration files diff --git a/modules/ROOT/pages/git-rest-api-guide.adoc b/modules/ROOT/pages/git-rest-api-guide.adoc index 6cd46cd2c..dbf1d6e7f 100644 --- a/modules/ROOT/pages/git-rest-api-guide.adoc +++ b/modules/ROOT/pages/git-rest-api-guide.adoc @@ -49,7 +49,7 @@ __Optional__|__String__. Name of the branch in the Git repository to which you w === Request example -The following example shows the API request with Liveboard and Worksheet objects to commit to the default `commit_branch_name` for the Org the request is issued on (controlled by the bearer token): +The following example shows the API request with Liveboard and Model objects to commit to the default `commit_branch_name` for the Org the request is issued on (controlled by the bearer token): [source,cURL] ---- @@ -189,7 +189,7 @@ Due to GUID mapping requirements in most destination environments, it is current === Request example -The following example shows the API request with Liveboard and Worksheet objects to commit to Git. +The following example shows the API request with Liveboard and Model objects to commit to Git. [source,cURL] ---- diff --git a/modules/ROOT/pages/intro-thoughtspot-objects.adoc b/modules/ROOT/pages/intro-thoughtspot-objects.adoc index fed1bf2a8..4aee463e6 100644 --- a/modules/ROOT/pages/intro-thoughtspot-objects.adoc +++ b/modules/ROOT/pages/intro-thoughtspot-objects.adoc @@ -20,22 +20,22 @@ image::./images/object_model_hierarchy.png[Object Model Hierarchy] You must create a data model comprising at least one link:https://docs.thoughtspot.com/cloud/latest/connections[connection, window=_blank] with one link:https://docs.thoughtspot.com/cloud/latest/connect-data[Table, window=_blank] to begin using 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, with a link:https://docs.thoughtspot.com/cloud/latest/models[Model, window=_blank] bringing those tables together into a presentable analytic data model for the end-users. -Data engineers with *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. +Data engineers with *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. -*Tables* can have link:https://docs.thoughtspot.com/cloud/latest/security-rls[Row Level Security (RLS), window=_blank] rules that filter the data results based on the signed-in link:https://docs.thoughtspot.com/cloud/latest/user-management[username, window=_blank] or the link:https://docs.thoughtspot.com/cloud/latest/group-management[ThoughtSpot groups, window=_blank] to which the user belongs, and those rules apply to any *Worksheet* or *Model* that uses the *Table*. +*Tables* can have link:https://docs.thoughtspot.com/cloud/latest/security-rls[Row Level Security (RLS), window=_blank] rules that filter the data results based on the signed-in link:https://docs.thoughtspot.com/cloud/latest/user-management[username, window=_blank] or the link:https://docs.thoughtspot.com/cloud/latest/group-management[ThoughtSpot groups, window=_blank] to which the user belongs, and those rules apply to any *Model* that uses the *Table*. [NOTE] ==== -Models in ThoughtSpot application refer to an advanced version of Worksheets and serve as data source objects for content creation and data analytics. In ThoughtSpot 10.12.0.cl and later release versions, Worksheets are deprecated and replaced with Models. +Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0.cl and later release versions. ==== === Data modeling workflow 1. Create a *connection* to a cloud data warehouse. 2. Import *tables* from the *connection*. -3. Create *Worksheets* (analytic data models) based on tables. You can also create link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] and add tables. -4. Create *link:https://docs.thoughtspot.com/cloud/latest/views[ThoughtSpot views, window=_blank]* or *link:https://docs.thoughtspot.com/cloud/latest/sql-views[SQL views, window=_blank]* as necessary. +3. Create *Models* (analytic data models) based on tables. You can also create link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] and add tables. +4. Create link:https://docs.thoughtspot.com/cloud/latest/views[ThoughtSpot Views, window=_blank] or link:https://docs.thoughtspot.com/cloud/latest/sql-views[SQL Views, window=_blank] as necessary. -ThoughtSport also supports programmatic deployment of data models via link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] and table import from link:https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate[dbt, window=_blank]. +ThoughtSport also supports programmatic deployment of data models via link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] and table import from link:https://docs.thoughtspot.com/cloud/latest/dbt-integration#integrate[dbt, window=_blank]. == Content creation ThoughtSpot Search data creates a single table or chart view based on the query in the search bar and other configurations to the view made after the search results are visible. @@ -48,7 +48,7 @@ A link:https://docs.thoughtspot.com/cloud/latest/liveboard[Liveboard, window=_bl To create content: -1. Use the *link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank]* functionality to build visualizations from data sources such as *worksheets* or *views*. +1. Use the link:https://docs.thoughtspot.com/cloud/latest/search-data[Search data, window=_blank] functionality to build visualizations from data sources such as *Models* or *Views*. 2. Save the search result as an *Answer* or pin it to a Liveboard as a visualization. === Visualizations on a Liveboard @@ -92,7 +92,7 @@ GUID of the object. Unique within a given ThoughtSpot instance * `author` + GUID of the user who created / uploaded the object, or had the object transferred to them. * `owner` + -GUID representing the relationship between hierarchical objects, For example, a *column* would have the GUID of a *Table* or *Worksheet* as owner. +GUID representing the relationship between hierarchical objects, For example, a *column* would have the GUID of a *Table* or *Model* as owner. * `created` + timestamp of object creation * `modified` + @@ -112,7 +112,6 @@ The following notation is used in REST API v1 for object types: * *Connections*: `DATA_SOURCE` * *Data objects*: `LOGICAL_TABLE`, with the following subtypes: ** *Tables*: `ONE_TO_ONE_LOGICAL` -** *Worksheets*: `WORKSHEET` ** *Models*: `WORKSHEET` ** *Views*: `AGGR_WORKSHEET` ** *SQL views*: `SQL_VIEW` @@ -123,7 +122,7 @@ The following notation is used in REST API v1 for object types: * *Users*: `USER` * *Groups*: `USER_GROUP` -Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to *tables*, *Worksheets*, *Models*, or other data objects. Columns and joins can be viewed or modified only within the context of the data object to which they belong. +Column and join objects with their own GUIDs do exist within the ThoughtSpot system, but they are connected to *Tables*, *Models*, or other data objects. Columns and joins can be viewed or modified only within the context of the data object to which they belong. == Related resources diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc new file mode 100644 index 000000000..1eed543b9 --- /dev/null +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -0,0 +1,190 @@ += Agentic MCP server integration +:toc: true +:toclevels: 3 + +:page-title: MCP integration +:page-pageid: mcp-integration +:page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. + +ThoughtSpot’s Agentic Multi-Client Protocol (MCP) Server allows integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools to interact with ThoughtSpot’s data and its analytics capabilities programmatically. + +The MCP tools of the Agentic MCP Server support the following functions: + +* Ask natural language questions and get data in a structured format from ThoughtSpot +* Retrieve relevant analytical questions based on user queries +* Create a Liveboard with the answers generated from the queries +* Get data source recommendations based on a user's query and intent + +== Integration overview + +The Agentic MCP server integration requires the following core components and authentication framework: + +MCP server:: +The MCP server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP server can be hosted by ThoughtSpot or by customers in their own environment. + +MCP tools, resources, and AI APIs:: +MCP tools are the actions that the MCP server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP server supports the following tools: + +* `ping` to test connection to ThoughtSpot +* `getRelevantQuestions` to get relevant analytical questions + +The `getRelevantQuestions` tool calls `/api/rest/2.0/ai/relevant-questions/` API and gets relevant data questions for a given data context by breaking down a user's query. +* `getAnswer` to execute the queries and fetch data + +The `getAnswer` tool calls `/api/rest/2.0/ai/agent/converse/sse` API and generates answers and insights for a given data context. +* `createLiveboard` to create a Liveboard in ThoughtSpot + +The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from user's query. +* `getDataSourceSuggestions` to get data source suggestions + +Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. + +MCP host/client:: +The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP server, and enables agentic workflows. + +Configuration settings to enable the integration:: +Integration requires configuration, typically via a config file, to specify server addresses, credentials, and other connection details. + +Authentication and security settings:: +* Access to ThoughtSpot instance: + +For MCP server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + +To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users +* CSP and CORS settings: + +To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. +* SAML redirect settings: + +For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. +* Client connection configuration: + +MCP server integration also requires configuration on the client side, typically via a config file, to include the MCP server addresses, credentials, and other details. + +=== How it works + +When the MCP Server integration is enabled, your host app connects to ThoughtSpot and enables the following workflow: + +. User initiates a request. + +The user sends a query to get data from a specific ThoughtSpot data model or context. +. AI agent receives the request and discovers the MCP tools + +The agent discovers MCP tools available in its environment and processes the request to the MCP server, specifying the data model or context and the user's query. +. MCP server receives the request and executes actions via tools + +The MCP server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. +. The MCP server sends the response to the MCP host. +. The agent receives the response and constructs the output + +The agent receives the response from the MCP host and presents it to the user +. User receives the response + +The user can refine the analysis or choose a direction for further exploration. + +For example, after receiving relevant questions and answer, the user can send follow-up questions or send a Liveboard creation request. + +The following figure illustrates the sequence of workflows in a typical MCP server integration setup: + +[.bordered] +[.widthAuto]] +image::./images/mcp-integration.png[MCP integration] + +== Get started with the integration +To get started with the integration, complete the steps described in the following sections. In this article, we'll integrate ThoughtSpot MCP server with Claude and enable agentic interaction and workflows. + +=== Before you begin + +Before you begin, verify if your application setup has the following: + +* Node.JS version 22 or later is installed on your system. +* A ThoughtSpot instance with 10.11.0.cl or later release version. You'll need administrator credentials to configure security settings or set up token-based authentication for your application users. +* Your application users require at least view access to the data source objects to query data and get answers. +* Row-level and column-level security rules are configured for data security and access control. + +=== Configure security settings on ThoughtSpot + +To allow the secure communication between the MCP server and your ThoughtSpot instance, configure the following settings: + +. On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. +. Add the MCP server domain to CSP and CORS allowlists. +. If your setup uses SAML SSO logins, add the MCP server domain to the SAML redirect domain allowlist. + +=== Add MCP server to the MCP client's config + +If your MCP client supports remote MCP servers, add the MCP server URL to the client's config file. + +MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP servers. In such a case, add the URL with arguments shown in this example: + +[source,JSON] +---- +{ + "mcpServers": { + "ThoughtSpot": { + "command": "npx", + "args": [ + "mcp-remote", + "https://agent.thoughtspot.app/mcp" + ] + } + } +} + +---- + +After updating the config file: + +. Connect to ThoughtSpot instance and complete authentication. +. Restart your MCP client to load the new configuration. ++ +If the connection is successful, you'll see an option to add data context from ThoughtSpot. + +For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: ++ +[.bordered] +[.widthAuto] +image::./images/claudeDesktop.png[Claude Desktop] + +. Verify if the MCP tools are available. + +For example, on Claude Desktop, click the Search and tools icon to view the MCP tools. + ++ +[.bordered] +[.widthAuto] +image::./images/mcp-tools-claude.png[Claude Desktop] + +You can adjust tool access, resources, instructions to data models, object permissions, and user privileges as needed. To get insights, the user requires view access to the data source objects and data download privilege. + +=== Verify the query and response workflow + +* Select a datasource to set the context of your query. + +For example, on Claude Desktop, click the `+` icon and select a data source. + ++ +[.bordered] +[.widthAuto] +image::./images/datasource-selection.png[Claude Desktop] + +* Ask an analytics question to trigger the query and response workflow. +* Verify if the AI agent on your MCP client gets relevant data questions from ThoughtSpot and generates an Answer. ++ +[.bordered] +[.widthAuto] +image::./images/query-response-claude.png[Claude query response] + ++ +[.bordered] +[.widthAuto] +image::./images/query-response-claude2.png[Claude query response 2] + +* Try sending a query to create a Liveboard and verify if a Liveboard is created on your ThoughtSpot instance. + ++ +[.bordered] +[.widthAuto] +image::./images/create-lb-claude.png[Liveboard creation] + + + +== Configuration considerations and best practices + +* Streaming responses require client support for real-time updates. +* Users must have access to the data source. If not, it will lead to empty results. +* Ensure that data is modeled. Large or complex data sources may impact response time. +* Streaming responses require client support for real-time updates. Ensure that the system is available for queries. +* Each conversation is session-based. Ensure that session IDs are managed correctly in your integration. + +== Additional resources + +* Check the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repo, window=_blank] for implementation instructions. +* Check your MCP client's documentation for instructions on how to connect to MCP servers. +* To understand ThoughtSpot agentic analytics capabilities and AI APIs, refer to the following documentation: + +** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] +** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] +** xref:spotter-apis.adoc[Spotter AI APIs] +* In case of issues with connection or authentication, check the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^] \ No newline at end of file diff --git a/modules/ROOT/pages/metadata-api.adoc b/modules/ROOT/pages/metadata-api.adoc index 8548b26bb..8e3c3cc50 100644 --- a/modules/ROOT/pages/metadata-api.adoc +++ b/modules/ROOT/pages/metadata-api.adoc @@ -9,7 +9,7 @@ :page-pageid: metadata-api :page-description: Metadata API -The metadata APIs allow you to query metadata objects from the ThoughtSpot system. The metadata objects include answers, Liveboards, visualizations, and data objects such as tables, worksheets, and views. You can also query metadata objects for a user or user group configured in ThoughtSpot. +The metadata APIs allow you to query metadata objects from the ThoughtSpot system. The metadata objects include answers, Liveboards, visualizations, and data objects such as Tables, Models, and Views. You can also query metadata objects for a user or user group configured in ThoughtSpot. == Supported operations @@ -48,8 +48,8 @@ POST /tspublic/v1/metadata/assigntag * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or view. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. For example, if you want to assign a tag named `Sales` to a Liveboard and Answer, specify a JSON array of the Liveboard and Answer GUIDs in `id` and set the `type` as `["PINBOARD_ANSWER_BOOK","QUESTION_ANSWER_BOOK"]`. @@ -113,8 +113,8 @@ POST /tspublic/v1/metadata/unassigntag * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or view. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. For example, if you want to remove a tag named `Sales` from a Liveboard and Answer, specify a JSON array of the Liveboard and Answer GUIDs in `id` and set the `type` as `["PINBOARD_ANSWER_BOOK","QUESTION_ANSWER_BOOK"]`. @@ -176,16 +176,19 @@ GET /tspublic/v1/metadata/details * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or view. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. -* `LOGICAL_RELATIONSHIP` for table or Worksheet joins. A join combines columns from one or several data objects by using matching values. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. +* `LOGICAL_RELATIONSHIP` for table joins. A join combines columns from one or several data objects by using matching values. * `TAG` for tag objects. * `DATA_SOURCE` for data source connections from which the metadata objects were loaded. * `USER` for user objects. * `USER_GROUP` for user group objects. |`id`|__String__. A JSON array of GUIDs of the objects. -|`showhidden` |__Boolean__. When set to `true`, returns details of the hidden objects, such as a column in a Worksheet or a table. By default, this attribute is set to `false`. -|`dropquestiondetails`|__Boolean__. When set to `true`, the search assist data associated with a Worksheet is not included in the API response. This attribute is applicable only for `LOGICAL_TABLE` data type. By default, this attribute is set to `false`. +|`showhidden` |__Boolean__. When set to `true`, returns details of the hidden objects, such as a column in a Model or a Table. By default, this attribute is set to `false`. +|`dropquestiondetails` a|__Boolean__. When set to `true`, the search assist data associated with the specified data source object is not included in the API response. +This attribute is applicable only for the `LOGICAL_TABLE` data type. By default, this attribute is set to `false`. +[NOTE] +The Search Assist feature is deprecated and removed from ThoughtSpot Cloud 10.4.0.cl and later versions. |`version` __Optional__|__Long integer__. Object version. By default, the API returns metadata for all versions of the object. |`orgScope`|__Optional__. The Org scope. To query user metadata for all Orgs on your cluster, set the Org scope to `ALL`. If the Org scope is not set, ThoughtSpot returns metadata for only the user objects in your current Org context. |==== @@ -540,9 +543,9 @@ GET /tspublic/v1/metadata/list * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or view. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. -* `LOGICAL_RELATIONSHIP` for table or Worksheet joins. A join combines columns from one or several data objects by using matching values. +* `LOGICAL_TABLE` for any data object such as a table, Model, or view. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or views. +* `LOGICAL_RELATIONSHIP` for table joins. A join combines columns from one or several data objects by using matching values. * `DATA_SOURCE` for external data source connections that are mapped in ThoughtSpot to support live query of data. * `TAG` for tag objects. * `USER` for user objects. @@ -557,7 +560,7 @@ The `QUESTION_ANSWER_SHEET` and `PINBOARD_ANSWER_SHEET` metadata object types ar * For the `LOGICAL_TABLE` metadata object `type`, the valid `subtypes` are: ** `ONE_TO_ONE_LOGICAL` for Tables -** `WORKSHEET` for Worksheets and Models. A Worksheet is a collection of related tables. +** `WORKSHEET` for data objects such as Models ** `USER_DEFINED` for imported data; For example, the tables uploaded from a CSV file. ** `AGGR_WORKSHEET` for views. A *View* in ThoughtSpot refers to a table materialized from a saved Answer that was saved as a view by a user. @@ -569,8 +572,8 @@ The `PRIVATE_WORKSHEET` metadata `subtype` is deprecated. //// * For `LOGICAL_COLUMN` and `LOGICAL_RELATIONSHIP` metadata object types, the valid `subtypes` include: -** `FORMULA` to query a list of formulas applied to a Worksheet column. -** `CALENDAR_TYPE` to query the type of calendar used by the DATE TYPE column in a Worksheet. +** `FORMULA` to query a list of formulas applied to a column. +** `CALENDAR_TYPE` to query the type of calendar used by the DATE TYPE column in the data model. ** `CALENDAR_TABLE` to query columns that have a custom calendar configured. |`ownertypes` __Optional__|__String__. A JSON array of owner types for metadata object subtypes such as `ONE_TO_ONE_LOGICAL`, `WORKSHEET`, `USER_DEFINED`, and `AGGR_WORKSHEET`. @@ -596,7 +599,7 @@ The `PRIVATE_WORKSHEET` metadata `subtype` is deprecated. |`batchsize` __Optional__|__Integer__. The batch size of the objects returned in the API response. A value of -1 implies all items starting from the offset value. |`tagname` __Optional__|__String__. A JSON array containing a set of tag names to filter headers by. |`pattern` __Optional__|__String__. A pattern to match the name of the metadata object or the username associated with the object. This parameter supports matching case-insensitive strings. For a wildcard match, use `%`. -|`showhidden` |__Boolean__. When set to `true`, returns details of the hidden objects, such as a column in a Worksheet or a table. By default, this attribute is set to `false`. +|`showhidden` |__Boolean__. When set to `true`, returns details of the hidden objects, such as a column in a Model or a table. By default, this attribute is set to `false`. |`skipids` __Optional__|__String__. A JSON array containing the GUIDs of the metadata objects that you want to exclude. |`fetchids` __Optional__|__String__. A JSON array containing the GUIDs of the metadata objects that you want to fetch. |`auto_created` __Optional__|__Boolean__. A flag to indicate whether to list only the auto-created objects. A value of null returns all objects. @@ -1004,7 +1007,7 @@ GET /tspublic/v1/metadata/listobjectheaders * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, worksheet, or view. +* `LOGICAL_TABLE` for any data object such as a Table, Worksheet, or View. * `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. * `LOGICAL_RELATIONSHIP` for table or worksheet joins. A join combines columns from one or several data objects by using matching values. * `TAG` for tags assigned to a metadata object. diff --git a/modules/ROOT/pages/modify-tml.adoc b/modules/ROOT/pages/modify-tml.adoc index ac48fdb4c..9234c85d3 100644 --- a/modules/ROOT/pages/modify-tml.adoc +++ b/modules/ROOT/pages/modify-tml.adoc @@ -6,10 +6,7 @@ :page-pageid: modify-tml :page-description: Details of how to change TML files to achieve various transformations and goals - -link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] is slightly different for every object type, but all follow a general pattern that allows for programmatic editing. - -This section describes how various objects and their connections to each other are represented in TML. +link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] is slightly different for every object type, but all follow a general pattern that allows for programmatic editing. This article describes how various objects and their connections to each other are represented in TML. The xref:version_control.adoc[Git integration features] within ThoughtSpot automatically handle the relevant aspects of a typical development and deployment process. @@ -30,12 +27,13 @@ The *Connection* is thus the natural packaging level for importing TML files, ex This is to say, for a given *Connection* you can always upload all TML files connected to that connection safely except Liveboards. -One best practice recommendation is to only connect *Answers* and *Liveboards* to *worksheets*. Although they can connect directly to *Tables* and *Views*, it is far simpler to adjust a single reference to one *worksheet* within the *answer* and *Liveboard* TML than many individual *tables*. The only exception is if you use a single *table* or *view* for the underlying search answer. +One best practice recommendation is to only connect *Answers* and *Liveboards* to *Models*. Although they can connect directly to *Tables* and *Views*, it is far simpler to adjust a single reference to one Model within the Answer and Liveboard TML than many individual *tables*. The only exception is if you use a single *table* or *view* for the underlying Answer. image::./images/object_model_hierarchy.png[ThoughtSpot object model hierarchy and relationships] === Export with fqn: property -Always export TML files with `export_fqns=true` (for versions lower than 9.0.0.cl, see xref:development-and-deployment.adoc#_notes_for_older_releases_8_9_0_cl_or_earlier_versions[Notes for older releases]). +Always export TML files with `export_fqns=true`. +//(for versions lower than 9.0.0.cl, see xref:development-and-deployment.adoc#_notes_for_older_releases_8_9_0_cl_or_earlier_versions[Notes for older releases]). The `fqn:` property provides the GUID of associated objects, which can be swapped out when moving packages of TML files between environments. The following is an example of the `connection:` property within a Table TML: @@ -51,7 +49,7 @@ You can always *remove* an `fqn:` property when uploading a set of TML with the === Name properties are identifiers in connected objects When editing entire packages of exported TML files to be deployed in a different environment, you *must consider changes to identifiers in other "downstream" TML files*. ThoughtSpot will do the necessary updates on an existing data model. -One of the most important examples is that the `name:` property of a column in a Table is used as part of the column identifier in connected Worksheet objects. +One of the most important examples is that the `name:` property of a column in a Table is used as part of the column identifier in connected Model objects. A Table object might have a column with a display name property (`name:`) that has been modified to be different than the `db_table:` property (the actual name of the column in the database itself): @@ -75,8 +73,18 @@ table: data_type: INT64 ---- -The connected worksheet TML referencing the same column would be as shown in the following example. Note that it is the formatted `name` property from the Table TML, not `db_table_name`. +The connected Model TML referencing the same column would be as shown in the following example. Note that it is the formatted `name` property from the Table TML, not `db_table_name`. +[source,YAML] +---- + columns: + - name: Product Name + column_id: FACT_RETAPP_SALES_1::Sales Id + properties: + column_type: ATTRIBUTE +---- + +In the Worksheet TML, the column properties are presented as shown in the following example: [source,YAML] ---- ... @@ -88,9 +96,9 @@ The connected worksheet TML referencing the same column would be as shown in the ... ---- -The pattern for `column_id` is a combination of the `id` from the `table_paths` section along with the `name` property of the column in the table object: `{Worksheet.table_paths[n].id}::{Table.columns[n].name}` +The pattern for `column_id` is a combination of the `id` from the `table_paths` section along with the `name` property of the column in the table object: `{Model.table_paths[n].id}::{Table.columns[n].name}` -This is the section in Worksheet where the first part of the identifier is defined as the `id` property (`table` property references the `tables:` section above in the TML file): +This is the section in Model where the first part of the identifier is defined as the `id` property (`table` property references the `tables:` section above in the TML file): [source,YAML] ---- @@ -173,7 +181,7 @@ You can adjust the properties of existing columns or even add new column objects When updating an existing object, do not change both `name` and `db_column_name` at the same time. The TML parser will consider this as a deletion of the original column and an addition of a new column. -If you are modifying a package of TML for deployment to a new environment, changes to `name` property have downstream effects in connected Worksheet files. +If you are modifying a package of TML for deployment to a new environment, changes to `name` property have downstream effects in connected Model files. [source,YAML] ---- @@ -200,57 +208,13 @@ If you cannot upload your Table TMLs all at once and you are encountering errors . Check that all table objects have been created successfully on the ThoughtSpot server. . Do a second import of the TML documents with the `rls_rules` and `joins_with` sections. To update the new objects rather than the original objects, specify the GUIDs of the newly created table objects on the server in the TML documents' `guid` property. -== Worksheets - -Worksheets combine several *tables*, including *Views*, into a coherent data model optimized for searches. The link:https://docs.thoughtspot.com/cloud/latest/tml-worksheets[TML syntax for worksheets, window=_blank] defines all aspects of the *worksheet*, including the tables it joins together, the columns and their properties, filters, and so on. - -If you want to change the values for an existing *worksheet* object, the `tables`, `joins` and `table_paths` sections are the most important. - -The `tables` section is a list of table objects that exist on the ThoughtSpot Server. The `name` property is all that is included in an exported TML file, and this matches the `name` property of the table object. If there is more than one table object on the server with identical name properties, you must use the `fqn` property to specify the GUID of the particular table you want. However, the string value of `name` is used in the `joins` section, so the correct process for adding an `fqn` property is as follows: - -So you go from -[source,YAML] ----- - tables: - - name: ----- - -to - -[source,YAML] ----- - tables: - - id : - fqn : ----- -The `name` property, which is now transformed into the `id` property, is used in the `joins` and `table_paths` sections that follow. Under `joins`, the `source` and `destination` properties take the string `id` property of a table in the tables list. In a TML file exported from ThoughtSpot, you won't have to make any changes, because this value will already be set to what was defined in the `name` property, and we've maintained that value by switching it to the `id` property. - -Under `table_paths`, the `table` property also uses the values we moved to `id`. The list of join names under `join_path` will need to match the text value of the `name` element of an item in the `joins`. This should be valid as exported and not require any changes, but if you do change the `name` value of a join, you will need to update the value in the `join_path` list in `table_paths`. - -[source,YAML] ----- - joins: - - name: - source: - destination: - type: [RIGHT_OUTER | LEFT_OUTER | INNER | OUTER] - on: - is_one_to_one: [ false | true ] - - ... - table_paths: - - id: - table: - join_path: - - join: - - - - ----- - == Models -Like Worksheets, Models combine several Tables to create a data model optimized for Search. With Models, you can build a data model easily by dragging and dropping tables and columns and creating joins, and switch between Table and Column views. +Models combine several Tables to create a data model optimized for Search. With Models, you can build a data model easily by dragging and dropping tables and columns and creating joins, and switch between Table and Column views. -TML for Models has a specific syntax and includes several parameters. It includes parameters that are explicitly defined. For example, if you do not have any filters on your Model, the `filters` parameter does not appear. You can add that variable to the TML file to specify filters for your Model. The `fqn` parameter is optional but is recommended to reduce ambiguity when there is more than one table object on the server with identical name properties. If you do not add the `fqn` property and the Connection or Table you reference does not have a unique name, the file import fails. +TML for Models has a specific syntax and includes several parameters. It includes parameters that are explicitly defined. For example, if you do not have any filters on your Model, the `filters` parameter does not appear. You can add that variable to the TML file to specify filters for your Model. + +The `model_tables` section is a list of table objects that exist on the ThoughtSpot Server. The `name` property is all that is included in an exported TML file, and this matches the `name` property of the table object. If there is more than one table object on the server with identical name properties, you must use the `fqn` property to specify the GUID of the particular table you want. However, the string value of `name` is used in the `joins` section, so the correct process for adding an `fqn` property is as follows: [source,YAML] ---- @@ -381,11 +345,61 @@ model: For more information, see link:https://docs.thoughtspot.com/cloud/latest/tml-models[TML for Models, window=_blank]. +== Worksheets +[tag redBackground]#DEPRECATED# + +[IMPORTANT] +==== +Worksheets are deprecated and replaced with Models in ThoughtSpot Cloud 10.12.0.cl and later versions. You'll no longer be able to import a Worksheet TML object into ThoughtSpot without link:https://docs.thoughtspot.com/latest/worksheet-migration[converting it into a Model, window=_blank]. For information about the TML properties of a Model object, see link:https://docs.thoughtspot.com/cloud/latest/tml-models[TML for Models]. +==== + +Worksheets combine several *tables*, including *Views*, into a coherent data model optimized for searches. The TML syntax for Worksheets defines all aspects, including the tables it joins together, the columns and their properties, filters, and so on. + +If you want to change the values for an existing object, the `tables`, `joins` and `table_paths` sections are the most important. + +So you go from +[source,YAML] +---- + tables: + - name: +---- + +to + +[source,YAML] +---- + tables: + - id : + fqn : +---- +The `name` property, which is now transformed into the `id` property, is used in the `joins` and `table_paths` sections that follow. Under `joins`, the `source` and `destination` properties take the string `id` property of a table in the tables list. In a TML file exported from ThoughtSpot, you won't have to make any changes, because this value will already be set to what was defined in the `name` property, and we've maintained that value by switching it to the `id` property. + +Under `table_paths`, the `table` property also uses the values we moved to `id`. The list of join names under `join_path` will need to match the text value of the `name` element of an item in the `joins`. This should be valid as exported and not require any changes, but if you do change the `name` value of a join, you will need to update the value in the `join_path` list in `table_paths`. + +[source,YAML] +---- + joins: + - name: + source: + destination: + type: [RIGHT_OUTER | LEFT_OUTER | INNER | OUTER] + on: + is_one_to_one: [ false | true ] + - ... + table_paths: + - id: + table: + join_path: + - join: + - + - +---- + == Answers -The link:https://docs.thoughtspot.com/cloud/latest/tml-answers[answer TML syntax, window=_blank] defines all aspects of a saved search and how it is visualized. The `tables` property is used to point to ThoughtSpot *table*, *view*, or *worksheet* objects, whichever the answer is connected to. +The link:https://docs.thoughtspot.com/cloud/latest/tml-answers[answer TML syntax, window=_blank] defines all aspects of a saved search and how it is visualized. The `tables` property is used to point to ThoughtSpot *table*, *view*, or *model* objects, whichever the answer is connected to. -As mentioned above, it is simpler to connect an answer to a single *worksheet*, so that you only have to update one reference in the `tables` section. +As mentioned above, it is simpler to connect an answer to a single *model*, so that you only have to update one reference in the `tables` section. [source,YAML] ---- @@ -406,7 +420,7 @@ answer: link:https://docs.thoughtspot.com/cloud/latest/tml-liveboards[Liveboards, window=_blank] include many different visualizations and define a layout of the visualizations elements. -It is *best practice* to only use *one worksheet* for all visualizations on a Liveboard. However, each visualization on a *Liveboard* can connect to different data objects. +It is *best practice* to only use *one model* for all visualizations on a Liveboard. However, each visualization on a *Liveboard* can connect to different data objects. === Visualizations on a Liveboard The individual elements on a *Liveboard* are referred to as visualizations and are defined in the `visualizations` section. @@ -419,7 +433,7 @@ Within the TML, the `visualizations` section uses the same syntax as a separate [NOTE] ==== -If your instance is running 8.9.0.cl, do not create visualizations on a single *Liveboard* that connect to different *worksheets* with the *same name* (this is possible, as *worksheet* names are not unique) if you wish to do programmatic transformations, because it is impossible to add in the FQN properties based on just name if names are not unique. +If your instance is running 8.9.0.cl, do not create visualizations on a single *Liveboard* that connect to different *models* with the *same name* (this is possible, as *model* names are not unique) if you wish to do programmatic transformations, because it is impossible to add in the FQN properties based on just name if names are not unique. ==== === Modifying Liveboard TML @@ -450,9 +464,9 @@ The `layout` section is an ordered list with a `size` property for each visualiz == Views -link:https://docs.thoughtspot.com/cloud/latest/views[Views, window=_blank] transform a saved search into a data source, allowing for analysis that would require complex sub-queries in SQL. *Views* can be joined with other data objects in a *worksheet*. The best practice is to make *views* available to *answers* and *Liveboards* through a *worksheet*. +link:https://docs.thoughtspot.com/cloud/latest/views[Views, window=_blank] transform a saved search into a data source, allowing for analysis that would require complex sub-queries in SQL. *Views* can be joined with other data objects in a *model*. The best practice is to make *views* available to *answers* and *Liveboards* through a *model*. -The link:https://docs.thoughtspot.com/cloud/latest/tml-sql-views[TML syntax for views, window=_blank] is similar to that of worksheets, in that it defines links to table objects on the ThoughtSpot server and join overrides using the `joins` and `table_paths` sections. What truly distinguishes a view is the `search_query` element, which contains a string using the xref:search-data-api.adoc[ThoughtSpot search syntax]. +The link:https://docs.thoughtspot.com/cloud/latest/tml-sql-views[TML syntax for views, window=_blank] is similar to that of models, in that it defines links to table objects on the ThoughtSpot server and join overrides using the `joins` and `table_paths` sections. What truly distinguishes a view is the `search_query` element, which contains a string using the xref:search-data-api.adoc[ThoughtSpot search syntax]. [source,YAML] ---- diff --git a/modules/ROOT/pages/multi-tenancy-best-practices.adoc b/modules/ROOT/pages/multi-tenancy-best-practices.adoc index 91d35a474..604fc6d0d 100644 --- a/modules/ROOT/pages/multi-tenancy-best-practices.adoc +++ b/modules/ROOT/pages/multi-tenancy-best-practices.adoc @@ -69,9 +69,9 @@ Sharing is controlled through the UI (including when embedded) or via the xref:s Please see the full documentation on xref:access-control-sharing.adoc[sharing for access control] to learn how the various options work to isolate content for end customers that share a single "prod" environment. ==== What content should be shared? -While you can share individual tables from connections to users, the best practice is to create link:https://docs.thoughtspot.com/cloud/latest/worksheet-create[worksheets, window=_blank] and only share the relevant worksheets to end users. Any Liveboards and saved answers shared to users should only connect to worksheets. +While you can share individual tables from connections to users, the best practice is to create link:https://docs.thoughtspot.com/cloud/latest/worksheet-create[worksheets, window=_blank] and only share the relevant Models to end users. Any Liveboards and saved answers shared to users should only connect to Models. -Remember to share the Worksheet as *READ_ONLY* along with the Liveboards and answers so the users can access self-service features such as changing filter values. +Remember to share the Model as *READ_ONLY* along with the Liveboards and answers so the users can access self-service features such as changing filter values. === Column level security (CLS) groups link:https://docs.thoughtspot.com/cloud/latest/security-data-object#cls[Column level security, window=_blank] (CLS) can be configured at the individual table level through sharing. As with row-level security (RLS) groups, the best practice is to create separate groups specifically for the CLS groups. @@ -90,11 +90,11 @@ The "multi-tenant database model" is designed on the following principles: The multi-tenant database model is simpler to implement within ThoughtSpot than the single-tenant database model. Because data security is enforced via RLS in the multi-tenant database model, ThoughtSpot only requires a single version of any object to serve all tenants. Even if your production databases are split as single tenants, you may choose to bring everything into a single database within your cloud data warehouse to enable this model. ==== Content provided by app developer -The app developer (the ThoughtSpot customer) will create at minimum the data model objects within ThoughtSpot and typically some “pre-built” searches and Liveboards. Because there is a single database connection, there is only a need for one of each object. Row-level security at the table level will ensure that each user only sees data from their organization, even though they are connecting to the same Liveboards and worksheets. +The app developer (the ThoughtSpot customer) will create at minimum the data model objects within ThoughtSpot and typically some “pre-built” searches and Liveboards. Because there is a single database connection, there is only a need for one of each object. Row-level security at the table level will ensure that each user only sees data from their organization, even though they are connecting to the same Liveboards and Models. Objects created by the application developer to be shared with all users can be published by a single group that all users belong to; we’ll call this the “app content group” (the actual group name can be whatever you like, something like “prod standard reports”). The application group should be configured as *NOT SHAREABLE*, because every user will belong to this group. -In most cases, only worksheets should be shared to the end users, while the tables within the Worksheet do not (this is allowed by the default ThoughtSpot configuration). Thus there should be a separate group for just the tables; we’ll call this the “app data model group”. +In most cases, only Models should be shared to the end users, while the tables within the Model do not (this is allowed by the default ThoughtSpot configuration). Thus there should be a separate group for just the tables; we’ll call this the “app data model group”. If you want, you can publish all content in the application group from a single user representing the app developer or the application itself. @@ -110,7 +110,7 @@ Reminder: when a group is set to *NOT SHAREABLE*, administrators can still share |=== |Group type|Content shared to group|Users in group|Shareability |prod data model group|tables|app developer|NOT SHAREABLE -|standard content group|worksheets, answers, Liveboards|all users|NOT SHAREABLE +|standard content group|Models, Answers, Liveboards|all users|NOT SHAREABLE |tenant content groups (1 per tenant)|answers, Liveboards|tenant users per group|SHAREABLE |=== @@ -149,7 +149,7 @@ Tags can be used as part of searches using the Metadata REST APIs, with the cave Tags have no ownership and exist at the Server level, and all tags that exist are visible to all users at any time. Tags are visible in many places within the UI, particularly in the following places: * Data Source selector within search -* Pages that list the existing answers, Liveboards, worksheets, and tables. +* Pages that list the existing answers, Liveboards, Models, and Tables. Why does this matter, even if you are only embedding Liveboards? SSO into ThoughtSpot creates a session that allows the user to go directly into the ThoughtSpot web UI if they find the underlying URL. While the URL is not obvious when embedding ThoughtSpot content, it is also not difficult to determine with basic knowledge of the web development tools built into web browsers. diff --git a/modules/ROOT/pages/query-stats-action-ref b/modules/ROOT/pages/query-stats-action-ref new file mode 100644 index 000000000..a1c80c4fa --- /dev/null +++ b/modules/ROOT/pages/query-stats-action-ref @@ -0,0 +1,124 @@ +== User Action to Query Task Mapping + +This document provides a comprehensive mapping between user actions in the ThoughtSpot application and the corresponding tasks that appear in query stats files. + +=== Overview + +Query stats in ThoughtSpot track different types of queries executed by the system, categorized by "Query Triggers" (also known as tasks). These triggers help identify what user action or system process initiated a particular query, which is crucial for billing, performance analysis, and usage tracking. + +=== Query Stats Fields + +Each query in the stats file contains relevant fields like: + +* *query_trigger*: The enum value indicating what triggered the query +* *context*: Additional context information (often empty for datamanager queries) +* *user_id*: GUID of the user who initiated the action +* *user_name*: Display name of the user +* *connection_name*: Data source connection used +* *query_string*: The actual SQL query executed +== TOC + +. ?tab=t.0#heading=h.z78te7szg375[User Action to Query Stats Mappings] +. ?tab=t.0#heading=h.2wim8q5ospox[Exceptions] +=== User Action to Query Stats Mappings + +==== 📊 Answer/Search Related Actions + +|=== +|User Action|Query Trigger|Description + +|Edit an existing saved answer|ANSWER_EDIT|User modifies a saved answer, triggering query to show updated results +|View/Load a saved answer|ANSWER_VIEW|User opens an existing saved answer +|Perform a new search|SEARCH_DATA|User types a search query in the search bar +|Add filter to answer/search|GET_FILTER_VALUES|User adds or modifies filters, requiring filter value lookup. It will have +ANSWER_EDIT +also in the query stats file as the answer is also modified. +|=== + +==== 📋 Liveboard (Pinboard) Related Actions + +|=== +|User Action|Query Trigger|Description + +|Edit a liveboard|LIVEBOARD_EDIT|User modifies a liveboard (adding/removing visualizations, filters, etc.) +|View/Load a liveboard|LIVEBOARD_VIEW|User opens an existing liveboard +|=== + +==== 🔍 Data Exploration Actions + +|=== +|User Action|Query Trigger|Description + +|Click "Explore" on a visualization|EXPLORE|User explores underlying data from a chart/table +|View underlying data|UNDERLYING_DATA|User clicks "View underlying data" option +|Drill down on data points|DRILL_DOWN|User drills down from context menu or chart elements +|=== + +==== 💾 Export/Download Actions + +|=== +|User Action|Query Trigger|Description + +|Download data (CSV, Excel, PDF)|DOWNLOAD|User exports data in various formats +|=== + +==== 🤖 SpotIQ and Analytics Actions + +|=== +|User Action|Query Trigger|Description + +|Run SpotIQ auto analysis|SPOTIQ_AUTO_ANALYZE|User initiates automated insights analysis +|Run SpotIQ change analysis|SPOTIQ_CHANGE_ANALYSIS|User analyzes changes in data over time +|Set up KPI monitoring|KPI_MONITOR|User creates or views KPI monitors +|=== +==== 📱 Mobile and API Access + +|=== +|User Action|Query Trigger|Description + +|Access via mobile app|MOBILE|User performs actions through ThoughtSpot mobile app +|Access via REST API|APIS|Programmatic access via ThoughtSpot APIs +|=== +==== 📊 Others + +|=== +|User Action|Query Trigger|Description + +|Scheduled liveboard execution|SCHEDULED_PINBOARDS|Automated execution of scheduled liveboards +|ThoughtSpot Sync operations|TS_SYNC|Data synchronization triggered by user through Seekwell +|Report book generation|REPORTBOOK|User generates report books +|Use Cortex features|CORTEX|User interacts with AI-powered features +|Use Spotter search|SPOTTER|User performs natural language searches +|Custom calendar|CUSTOM_CALENDAR|custom calendar +|=== + +|=== +|System Process|Query Trigger|Description + +|Connection setup/testing|CDW_CONNECTION|Connection Creation +|Sample data|DATA_WORKSPACE_SAMPLE|samples data for tables +|SQL Editor operations|SQL_EDITOR|SQL editor +|dbt integration|DBT|dbt-related system queries +|Search indexing|SAGE_INDEXING|System builds search indexes +|Data sampling for search|SAGE_SAMPLING|System samples data for search optimization +|SpotApps operations|SPOT_APPS|SpotApps operations +|Row count statistics|ROW_COUNT_STATS|System collects table statistics +|Caffeine operations|CAFFEINE|Internal caching system queries +|Seed questions|SEED_QUESTIONS|System-generated example questions +|Unknown/Default|UNKNOWN|Queries that don't match other categories +|=== + +== 💾 Exceptions + +These are some cases where the Query Trigger differs from the intuitive expectation + +|=== +|User Action|Query Trigger|Description + +|LIVEBOARD DOWNLOAD PDF|LIVEBOARD_VIEW|User downloads liveboard +|SCHEDULED PINBOARD WITH PDF TYPE|+LIVEBOARD_VIEW+|User schedules liveboard with pdf type +|GET_FILTER_VALUES ON LIVEBOARD|+LIVEBOARD_EDIT+|User applies filter on liveboard +|GET_FILTER_VALUES ON ANSWER|+ANSWER_EDIT+|User applies filter on liveboard +|=== + + + + diff --git a/modules/ROOT/pages/rest-api-java-sdk.adoc b/modules/ROOT/pages/rest-api-java-sdk.adoc index 3d435b50d..472554c25 100644 --- a/modules/ROOT/pages/rest-api-java-sdk.adoc +++ b/modules/ROOT/pages/rest-api-java-sdk.adoc @@ -281,13 +281,13 @@ Note the recommendation of Java SDK: [options='header'] |==== |ThoughtSpot release version|Supported SDK version +a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.1 or later a|ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later |==== - == SDK Reference [width="100%" cols="3,5"] diff --git a/modules/ROOT/pages/rest-api-sdk-typescript.adoc b/modules/ROOT/pages/rest-api-sdk-typescript.adoc index 25e33d25a..345f4ffd3 100644 --- a/modules/ROOT/pages/rest-api-sdk-typescript.adoc +++ b/modules/ROOT/pages/rest-api-sdk-typescript.adoc @@ -203,6 +203,7 @@ Note the version recommendations for your ThoughtSpot instances: [options='header'] |==== |ThoughtSpot release version|Recommended SDK version +a|ThoughtSpot Cloud: 10.13.0.cl | v2.18.0 or later a|ThoughtSpot Cloud: 10.12.0.cl | v2.17.0 or later a|ThoughtSpot Cloud: 10.11.0.cl | v2.16.0 or later a|ThoughtSpot Cloud: 10.10.0.cl | v2.15.1 or later @@ -227,7 +228,6 @@ a|* ThoughtSpot Cloud: 9.7.0.cl + a|* ThoughtSpot Cloud: 9.6.0.cl + * ThoughtSpot Software: 9.8.0.sw | v2.0.2 or later - |==== For information about new features, breaking changes, and deprecated parameters, see xref:rest-apiv2-changelog.adoc[API changelog]. diff --git a/modules/ROOT/pages/rest-api-v1.adoc b/modules/ROOT/pages/rest-api-v1.adoc index ea2f4ba1c..9f51515df 100644 --- a/modules/ROOT/pages/rest-api-v1.adoc +++ b/modules/ROOT/pages/rest-api-v1.adoc @@ -35,7 +35,7 @@ For example, in the `\https:///callosum/v1/tspub ThoughtSpot REST API endpoints support Create, Read, Update and Delete (CRUD) operations and allow applications to use the standard HTTP verbs in API requests: * `GET` to query information, such as getting a list of users or groups. -* `POST` to create and add new properties to a resource, such as a user, group, Answer, Worksheet, or a data object. +* `POST` to create and add new properties to a resource, such as a user, group, Answer, Model, or a data object. * `PUT` to update the properties of an existing resource, such as modifying the properties of a user or user group. * `DELETE` to remove an object or object association. diff --git a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc index ec205b935..718d098b8 100644 --- a/modules/ROOT/pages/rest-api-v2-metadata-search.adoc +++ b/modules/ROOT/pages/rest-api-v2-metadata-search.adoc @@ -44,14 +44,14 @@ If you do not send specific object IDs as part of your request, the API lists al For information about the supported object types, see link:https://developers.thoughtspot.com/docs/restV2-playground?apiResourceId=http%2Fmodels%2Fenumerations%2Ftype-3[API Playground]. === Subtypes for LOGICAL_TABLE -For metadata types such as Worksheets (Deprecated), Models, Tables, and Views, set the `type` to `LOGICAL_TABLE`. When `type` is set as `LOGICAL_TABLE` and no object identifier is specified in the request, the API returns all available objects in ThoughtSpot. To get a complete list of `LOGICAL_TABLE` objects, set the `record_size` attribute to a desired value and configure xref:rest-api-v2-metadata-search.adoc#_pagination_settings[pagination settings]. +For metadata types such as Models, Tables, and Views, set the `type` to `LOGICAL_TABLE`. When `type` is set as `LOGICAL_TABLE` and no object identifier is specified in the request, the API returns all available objects in ThoughtSpot. To get a complete list of `LOGICAL_TABLE` objects, set the `record_size` attribute to a desired value and configure xref:rest-api-v2-metadata-search.adoc#_pagination_settings[pagination settings]. For `LOGICAL_TABLE` object type, you can also specify the subtype as an additional option to filter API response. You can specify one of the following values to define the `LOGICAL_TABLE` subtype: * `ONE_TO_ONE_LOGICAL` for Tables. -* `WORKSHEET` for Models or Worksheets (Deprecated). -* `PRIVATE_WORKSHEET` for private Worksheets or Models. +* `WORKSHEET` for data objects such as Models +* `PRIVATE_WORKSHEET` for private data objects such as Models. * `USER_DEFINED` for data imported from other sources such as a CSV file. * `AGGR_WORKSHEET` for Views. A *View* in ThoughtSpot refers to a Table materialized from a saved Answer that was saved as a View by a user. * `SQL_VIEW` for SQL Views. An SQL View is a virtual table and data source created from writing and saving a SQL query against your external data warehouse connection. diff --git a/modules/ROOT/pages/rest-api-v2-reference-beta.adoc b/modules/ROOT/pages/rest-api-v2-reference-beta.adoc index f248436d7..0b551fd5d 100644 --- a/modules/ROOT/pages/rest-api-v2-reference-beta.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference-beta.adoc @@ -577,7 +577,7 @@ Gets details of one or several metadata objects of a specific type. `*DELETE* /tspublic/rest/v2/metadata/delete` -Deletes the specified metadata object. You can delete answers, Liveboards, tags, worksheets, views, tables, columns, and table joins. + +Deletes the specified metadata object. You can delete answers, Liveboards, Tags, Models, Views, Tables, Columns, and Table joins. + Note that the endpoint does not support deleting the connection, user, and group objects. To delete these objects, use the following endpoints: * `DELETE /tspublic/rest/v2/connection/delete` diff --git a/modules/ROOT/pages/rest-api-v2-reference.adoc b/modules/ROOT/pages/rest-api-v2-reference.adoc index a13b46c40..603f8ca48 100644 --- a/modules/ROOT/pages/rest-api-v2-reference.adoc +++ b/modules/ROOT/pages/rest-api-v2-reference.adoc @@ -21,10 +21,31 @@ Access to ThoughtSpot data is controlled based on xref:api-user-management.adoc# |===== |API endpoint| Release version | Playground link +a|`PPOST /api/rest/2.0/ai/agent/conversation/create` + +Creates a conversation session with ThoughtSpot's Spotter agent. +|ThoughtSpot Cloud: __10.13.0.cl or later__ + +ThoughtSpot Software: __Not available__ a| +++Try it out+++ + a|`POST /api/rest/2.0/ai/conversation/create` + -Creates a conversation session with ThoughtSpot Spotter, your AI Analyst. +Creates a conversation session with ThoughtSpot Spotter |ThoughtSpot Cloud: __10.4.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ + +a|`POST /api/rest/2.0/ai/data-source-suggestions` +Gets data source recommendations for a given query. +|ThoughtSpot Cloud: __10.13.0.cl or later__ + +|+++Try it out+++ + +a|`POST /api/rest/2.0/ai/relevant-questions/` +Breaks down a user submitted query into relevant questions +|ThoughtSpot Cloud: __10.13.0.cl or later__ + +|+++Try it out+++ + +a| `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. +|ThoughtSpot Cloud: __10.13.0.cl or later__ +| +++Try it out+++ + a| `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` + Generates responses to user queries and follow-up questions sent in the specified conversation session. |ThoughtSpot Cloud: __10.4.0.cl or later__ + @@ -34,10 +55,10 @@ a|`POST /api/rest/2.0/ai/answer/create` + Generates an Answer for a Natural Language Search query. |ThoughtSpot Cloud: __10.4.0.cl or later__ + ThoughtSpot Software: __Not available__ a| +++Try it out+++ - |===== -- + == Authentication [div boxAuto] @@ -376,7 +397,7 @@ ThoughtSpot Software: __10.0.0.sw or later__ a| a|`POST /api/rest/2.0/dbt/generate-sync-tml` + -Resynchronizes the existing list of Models, Tables, and Worksheet TML content for the specified DBT connection object and imports these to Thoughtspot. +Resynchronizes the existing list of Models and Tables TML content for the specified DBT connection object and imports these to Thoughtspot. |ThoughtSpot Cloud: __9.10.0.cl or later__ + ThoughtSpot Software: __10.0.0.sw or later__ a| @@ -400,7 +421,7 @@ ThoughtSpot Software: __10.0.0.sw or later__ a| +++Try it out+++ -a|`POST /api/rest/2.0/customization/email/{template_identifier}/delete` +a|`POST /api/rest/2.0/customization/email/delete` Deletes the existing customized configuration set for the notification emails. -|ThoughtSpot Cloud: __10.10.0.cl or later__ a| +++Try it out+++ +|ThoughtSpot Cloud: __10.10.0.cl or later__ a| +++Try it out+++ a|`POST /api/rest/2.0/customization/email/search` + @@ -427,6 +448,13 @@ Searches the customized configuration set for the notification emails. |ThoughtSpot Cloud: __10.10.0.cl or later__ a| +++Try it out +++ +a|`POST /api/rest/2.0/customization/email/update` + + +Updates an existing email customization set for the notification emails. + +|ThoughtSpot Cloud: __10.12.0.cl or later__ a| ++++Try it out +++ + a|`POST /api/rest/2.0/customization/email/validate` + Validates the customized configuration set for the notification emails. diff --git a/modules/ROOT/pages/rest-apiv2-changelog.adoc b/modules/ROOT/pages/rest-apiv2-changelog.adoc index d5d3053ba..5db1c0095 100644 --- a/modules/ROOT/pages/rest-apiv2-changelog.adoc +++ b/modules/ROOT/pages/rest-apiv2-changelog.adoc @@ -8,6 +8,61 @@ This changelog lists the features and enhancements introduced in REST API v2.0. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 10.14.0.cl, October 2025 + +=== New API endpoints + +Spotter:: + +* `POST /api/rest/2.0/ai/agent/conversation/create` + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + + +* `POST /api/rest/2.0/ai/data-source-suggestions` + +Returns a list of relevant data sources, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + + +* `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. Provides a list of recommended or relevant questions for a given data source and conversation context to allow users to explore their data further. + + +* `POST /api/rest/2.0/ai/agent/converse/sse` + +Allows sending a follow-up message or question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +Email customization:: +* `POST /api/rest/2.0/customization/email/delete` + +Updates an existing email customization. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + + +=== API enhancements +The following APIs were modified to include new parameters: + +TML export:: +The TML export API now supports the `export_with_column_aliases` parameter in `export_options` to indicate whether to export column aliases of the model. + +Email customization:: +The `/api/rest/2.0/customization/email/update` and `/api/rest/2.0/customization/email` APIs now include `company_privacy_policy_url` and `company_website_url` properties in template variables, and a new `org_identifier` parameter in the API request. + +For more information, see xref:customize-email-apis.adoc[Customize email template]. + +=== Deprecated endpoints +Spotter:: +The `POST /api/rest/2.0/ai/analytical-questions` Spotter AI API [beta betaBackground]^Beta^ is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/ai/relevant-questions/`. + +Email customization:: +The `POST /api/rest/2.0/customization/email/{template_identifier}/delete` email customization API is deprecated and replaced with the new API endpoint, `POST /api/rest/2.0/customization/email/delete` [beta betaBackground]^Beta^. + + +//// +=== Deprecated endpoints +The following Spotter AI APIs [beta betaBackground]^Beta^ are deprecated and replaced with the new xref:spotter-apis.adoc[AI APIs]. + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/analytical-questions` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +//// + == Version 10.12.0.cl, September 2025 === New API endpoints diff --git a/modules/ROOT/pages/rls-rules.adoc b/modules/ROOT/pages/rls-rules.adoc index 39bab8049..678ba17d6 100644 --- a/modules/ROOT/pages/rls-rules.adoc +++ b/modules/ROOT/pages/rls-rules.adoc @@ -13,7 +13,7 @@ The two basic patterns for RLS Rules are *direct RLS rules* that reference a col If neither of these patterns is easily implemented, please consider the xref:abac-user-parameters.adoc[ABAC via tokens] method of RLS, available starting in ThoughtSpot 9.11. == RLS rules overview -*RLS rules* are link:https://docs.thoughtspot.com/cloud/latest/security-rls-implement[defined within ThoughtSpot, target=_blank] on table objects, and automatically extend to all worksheets, saved answers, and Liveboards based on that table, every time. +*RLS rules* are link:https://docs.thoughtspot.com/cloud/latest/security-rls-implement[defined within ThoughtSpot, target=_blank] on table objects, and automatically extend to all Models, saved answers, and Liveboards based on that table, every time. RLS rules are defined using either the *ts_username* variable or *ts_groups* variable. The RLS rules translate into WHERE clauses in any SQL query generated from that table object, with the variables expanding into the details of the signed-in user. *ts_groups* turns into the set of *group name* properties of the ThoughtSpot groups the user belongs to. diff --git a/modules/ROOT/pages/roles.adoc b/modules/ROOT/pages/roles.adoc index f35d70bca..e503f86a2 100644 --- a/modules/ROOT/pages/roles.adoc +++ b/modules/ROOT/pages/roles.adoc @@ -162,7 +162,7 @@ UI: *Can upload user data* |Allows users to upload data to ThoughtSpot. UI: *Can administer and bypass RLS* a|Allows access to the following operations: * Create, edit, or delete existing RLS rules -* Enable or disable Bypass RLS on a worksheet +* Enable or disable Bypass RLS on a Model For more information, see link:https://docs.thoughtspot.com/cloud/latest/security-rls[Row-level security, window=_blank]. |Custom calendars|API: `CAN_MANAGE_CUSTOM_CALENDAR` + UI: *Can manage custom calendars* | Allows creating, editing, and deleting link:https://docs.thoughtspot.com/cloud/latest/connections-cust-cal[custom Calendars, window=_blank]. @@ -170,7 +170,7 @@ UI: *Can manage custom calendars* | Allows creating, editing, and deleting link: |Data Connection|API: `CAN_CREATE_OR_EDIT_CONNECTIONS` + UI: *Can create/edit Connections*| Allows creating, editing, and managing link:https://docs.thoughtspot.com/cloud/latest/connections[connections to external data warehouses, window=_blank]. |Data objects|API: `CAN_MANAGE_WORKSHEET_VIEWS_TABLES` + -UI: *Can manage data models* |Allows users to create, edit, delete, and manage Worksheets, Models, Tables, and Views. +UI: *Can manage data models* |Allows users to create, edit, delete, and manage Models, Tables, and Views. |=== diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 22c422225..9711498ff 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -132,7 +132,7 @@ https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan&col2=p === Runtime filters in Visual Embed SDK -If you are embedding a Liveboard, visualization, or Answer using xref:VisualEmbedSdk.adoc[Visual Embed SDK], you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. +If you are embedding Spotter, Liveboard, visualization or the full application using xref:VisualEmbedSdk.adoc[Visual Embed SDK], you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. The following example shows how to apply runtime filters on an embedded visualization in the SDK. Here, the runtime filter is operating on the `Revenue` column to filter the data matching `100000`. @@ -503,6 +503,11 @@ liveboardEmbed.trigger(HostEvent.UpdateRuntimeFilters, [{ ]) ---- +[NOTE] +==== +In Spotter embed, updating filters via host and embed events may not work. +==== + For more information, see xref:HostEvent.adoc#_updateruntimefilters[UpdateRuntimeFilters] and xref:embed-events.adoc#_filters_in_embedded_ui[Filters in embedded UI]. === URL format when embedding without SDK @@ -750,15 +755,15 @@ https://{ThoughtSpot-Host}/?col1=State&op1=EQ&val1=California&col2=product&op2=B == Limitations of runtime filters * The `DATE` and `DATE_TIME` data types must be specified as EPOCH time (Unix or POSIX time) in runtime filters. -* Runtime filters work only on Answers and Liveboard visualizations built from Worksheets. Runtime filters on visualizations and Answers built directly from Tables, Views, and SQL Views do not work because the possibility of multiple join paths and join path choice is not supported as input in runtime filters. +* Runtime filters work only on Answers and Liveboard visualizations built from Models. Runtime filters on visualizations and Answers built directly from Tables, Views, and SQL Views do not work because the possibility of multiple join paths and join path choice is not supported as input in runtime filters. * Runtime filters do not allow you to apply `HAVING` filters in the URL parameters. //// -* You cannot apply a runtime filter on a Liveboard or visualization built from tables and worksheets that have chasm traps. +* You cannot apply a runtime filter on a Liveboard or visualization built from Tables and Models that have chasm traps. -* Runtime filters do not work directly on top of tables. You must create a Worksheet if you want to use runtime filters. This means that the Liveboard or visualization on which you apply a runtime filter must be created on top of a Worksheet. +* Runtime filters do not work directly on top of tables. You must create a Model if you want to use runtime filters. This means that the Liveboard or visualization on which you apply a runtime filter must be created on top of a Model. -* If the Worksheet was created from an Answer (it is an aggregated Worksheet), runtime filters will only work if the Answer was formed using a single Worksheet. If the Answer from which the Worksheet was created includes raw tables or joins multiple worksheets, you won't be able to use runtime filters on it. This is because of the join path ambiguity that could result. +* If the Model was created from an Answer (it is an aggregated Model), runtime filters will only work if the Answer was formed using a single Model. If the Answer from which the Model was created includes raw tables or joins multiple Models, you won't be able to use runtime filters on it. This is because of the join path ambiguity that could result. //// diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 88ae1d14c..5a55702a4 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -34,3 +34,4 @@ Like runtime filters, Parameters can be applied on ThoughtSpot Liveboards and An After the object loads, Parameter values can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event. For more information and examples, see xref:runtime-parameters.adoc[Runtime Parameters]. + diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 66c86e973..326be6db7 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -6,7 +6,7 @@ :page-pageid: runtime-params :page-description: Use Parameters to run multiple scenarios with adjustable values, without changing your answer. -ThoughtSpot lets you create Parameters in a Worksheet and integrate them into formulas, filters, data queries, and Liveboards. +ThoughtSpot lets you create Parameters in a Model and integrate them into formulas, filters, data queries, and Liveboards. == About Parameters Parameters are useful for "what-if" analysis, financial planning, cohort analysis, and so on. Parameters allow users to visualize data by running different scenarios with adjustable values. With Parameters, business users can use a single report and adjust the values dynamically to fit the scenario they want to analyze. @@ -49,7 +49,7 @@ new Date('2020-05-22').getTime() / 1000 == Apply Parameter overrides in Visual Embed SDK -The Visual Embed SDK v1.25.0 and later support Parameter overrides on embedded Liveboards and Answers. Before applying a Parameter override on an Answer or Liveboard object, make sure the Parameters and associated formulas are configured in the Worksheet used for generating charts and tables. +The Visual Embed SDK v1.25.0 and later support Parameter overrides on embedded Liveboards and Answers. Before applying a Parameter override on an Answer or Liveboard object, make sure the Parameters and associated formulas are configured in the Model used for generating charts and tables. The following example shows how to apply multiple runtime filters on a Liveboard embedded using the SDK: @@ -82,6 +82,16 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ } ]) ---- +=== Runtime Parameters in Spotter Embed + +* Saving or pinning an answer does not retain the parameter itself; only the parameter value is stored. In future releases, saved chats will also not retain the parameter, just the value. +* Users can see the parameter value in formulas, but only the value set for them is visible. Parameter values cannot be changed in the middle of a conversation session and may result in unintended effects. +* If a user adds a parameter to an answer through the edit flow, Spotter may drop this parameter and any formulas using it in follow-up interactions. This means parameters added in this way are not guaranteed to persist in subsequent conversational steps. + +[NOTE] +==== +In Spotter embed, updating Parameters via host and embed events may not work. +==== == Runtime parameters in object URLs @@ -113,7 +123,7 @@ ThoughtSpot returns an error if an object URL with Parameter attributes exceeds == Apply Parameter overrides via REST API You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. -Before applying a Parameter override on a Liveboard or Answer object, ensure that the Parameters are configured in the source Worksheet. +Before applying a Parameter override on a Liveboard or Answer object, ensure that the Parameters are configured in the source Model. === REST API v1 You can apply runtime Parameters when sending an API request to the following v1 Data API endpoints: @@ -329,7 +339,7 @@ Setting a Parameter value via a JWT token will not hide the Parameter value by d Regardless of the user's interaction with the Parameter chip, Parameter values initiated via the JWT token cannot be overridden through the UI, to guarantee its use for security purposes only. -ThoughtSpot recommends hiding the Parameter chip while using a JWT token to minimize confusion. To do so, set the `is_hidden` flag to `true` in the Worksheet TML for all Parameter columns that you wish to hide from ThoughtSpot's user interface: +ThoughtSpot recommends hiding the Parameter chip while using a JWT token to minimize confusion. To do so, set the `is_hidden` flag to `true` in the Model TML for all Parameter columns that you wish to hide from ThoughtSpot's user interface: [.widthAuto] image:./images/parameter_hidden.png[Parameter hidden] @@ -338,7 +348,7 @@ image:./images/parameter_hidden.png[Parameter hidden] [options='header'] |===== |Is the Parameter value passed via a JWT?| -Is the `is_hidden` property enabled for the Parameter in the Worksheet/Model? |Parameter chip behavior +Is the `is_hidden` property enabled for the Parameter in the Model? |Parameter chip behavior |Yes|No| The Parameter chip is visible and shows the parameter's default value. It uses the Parameter value defined in the JWT in the data. User interactions with the filter chip will be ignored due to Parameter value defined via JWT token being locked. diff --git a/modules/ROOT/pages/search-assist-tse.adoc b/modules/ROOT/pages/search-assist-tse.adoc index 2374f060a..2cc219c6a 100644 --- a/modules/ROOT/pages/search-assist-tse.adoc +++ b/modules/ROOT/pages/search-assist-tse.adoc @@ -11,12 +11,12 @@ Search Assist feature is deprecated and is not available in ThoughtSpot 10.4.0.cl and later versions. ==== -The Search Assist feature provides sample scenarios of searching data from a Worksheet. Your application users can use this feature to familiarize themselves with the search experience and get the answers they need. +The Search Assist feature provides sample scenarios of searching data from a Model. Your application users can use this feature to familiarize themselves with the search experience and get the answers they need. To enable the Search Assist walkthrough on an embedded instance, the following steps are required: * Enable Search Assist in the Visual Embed SDK -* Configure Search Assist questions and answers (__Requires `Can manage data` privilege and edit access to a worksheet__) +* Configure Search Assist questions and answers (__Requires `Can manage data` privilege and edit access to a Model__) == Enable Search Assist in the SDK @@ -43,7 +43,7 @@ const searchEmbed = new SearchEmbed(document.getElementById('ts-embed'), { By default, the Sample Retail link:https://docs.thoughtspot.com/cloud/latest/system-worksheet[system Worksheet, window=_blank] includes a Search Assist lesson with a predefined set of questions and instructions to guide your application users. -To provide Search Assist walkthrough to your users with your own data, you must create a Search Assist lesson on your Worksheet. ThoughtSpot provides sample question templates, using which you can create your own Search Assist content. Any ThoughtSpot user with `Can manage data` privilege and edit access to the Worksheet can configure a Search Assist lesson. For more information about configuring a sample search lesson, see link:https://docs.thoughtspot.com/cloud/latest/search-assist-coach[Search Assist Coach, window=_blank]. +To provide Search Assist walkthrough to your users with your own data, you must create a Search Assist lesson on your Model. ThoughtSpot provides sample question templates, using which you can create your own Search Assist content. Any ThoughtSpot user with `Can manage data` privilege and edit access to the Model can configure a Search Assist lesson. For more information about configuring a sample search lesson, see link:https://docs.thoughtspot.com/cloud/latest/search-assist-coach[Search Assist Coach, window=_blank]. //// If Search Assist is enabled on your embedded instance, the sample queries and instructions will appear when your users log in to ThoughtSpot for the first time and go through the onboarding process. @@ -51,9 +51,9 @@ If Search Assist is enabled on your embedded instance, the sample queries and in == How to use Search Assist -Search Assist walks you through simple search scenarios, using data from the Search Assist lesson created for a Worksheet. If Search Assist is enabled, and your Worksheet has the Search Assist queries configured, the embedded Search page allows you to try sample search scenarios. +Search Assist walks you through simple search scenarios, using data from the Search Assist lesson created for a Model. If Search Assist is enabled, and your Model has the Search Assist queries configured, the embedded Search page allows you to try sample search scenarios. -For example, if you are searching data from the Sample Retail Worksheet, the initial example asks *_What were Sales by Product in this year?_* and Search Assist guides you to select *_sales_* and press *Enter* on your keyboard. The search then returns the Answer as a table, demonstrating your total sales. +For example, if you are searching data from the Sample Retail Model, the initial example asks *_What were Sales by Product in this year?_* and Search Assist guides you to select *_sales_* and press *Enter* on your keyboard. The search then returns the Answer as a table, demonstrating your total sales. Similarly, you can add keywords, such as *_product_* and *_this year_* to your search and press *Enter* to get an Answer with the total sales data for each product in the current year. @@ -61,8 +61,8 @@ Similarly, you can add keywords, such as *_product_* and *_this year_* to your s * Search Assist is available on instances that have ThoughtSpot Search functionality embedded using `SearchEmbed` or `AppEmbed` SDK library. * Sample search queries and search experience walkthrough are available to users only if a Search Assist lesson is configured at the data source level. -* Search Assist lessons can be configured only on worksheets. -* To configure a Search Assist lesson on a Worksheet, make sure you have embedded the ThoughtSpot *Data* tab in your host app. +* Search Assist lessons can be configured only on Models. +* To configure a Search Assist lesson on a Model, make sure you have embedded the ThoughtSpot *Data* tab in your host app. //// == Related resources diff --git a/modules/ROOT/pages/search-data-api.adoc b/modules/ROOT/pages/search-data-api.adoc index 2e1f6c200..111e465d0 100644 --- a/modules/ROOT/pages/search-data-api.adoc +++ b/modules/ROOT/pages/search-data-api.adoc @@ -27,7 +27,7 @@ To query data using the API, follow these steps: [#get-guid] === Determine the GUID of the data source -To find the GUID of the Worksheet, View, or Table, use one of the following methods: +To find the GUID of the Model, View, or Table, use one of the following methods: Get data object GUID via API:: @@ -39,7 +39,7 @@ Send an API request to the `/api/rest/2.0/metadata/search` v2 API endpoint with ---- "metadata": [ { - "identifier": "my_worksheet", + "identifier": "my_data_model", "type": "LOGICAL_TABLE" } ] @@ -55,7 +55,7 @@ Find the GUID of the data object via UI:: ---- https:///#/data/tables/ ---- -. On the **Data** > **Home** page, select the data object. For example, if the data source object is a Worksheet, click **Worksheets** and then open the Worksheet. +. On the **Data** > **Home** 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`: + ---- @@ -131,7 +131,7 @@ POST /tspublic/v1/searchdata | Query parameter | Description |`query_string` |__String__. The data search query string. For more information, see xref:search-data-api.adoc#components[Components of a search query]. -|`data_source_guid` |__String__. The GUID of the data source, either a Worksheet, a View, or a table. +|`data_source_guid` |__String__. The GUID of the data source, either a Model, a View, or a table. |`batchsize` |__Integer__. The batch size for loading search objects. diff --git a/modules/ROOT/pages/security-api.adoc b/modules/ROOT/pages/security-api.adoc index b11d632f1..5a4adb304 100644 --- a/modules/ROOT/pages/security-api.adoc +++ b/modules/ROOT/pages/security-api.adoc @@ -41,8 +41,8 @@ POST /tspublic/v1/security/share * `QUESTION_ANSWER_BOOK` to share answers. * `PINBOARD_ANSWER_BOOK` to share Liveboards. -* `LOGICAL_TABLE` to share a data object such as a table, Worksheet, or View. -* `LOGICAL_COLUMN` to share a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` to share a data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` to share a column of any data object such as Tables, Models, or Views. |`id`|__String__. A JSON array of the GUIDs of the objects to be shared. |`permission` a|_String__. A string with the GUIDs of the user or user group, and the type of access privilege. @@ -203,8 +203,8 @@ GET /tspublic/v1/security/metadata/permissions * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or View. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as tables, models, or views. |`id`| Query parameter|__String__. A JSON array of the GUIDs of the objects. |`dependentshare` __Optional__|Query parameter|__Boolean__. Object permission details for the dependent objects. When set to `true`, the API returns the permission details for the dependent objects for the specified GUIDs. @@ -334,8 +334,8 @@ GET /tspublic/v1/security/metadata/{id}/permissions * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or View. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. |`id`| Path parameter|__String__. The GUID of the object to query. |`dependentshare` __Optional__|Query parameter|__Boolean__. Object permission details for the dependent objects. When set to `true`, the API returns the permission details for the dependent objects for the specified GUID. @@ -448,8 +448,8 @@ POST /tspublic/v1/security/effectivepermissionbulk * `QUESTION_ANSWER_BOOK` for answers. * `PINBOARD_ANSWER_BOOK` for Liveboards. -* `LOGICAL_TABLE` for any data object such as a table, Worksheet, or View. -* `LOGICAL_COLUMN` for a column of any data object such as tables, worksheets, or views. +* `LOGICAL_TABLE` for any data object such as a Table, Model, or View. +* `LOGICAL_COLUMN` for a column of any data object such as Tables, Models, or Views. For example, to get permission details for specific Liveboards and answers, specify the value of `idsbytype` as shown here: ---- diff --git a/modules/ROOT/pages/single-tenant-data-models.adoc b/modules/ROOT/pages/single-tenant-data-models.adoc index 01270e3e7..426472196 100644 --- a/modules/ROOT/pages/single-tenant-data-models.adoc +++ b/modules/ROOT/pages/single-tenant-data-models.adoc @@ -70,9 +70,9 @@ Reminder: when a group is set to *NOT SHAREABLE*, administrators can still share [options='header'] |=== |Group type|Content shared to group|Users in group|Sharability -|prod template group|Template tables, worksheets, answers, Liveboards|app developer|SHAREABLE +|prod template group|Template Tables, Models, Answers, Liveboards|app developer|SHAREABLE |standard data groups (1 per tenant)|tables (connected to tenant connection)|app developer|NOT SHAREABLE -|standard content groups (1 per tenant)|worksheets, answers, Liveboards|tenant users per group|NOT SHAREABLE +|standard content groups (1 per tenant)|Models, Answers, Liveboards|tenant users per group|NOT SHAREABLE |tenant content groups (1 per tenant)|answers, Liveboards|tenant users per group|SHAREABLE |=== diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 7acd3b9f7..0efe06fdb 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -1,4 +1,4 @@ -= Generate Answers from AI APIs [beta betaBackground]^Beta^ += Spotter AI APIs :toc: true :toclevels: 3 @@ -6,27 +6,149 @@ :page-pageid: spotter-api :page-description: You can use Spotter REST APIs to receive Answers for your analytical queries sent through the conversational experience with ThoughtSpot. -ThoughtSpot provides a set of Spotter AI APIs [beta betaBackground]^Beta^ to create a conversation session with Spotter, ask follow-up questions, and generate Answers for their analytic queries. +ThoughtSpot provides a set of Spotter AI APIs [beta betaBackground]^Beta^ to create a conversation session with Spotter, ask follow-up questions, and generate Answers for their analytic queries. These APIs collectively enable natural language interaction, context-aware analytics, and guided data analysis. -This article describes how to use ThoughtSpot REST APIs for the following operations: +[NOTE] +==== +The Spotter AI APIs are in beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support. +==== -* xref:spotter-apis.adoc#createManageConversations[Create a conversation and ask follow-up questions] -* xref:spotter-apis.adoc#_generate_a_single_answer[Generate a single Answer for a natural language query] -* xref:spotter-apis.adoc#process_results[Process results generated from Spotter APIs] +== Overview +The AI APIs [beta betaBackground]^Beta^ enable agentic conversational analytics by allowing users and systems to interact with data using natural language. Each of these APIs serves a specific function: -[#createManageConversation] -== Create and manage conversations -Use the following Spotter AI APIs to initiate a conversation with Spotter and ask follow-up questions. +[width="100%" cols="2,4"] +[options='header'] +|===== +|Purpose| API endpoints +|xref:spotter-apis.adoc#_create_a_conversation_session[Create a conversation session] a| * xref:spotter-apis.adoc#_create_a_conversation_session_with_spotter_agent[`POST /api/rest/2.0/ai/agent/conversation/create`] + +Creates a new AI-driven conversation session based on a specified data source. The resulting session sets the context for subsequent queries and responses. + +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. + +* xref:spotter-apis.adoc#_create_a_conversation_session_legacy_api_endpoint[`POST /api/rest/2.0/ai/conversation/create`] + +Creates a conversation session. + +__This is a legacy API and will be deprecated in an upcoming release version__. + + +|xref:spotter-apis.adoc#_get_relevant_questions[Get relevant questions] a| * `POST /api/rest/2.0/ai/relevant-questions/` + +Breaks down a user-submitted query into a series of analytical sub-questions using relevant contextual metadata. Provides a list of recommended or relevant questions for a given data source and conversation context to allow users to explore their data further. + +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. + +|xref:spotter-apis.adoc#_send_a_question_to_a_conversation_session[Send queries to a conversation session] a| +* xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[`POST /api/rest/2.0/ai/agent/converse/sse`] (Recommended for agentic workflows) + +Allows sending a natural language query or a follow-up question to an ongoing conversation session and returns the AI agent's response, including answers, tokens, and visualization details. + +__Available on ThoughtSpot Cloud instances from 10.13.0.cl onwards__. + +* xref:spotter-apis.adoc#_send_a_question_to_generate_answer[`POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse`] + +Allows sending a follow-up message to an ongoing conversation within the context of the metadata model. +__This is a legacy API and will be deprecated in an upcoming release version__. + +|xref:spotter-apis.adoc#_generate_a_single_answer[Generate a single answer] a| * `POST /api/rest/2.0/ai/answer/create` + +Allows users to submit a natural language search query and fetch an AI-generated response. + +|xref:spotter-apis.adoc#_get_data_source_suggestions[Get data source suggestions] a| * `POST /api/rest/2.0/ai/data-source-suggestions` + +Returns a list of relevant data sources, such as Models, based on a query and thus helping users and agents choose the most appropriate data source for analytics. + +__Limited availability on ThoughtSpot Cloud instances from 10.13.0.cl onwards. Please contact ThoughtSpot Support to enable this feature on your instance__. +|===== -* xref:spotter-apis.adoc#_create_conversation[Create a conversation session] -* xref:spotter-apis.adoc#ask_question[Send a question to an ongoing conversation] +//// +[NOTE] +==== +* The `/api/rest/2.0/ai/conversation/create` and `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoints will be deprecated in an upcoming release version. Therefore, ThoughtSpot recommends updating your implementation to use the `/api/rest/2.0/ai/agent/conversation/create` and `POST /api/rest/2.0/ai/agent/converse/sse` API endpoints. +* To process results generated from a Spotter query, you can use the `/api/rest/2.0/report/answer` API endpoint. You can also use the tokens obtained from the API response as search inputs in the search data API request. +==== +//// + + +== Create a conversation session +A conversation session acts as a container for maintaining continuity across user inputs, system responses, and agent-driven clarifications. Once created, users can send queries or ask follow-up questions to the conversation session to explore data and get further insights. + +The following AI API endpoints allow you to initiate a conversation session with Spotter: + +* xref:spotter-apis.adoc#_create_a_conversation_session_with_spotter_agent[`POST /api/rest/2.0/ai/agent/conversation/create`] +* xref:spotter-apis.adoc#_create_a_conversation_session_legacy_api_endpoint[`POST /api/rest/2.0/ai/conversation/create`] + +__This is a legacy API endpoint and will be deprecated in an upcoming release version__. + +=== Create a conversation session with Spotter agent +The `/api/rest/2.0/ai/agent/conversation/create` API endpoint allows you to initiate a new conversation session with ThoughtSpot's AI Agent. Developers and system integrators embedding Spotter into agentic workflows, custom applications, or internal MCP (Managed Content Platform) servers, can use this API endpoint to create a conversation session from different data contexts such as Answers, Liveboards, or Models. [NOTE] ==== -The Spotter AI APIs are in beta and disabled by default on ThoughtSpot instances. To enable these APIs on your instance, contact ThoughtSpot Support. +Clients must have at least view access to the objects specified in the API request to create a conversation context and use it for subsequent queries. ==== -=== Create a conversation session +==== Request parameters +To set the context for the conversation session, you must specify the metadata type and context in the `POST` request body. Optionally, you can also define additional parameters to refine the data context and generate accurate and precise responses. + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Form parameter| Description +|`metadata_context` a| Defines the data context for the conversation. Specify the following values: + +* `type` + +Metadata type. Valid values are: +** `answer` - To use an existing Spotter-generated Answer as the object +** `liveboard` - To use an existing Liveboard as data object +** `data_source` - To create a new conversation session using data objects such as Model. ++ + +* `answer_context` + +If the metadata type is set as `answer`, specify the following attributes: +** `session_identifier`: __string__, Unique ID representing the answer session. +** `generation_number`: __Integer__. Specific generation/version number of the answer within a conversation session. ++ +The session identifier and generation numbers are assigned to the Answers generated from the Spotter AI REST APIs. These properties serve as the ID of the AI-generated Answer within the ThoughtSpot system. + +* `liveboard_context` + +If the metadata type is set as `liveboard`, specify the GUID of the Liveboard and visualization. +* `data_source_context` + +If the metadata type is set as `data_source`, specify the GUID of the data source object. + +|`conversation_settings` a|__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. +|===== + +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/conversation/create' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "metadata_context": { + "type": "data_source", + "data_source_context": { + "guid": "cd252e5c-b552-49a8-821d-3eadaa049cca" + } + }, + "conversation_settings": { + "enable_contextual_change_analysis": false, + "enable_natural_language_answer_generation": true, + "enable_reasoning": false + } +}' +---- + +==== API response + +If the API request is successful, the API returns the conversation ID. You can use this ID to send follow-up questions to the conversation session. + +[source,JSON] +---- +{"conversation_id":"q9tZYf_6WnFC"} +---- + +Note the conversation ID for further agentic interactions and API calls. + +=== Create a conversation session (legacy API endpoint) To create a conversation session, send a `POST` request body with the data source ID and search token string to the `/api/rest/2.0/ai/conversation/create` API endpoint. ==== Request parameters @@ -35,8 +157,9 @@ To create a conversation session, send a `POST` request body with the data sourc [options='header'] |===== |Form parameter|Description -|`metadata_identifier`|_String_. Required. Specify the GUID of the ThoughtSpot Worksheet or Model. The metadata object specified in the API request will be used as a data source for the conversation. -|`tokens` __Optional__ a|_String_. To set the context for the conversation, you can specify a set of keywords as token string. For example, `[sales],[item type],[state]`. +|`metadata_identifier`|_String_. Required. Specify the GUID of the data source objects such as ThoughtSpot Models. The metadata object specified in the API request will be used as a data source for the conversation. +|`tokens` + +__Optional__ a|_String_. To set the context for the conversation, you can specify a set of keywords as token string. For example, `[sales],[item type],[state]`. |===== ==== Example requests @@ -51,7 +174,7 @@ curl -X POST \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ "metadata_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", - "tokens": "[sales],[item type],[state]" + "tokens": "[sales],[item type],[Jackets]" }' ---- @@ -78,23 +201,514 @@ If the API request is successful, a conversation identifier is created. Note the {"conversation_identifier":"98f9b8b0-6224-4f9d-b61c-f41307bb6a89"} ---- -//// -===== Response codes +== Get relevant questions + +To discover follow-up or related questions that can be asked of a data model, ThoughtSpot provides the `/api/rest/2.0/ai/relevant-questions/` REST API endpoint. This API endpoint supports both agentic workflows and direct user interaction, and generates contextually relevant questions for a given data context and user query. + +The `/api/rest/2.0/ai/relevant-questions/` API is exposed as the `getRelevantQuestions` tool in ThoughtSpot's MCP server implementation. The MCP server can call this API directly to fetch relevant questions, which can then be used to generate reports or for further analysis and interactions. For more information, see xref:mcp-integration.adoc[MCP server integration]. + +You can also call this API directly from your REST client to fetch relevant questions by making a `POST` request. The API breaks the user-submitted query into a structured set of analytical sub-questions and returns these in the API response. + +=== Request parameters + [width="100%" cols="2,4"] [options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**500**| Internal error -|=== +|===== +|Parameter| Description +|`metadata_context` a| Required. Specify one of the following attributes to set the metadata context: + +* `data_source_identifiers` + +__Array of strings__. IDs of the data source object such as Models. +* `answer_identifiers` + +__Array of strings__. GUIDs of the Answer objects that you want to use as metadata. +* `conversation_identifier` + +__String__. ID of the conversation session. +* `liveboard_identifiers` + +__Array of strings__. GUIDs of the Liveboards that you want to use as metadata. + +| `query` |__String__. Required parameter. Specify the query string that needs to be decomposed into smaller, analytical sub-questions. +|`limit_relevant_questions` + +__Optional__ | __Integer__. Sets a limit on the number of sub-questions to return in the response. Default is 5. +|`bypass_cache` + +__Optional__| __Boolean__. When set to `true`, disables cache and forces fresh computation. +|`ai_context` + +__Optional__. a| Additional context to guide the response. Define the following attributes as needed: + +* `instructions` + +__Array of strings__. Custom user instructions to influence how the AI interprets and processes the query. +* `content` + +__Array of strings__. Additional input such as raw text or CSV-formatted data to enhance context and answer quality. +|===== + + +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/relevant-questions/' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' + --data-raw '{ + "metadata_context": { + "data_source_identifiers": [ + "cd252e5c-b552-49a8-821d-3eadaa049cca" + ] + }, + "query": "Net sales of Jackets in west coast", + "limit_relevant_questions": 3 +}' +---- + +=== Example response +If the request is successful, the API returns a set of questions related to the query and metadata context in the `relevant_questions` array. Each object in the `relevant_questions` array contains the following fields: + +* `query` + +A string containing the natural language (NL) sub-question. +* `data_source_identifier` + +GUID of the data source object that can be used as data context for the sub-question. +* `data_source_name` + +Name of the associated data source object. + +[source,JSON] +---- +{ + "relevant_questions": [ + { + "query": "What is the trend of sales by type over time?", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales by item", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + }, + { + "query": "Sales across regions", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca", + "data_source_name": "(Sample) Retail - Apparel" + } + ] +} +---- + +== Send a question to a conversation session +The following AI API endpoints allow you to send a follow-up query to an ongoing conversation: + +* xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[`POST /api/rest/2.0/ai/agent/converse/sse`] + +Allows a client to send queries to an ongoing conversation session with the AI agent (Spotter) and uses the Server-Sent Events (SSE) protocol to stream responses for a real-time conversational experience. It returns a streaming response (using SSE) with the AI agent's replies, allowing clients to receive incremental updates as the AI agent processes and generates its response. + +The `POST /api/rest/2.0/ai/agent/converse/sse` API call supports only the agent sessions created via `/api/rest/2.0/ai/agent/conversation/create` API call. + +* xref:spotter-apis.adoc#_send_a_question_to_generate_answer[`POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse`] + +Sends query to an ongoing conversation session and generates Answer. + +The `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API call supports only the conversation sessions created using the `POST /api/rest/2.0/ai/conversation/create` API call. + +__This is a legacy API endpoint and will be deprecated in an upcoming release version__. + +=== Send a question and generate streaming responses + +To send queries to an ongoing conversation session and receive streaming responses, ThoughtSpot provides the `/api/rest/2.0/ai/agent/converse/sse` API endpoint. This API endpoint uses the SSE protocol to deliver data incrementally as it becomes available, rather than waiting for the entire response to be generated before sending it to the client. This enables immediate feedback and a more interactive user experience for AI-generated responses. + +This API can be called directly, either through the Multi-Component Protocol (MCP) server or by integrating it into your own agentic workflow. In the MCP context, the `/api/rest/2.0/ai/agent/converse/sse` API is used as a "tool" for real-time, streaming of conversational interactions between agents and the ThoughtSpot backend. It enables AI agents to send user queries and receive incremental, streamed responses, which can be processed and displayed to the users. + +REST clients can also send a `POST` request with a conversation ID and query string to fetch streaming responses. + +==== Request parameters + +[width="100%" cols="2,4"] +[options='header'] +|===== +|Parameter| Description +|`conversation_identifier` |__String__. Specify the GUID of the conversation received from the xref:spotter-apis.adoc#_create_a_conversation_session_with_spotter_new_api_endpoint[create conversation API call]. +|`message`|_Array of Strings_. Specify the query text in natural language format. For example, `Sales data for Jackets`, `Top performing products in the west coast`. +|===== + +//// +|`settings` |__Optional__. Defines additional parameters for the conversation context. You can set any of the following attributes as needed: + +* `enable_contextual_change_analysis` + +__Boolean__. When enabled, Spotter analyzes how the context changes over time, that is comparing results from different queries. +* `enable_natural_language_answer_generation` + +__Boolean__. Allows sending natural language queries to the conversation session. +* `enable_reasoning` + +__Boolean__. Allows Spotter to use reasoning for deep analysis and precise responses. //// -[#ask_question] -=== Send questions to a conversation session +==== Example request + +[source,cURL] +---- +curl -X POST \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/agent/converse/sse' \ + -H 'Accept: application/json' \ + -H 'Content-Type: application/json' \ + -H 'Authorization: Bearer {AUTH_TOKEN}' \ + --data-raw '{ + "conversation_identifier": "h2I_pTGaRQof", + "messages": [ + "Net sales of Jackets" + ] +}' +---- + +==== API response + +If the API request is successful, the response includes a stream of events, each containing a partial or complete message from the AI agent, rather than a single JSON object. + +Each event is a simple text-based message in a specific format, `data: \n\n`; `\n\n` means that each message sent from the server to the client is prefixed with `data:` keyword, followed by the actual payload (``), and ends with two newline characters (`\n\n`). + +The API uses this format so that clients can reconstruct the AI-generated response as it streams in, chunk by chunk, and show the responses in real-time. In agentic workflows and the MCP server context, the API response is processed by the MCP host or AI agent. The agent listens to the SSE stream, parses each event, and assembles the full response for the user. + +===== Example response + +[source,] +---- +data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "I"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " understand"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you're"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " interested"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " I'll"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " retrieve"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " relevant"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " data"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "OJ0zMh4PVa-y", "type": "text-chunk", "group_id": "czoDDhNwwU7z", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "metadata": {"title": "Net sales of Jackets"}, "code": "nls_start"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "QH", "message": "Fetching Worksheet Data"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "TML_GEN", "message": "Translating your query with the Reasoning Engine"}] + +data: [{"type": "notification", "group_id": "o8dQ9SAWdtrL", "code": "ANSWER_GEN", "message": "Verifying results with the Trust Layer"}] + +data: [{"id": "r24X7D99SROD", "type": "answer", "group_id": "o8dQ9SAWdtrL", "metadata": {"sage_query": "[sales] [item type] = [item type].'jackets'", "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", "gen_no": 1, "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", "generation_number": 1, "warning_details": null, "ambiguous_phrases": null, "query_intent": null, "assumptions": "You want to see the total sales amount for jackets item type.", "tml_phrases": ["[sales]", "[item type] = [item type].'jackets'"], "cached": false, "sub_queries": null, "title": "Net sales of Jackets", "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca"}, "title": "Net sales of Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " have"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " been"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visual"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ized"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "."}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " analysis"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " specifically"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " filtered"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "\""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " and"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amount"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " associated"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " with"}] -To send a follow-up query to an ongoing conversation, send a `POST` request body with conversation ID and query text to the `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoint. +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " those"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " products"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "Summary"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " &"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " Insights"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ":"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "**\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " visualization"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " shows"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " total"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " net"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " all"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " transactions"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " in"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " apparel"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " dataset"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " The"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " calculation"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " uses"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " only"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " amounts"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " where"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " item"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " type"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " \""}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "J"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "ackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\"\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "-"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " This"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " information"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " is"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " useful"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " for"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " understanding"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " the"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " revenue"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " contribution"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " of"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jackets"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " within"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " your"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " mix"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ".\n\n"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "If"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " you'd"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " like"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " see"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " a"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " breakdown"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " by"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " region"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " state"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " time"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " period"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " or"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " compare"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " jacket"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " sales"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " to"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " other"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " product"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " types"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": ","}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " please"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " let"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " me"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": " know"}] + +data: [{"id": "BgY16KR8nVL1", "type": "text-chunk", "group_id": "_ARJXDKbFhHF", "metadata": {"format": "markdown"}, "content": "!"}] +---- + +The messages in the API response include the following parts: + +* `id` + +A unique identifier for the message group +* `type` +Type of the message. Valid types are: +** `ack` + +Confirms receipt of the request. For example, the type in the first message `data: [{"type": "ack", "node_id": "BRxCtJ-aGt8l"}]`, which indicates that the server has received the client's request and is acknowledging it. +** `text / text-chunk` + +Content chunks, optionally formatted. +** `answer` + +The final structured response with metadata and analytics +** `error` + +Indicates a failure. +** `notification` + +Notification messages. +* `group_id` + +Groups related chunks together. +* `metadata`: +Indicates content format, for example, markdown. +* `content` + +The actual text content sent incrementally. For example, `"I"`, `"understand"`, `"you're"`, `"interested"`, `"in"`, `"the"`, `"net"`, `"sales"`, and so on. + +The following example shows the response text contents for the `answer` message type. + +[source,JSON] +---- +[ + { + "id": "r24X7D99SROD", + "type": "answer", + "group_id": "o8dQ9SAWdtrL", + "metadata": { + "sage_query": "[sales] [item type] = [item type].'jackets'", + "session_id": "b321b404-cbf1-4905-9b0c-b93ad4eedf89", + "gen_no": 1, + "transaction_id": "6874259d-13b1-478c-83cb-b3ed52628850", + "generation_number": 1, + "warning_details": null, + "ambiguous_phrases": null, + "query_intent": null, + "assumptions": "You want to see the total sales amount for jackets item type.", + "tml_phrases": [ + "[sales]", + "[item type] = [item type].'jackets'" + ], + "cached": false, + "sub_queries": null, + "title": "Net sales of Jackets", + "worksheet_id": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "title": "Net sales of Jackets" + } +] +---- + +* The session ID and generation number serve as the context data for Answer. You can use this information to create a new conversation session using `/api/rest/2.0/ai/agent/conversation/create` or download the answer via `/api/rest/2.0/report/answer` operations. +* The tokens and TML phrases returned in the response can be used as inputs for the search data API call to get an Answer. + +=== Send a question to generate answer +To send a question to an ongoing conversation session or ask follow-up questions, send a `POST` request body with conversation ID and query text to the `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` API endpoint. ==== Request parameters @@ -102,9 +716,9 @@ To send a follow-up query to an ongoing conversation, send a `POST` request body [options='header'] |===== |Parameter|Type| Description -|`conversation_identifier`|Path parameter|__String__. Required. Specify the GUID of the conversation received from the xref:spotter-apis.adoc#_create_a_conversation_session[create conversation API call]. -|`metadata_identifier`|Form parameter|_String_. Required. Specify the GUID of the ThoughtSpot Worksheet or Model. The metadata object specified in the API request will be used as a data source for the follow-up conversation. -|`message`|Form parameter|_String_. Required. Specify the follow-up question as natural language query string. For example, `Sales data for Jackets`. +|`conversation_identifier`|Path parameter|__String__. Required. Specify the GUID of the conversation received from the xref:spotter-apis.adoc#_create_a_conversation_session_legacy_api_endpoint[create conversation API call]. +|`metadata_identifier`|Form parameter|_String_. Required. Specify the GUID of the data source object, for example, Model. The metadata object specified in the API request will be used as a data source for the follow-up conversation. +|`message`|Form parameter|_String_. Required. Specify a natural language query string. For example, `Sales data for Jackets`. |===== ==== Example request @@ -130,10 +744,10 @@ If the API request is successful, the following data is sent in the API response GUID of the Answer session. * `generation_number` + Number assigned to the Answer session. -* `message_type` +* `message_type` + Type of response received for the query. For example, `TSAnswer` (ThoughtSpot Answer). -* `visualization_type` -The data format of the generated Answer; for example, chart or table. When you download this Answer, the data will be exported in the format indicated by the `visualization_type`. +* `visualization_type` + +The data format of the generated Answer, for example, chart or table. When you download this Answer, the data will be exported in the format indicated by the `visualization_type`. * `tokens` + Tokens generated from the natural language search query string specified in the API request. You can use these tokens as input for `query_string` in your API request to `/api/rest/2.0/searchdata` and export the raw data of the query, or as input to `POST /api/rest/2.0/ai/conversation/create` to initiate a new conversation with a new context. @@ -155,10 +769,11 @@ Note the session ID and generation number. To export the Answer generated from t ] ---- -==== Ask follow-up questions +=== Ask follow-up questions -The API retains the context of previous queries when you send follow-up questions. To verify this, you can send another API request with a follow-up question to drill down the Answer data. +The API retains the context of previous queries when you send follow-up questions. To verify this, you can send another API request with a follow-up question to drill down into the data. +//// [source,cURL] ---- curl -X POST \ @@ -186,7 +801,7 @@ The API retrains the context of the initial question and returns a response: } ] ---- - +//// //// ===== Response codes [width="100%" cols="2,4"] @@ -200,6 +815,7 @@ The API retrains the context of the initial question and returns a response: |=== //// + == Generate a single Answer To generate an Answer from a natural language search query, send a `POST` request to the `/api/rest/2.0/ai/answer/create` API endpoint. In the request body, include the query and the data source ID. @@ -210,7 +826,7 @@ To generate an Answer from a natural language search query, send a `POST` reques |===== |Form parameter| Description |`query`|__String__. Required. Specify the string as a natural language query. For example, `Top performing products in the west coast`. -|`metadata_identifier`|_String_. Required. Specify the GUID of the ThoughtSpot Worksheet or Model. The metadata object specified in the API request will be used as a data source for the follow-up conversation. +|`metadata_identifier`|_String_. Required. Specify the GUID of the data source object, for example, Model. The metadata object specified in the API request will be used as a data source for the follow-up conversation. |===== ==== Example request @@ -238,7 +854,7 @@ GUID of the Answer session. Number assigned to the Answer session. * `message_type` Type of response received for the query. For example, `TSAnswer` (ThoughtSpot Answer). -* `visualization_type` +* `visualization_type` + The data format of the generated Answer; for example, chart or table. When you download this Answer, the data will be exported in the format indicated by the `visualization_type`. * `tokens` + Tokens generated from the natural language search query string specified in the API request. You can use these tokens as input for `query_string` in your API request to `/api/rest/2.0/searchdata` and export the raw data of the query, or as input to `POST /api/rest/2.0/ai/conversation/create` to initiate a new conversation with a new context. @@ -259,116 +875,95 @@ Note the session ID and generation number. To export the result generated from t }] ---- -//// -===== Response codes -[width="100%" cols="2,4"] -[options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**500**| Internal error -|=== -//// + [#process_results] == Process results generated from Spotter APIs -You can process the results generated from Spotter APIs in the following ways: +To generate an Answer using the data returned from the Spotter APIs, use the following options: -* xref:spotter-apis.adoc#exportSpotterData[Export the results as CSV or PNG] -* xref:spotter-apis.adoc#_use_tokens_generated_from_spotter_apis_as_raw_data[Use tokens generated from Spotter APIs as raw data] +* Download the generated Answer using the session ID and generation number via xref:data-report-v2-api.adoc#exportSpotterData[api/rest/2.0/report/answer] API endpoint. +* Use tokens generated from Spotter API requests as raw data in query strings and generate an Answer via xref:data-report-v2-api.adoc#_using_tokens_generated_from_spotter_apis_as_raw_data[/api/rest/2.0/searchdata] API endpoint. -[#exportSpotterData] -=== Export data generated from Spotter APIs -To export results generated from Spotter APIs, use the `/api/rest/2.0/report/answer` API endpoint. In the `POST` request body, include the session ID and generation number received from the xref:spotter-apis.adoc#ask_question[`POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse`] or xref:spotter-apis.adoc#_generate_a_single_answer[`POST /api/rest/2.0/ai/answer/create`] API call. +== Get data source suggestions +The `POST /api/rest/2.0/ai/data-source-suggestions` API provides relevant data source recommendations for a user-submitted natural language query. To use this API, you must have at least view access to the underlying metadata source referenced in the response. -==== Request parameters +[NOTE] +==== +The Get data source suggestions feature is not by default on all ThoughtSpot instances. To enable this API on your instance, contact ThoughtSpot Support. +==== + +=== Request parameters -[width="100%" cols="3,4"] +[width="100%" cols="2,4"] [options='header'] |===== -|Form parameter|Description -|`metadata_identifier` + -__Optional__|_String_. GUID of the object to export. In this case, the metadata object ID is not required, because you will be exporting the data generated from the conversation and not a saved Answer. -a|`session_identifier` [beta betaBackground]^Beta^ a|_String_. Required. GUID of the session identifying the conversation. The session ID is generated from a xref:spotter-apis.adoc#ask_question[POST call] to the `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse` endpoint, or when an API request is sent to the `/api/rest/2.0/ai/answer/create` endpoint to xref:_generate_a_single_answer[generate a single Answer]. -a|`generation_number` [beta betaBackground]^Beta^ + -__Optional__ a| _Integer_. Generation number identifying the conversation. The generation number is created in response to a xref:spotter-apis.adoc#ask_question[POST call] to the `/api/rest/2.0/ai/conversation/{conversation_identifier}/converse` endpoint, or when an API request is sent to the `/api/rest/2.0/ai/answer/create` endpoint to xref:_generate_a_single_answer[generate a single Answer]. - -|`file_format` + -__Optional__|__String__. Specifies the format of the output. You can export the Spotter-generated data as PNG or CSV file. By default, the API exports this data in PNG file format. +|Parameter| Description +|`query`|_String_. Required. Specify a natural language query string. For example, `Sales data for Jackets`. |===== -==== Request example +=== Example request -[source,cURL] +[source,JSON] ---- curl -X POST \ - --url 'https://{ThoughtSpot-Host}/api/rest/2.0/report/answer' \ + --url 'https://{ThoughtSpot-Host}/api/rest/2.0/ai/data-source-suggestions' \ + -H 'Accept: application/json' \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer {AUTH_TOKEN}' \ --data-raw '{ - "file_format": "CSV", - "session_identifier": "ee077665-08e1-4a9d-bfdf-7b2fe0ca5c79", - "generation_number": 2 + "query": "Sales data for Jackets" }' ----- -==== 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 -[width="100%" cols="2,4"] -[options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**401**| Forbidden request -|**500**| Internal error -|=== -//// -=== Use tokens generated from Spotter APIs as raw data - -For every natural language query and follow-up question, Spotter APIs return tokens in the API response. You can use these tokens as raw data to generate an Answer from ThoughtSpot via xref:data-report-v2-api.adoc#_search_data_api[`/api/rest/2.0/searchdata`] API. - -In the `POST` request body, include the session ID and generation number received from the xref:spotter-apis.adoc#ask_question[`POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse`] or xref:spotter-apis.adoc#_generate_a_single_answer[`POST /api/rest/2.0/ai/answer/create`] API call. +---- -==== Request example +=== API response +If the API request is successful, ThoughtSpot returns a ranked list of data sources, each annotated with relevant reasoning. -[source,cURL] +[source,JSON] ---- -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 -}' +{ + "data_sources": [ + { + "confidence": 0.97, + "details": { + "description": "", + "data_source_name": "(Sample) Retail - Apparel", + "data_source_identifier": "cd252e5c-b552-49a8-821d-3eadaa049cca" + }, + "reasoning": "Following similar NL queries were asked earlier on this worksheet - \"show sales of jackets quarter on quarter\", \"show sales of jackets last quarter in east\", \"jacket sales for february. (ignore previous context\"" + }, + { + "confidence": 0.62, + "details": { + "description": "", + "data_source_name": "Dunder Mifflin Sales", + "data_source_identifier": "0e4406c7-d978-4be7-abd7-c34e8f7da835" + }, + "reasoning": "" + }, + { + "confidence": 0.45, + "details": { + "description": "", + "data_source_name": "Copy of Dunder Mifflin Sales-SSD", + "data_source_identifier": "c8305843-d31f-468a-ab1b-2636f64c83e5" + }, + "reasoning": "Columns include 'Product', 'Category', 'Quantity', and 'Amount', which could support sales analysis for jackets if present, but no direct NLQ or answer matches." + } + ] +} ---- -==== API response +The returned results include metadata such as: -If the API request is successful, ThoughtSpot returns the Answer data for the query string sent in the API request. +* `confidence` + +A float indicating the Model's confidence in the relevance of each recommendation. +* `details` + +The data source ID, name, and description for each recommended data source. +* `reasoning` + +Reason provided by the LLM to explain why each data source was recommended. -//// -===== Response codes -[width="100%" cols="2,4"] -[options='header'] -|=== -|HTTP status code|Description -|**200**| Successful operation -|**400**| Invalid parameter -|**401**| Unauthorized access -|**401**| Forbidden request -|**500**| Internal error -|=== -//// \ No newline at end of file +== Additional resources + +* See REST API v2 Playground to verify the request and response workflows +* For information MCP tools, see xref:_mcp_server_integration[MCP server integration] \ No newline at end of file diff --git a/modules/ROOT/pages/spotter-in-custom-chatbot.adoc b/modules/ROOT/pages/spotter-in-custom-chatbot.adoc index ed60c250b..04c01d17e 100644 --- a/modules/ROOT/pages/spotter-in-custom-chatbot.adoc +++ b/modules/ROOT/pages/spotter-in-custom-chatbot.adoc @@ -38,6 +38,7 @@ To use the spotter conversational analytics, you start by creating a new convers [,js] ---- const conversation = new SpotterAgentEmbed({ + // ID of the data source object worksheetId: "", }); ---- diff --git a/modules/ROOT/pages/tml-api.adoc b/modules/ROOT/pages/tml-api.adoc index 64f9d702e..9a149647a 100644 --- a/modules/ROOT/pages/tml-api.adoc +++ b/modules/ROOT/pages/tml-api.adoc @@ -26,9 +26,9 @@ To import TML representation of objects into ThoughtSpot, use the `/tspublic/v1/ // // [NOTE] // ==== -// You can import single or multiple objects using the `tml/import` API. If you import only a Worksheet object, it may take some time for the Worksheet to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards. +// You can import single or multiple objects using the `tml/import` API. 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 Worksheet along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. +// 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. // ==== === Resource URL @@ -223,13 +223,13 @@ For example: |`formattype` + |__String__. The format in which to export the objects. Valid values are `JSON` and `YAML`. | `YAML` |`export_associated` + -__Optional__ |__Boolean__. Specifies if you would like to export the associated objects. To export the objects associated with the objects specified in `export_ids`, set the value to `true`. When set to `true`, the API exports any underlying worksheets, tables, or views for a given object. By default, the API does not export these underlying objects.| `false` +__Optional__ |__Boolean__. Specifies if you would like to export the associated objects. To export the objects associated with the objects specified in `export_ids`, set the value to `true`. When set to `true`, the API exports any underlying Models, Tables, or Views for a given object. By default, the API does not export these underlying objects.| `false` a|`export_fqn` + __Optional__ a|__Boolean__. When set to `true`, the API exports the FQNs of the referenced objects in the TML data. -// // For example, if you are exporting a Liveboard and its associated objects, the API returns the Liveboard TML data with the FQNs of the referenced Worksheet. + +// // 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 worksheets with the same name, the TML import for a Liveboard that uses one of these worksheets would fail unless the Liveboard TML includes the FQN of the referenced Worksheet. + +// // 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 Model. + // // // // 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. // diff --git a/modules/ROOT/pages/tml.adoc b/modules/ROOT/pages/tml.adoc index 8b7658b6e..39d1168a2 100644 --- a/modules/ROOT/pages/tml.adoc +++ b/modules/ROOT/pages/tml.adoc @@ -6,12 +6,11 @@ :page-pageid: tml :page-description: The TML API endpoints allow you to export and import TML files -ThoughtSpot developed its own scriptable approach for exporting, enhancing, and migrating Worksheets, views, tables, Liveboards, Monitor alerts, and Answers. -Use link:https://docs.thoughtspot.com/cloud/latest/tml[TML, window=_blank] (ThoughtSpot Modeling Language) to modify a ThoughtSpot object in a flat-file format. Users can model data and build out sophisticated dashboards in the test environment, before deploying to all users. +ThoughtSpot Modeling Language (TML) is a scriptable format developed by ThoughtSpot for exporting, modifying, and migrating metadata objects such as Models, Views, Tables, Liveboards, and Answers. TML files allow you to manage and version control these objects outside the ThoughtSpot UI, supporting workflows like bulk changes, migration between environments, and programmatic edits via REST API. Users can use link:https://docs.thoughtspot.com/cloud/latest/tml[TML] to model data and build analytics content in the test environment in a flat-file format, and then import and deploy it in their environments. == Structure of a TML file -To work with TML files for Worksheets, views, SQL views, tables, Answers, Liveboards, and Monitor alerts in ThoughtSpot, you can download these objects as a flat file in `.TML` format, modify, and subsequently upload the TMLs either to the same or a different cluster. +To work with TML files for Models, views, SQL views, tables, Answers, Liveboards, and Monitor alerts in ThoughtSpot, you can download these objects as a flat file in `.TML` format, modify, and subsequently upload the TMLs either to the same or a different cluster. The TML syntax varies per object type. However, all TMLs follow a general pattern that allows programmatic edits. ThoughtSpot offers a lot of flexibility within its set of xref:intro-thoughtspot-objects.adoc[data objects], and there is no particular hierarchy to TML files, but rather just some rules. @@ -26,7 +25,7 @@ See the following pages for the detailed syntax of TML files for each object typ * link:https://docs.thoughtspot.com/cloud/latest/tml-tables[TML for Tables, window=_blank] + * link:https://docs.thoughtspot.com/cloud/latest/tml-views[TML for Views, window=_blank] + * link:https://docs.thoughtspot.com/cloud/latest/tml-models[TML for Models, window=_blank] + -* link:https://docs.thoughtspot.com/cloud/10.11.0.cl/tml-worksheets[TML for Worksheets, window=_blank] + +//* link:https://docs.thoughtspot.com/cloud/10.11.0.cl/tml-worksheets[TML for Worksheets, window=_blank] + For TML modification tips and recommendations, see xref:modify-tml.adoc[TML modification]. @@ -72,9 +71,9 @@ You can also specify additional parameters to set the Org context and skip CDW v [NOTE] ==== -If you import only a Worksheet object, it may take some time for the Worksheet to become available in the ThoughtSpot system. You may need to wait for a few seconds to create answers and Liveboards. +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 Worksheet along with Liveboards, answers, and other dependent objects in a single API call, the imported objects will be immediately available for use. +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. ==== == Import TML objects asynchronously @@ -350,23 +349,24 @@ For Answer objects, the `identifier` is optional, and you can define parameters 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 worksheets, tables, or views for a given object. By default, the API does not export these underlying objects. +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, Worksheet, Answer, or Liveboard TML. +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 Worksheet. +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 worksheets with the same name, the TML import for a Liveboard that uses one of these worksheets would fail unless the Liveboard TML includes the FQN of the referenced Worksheet. +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. By default, the API request uses v1 schema for Worksheets. If you are using Models, set `export_schema_version` to v2. link:https://docs.thoughtspot.com/cloud/latest/models[Models, window=_blank] are supported as new datasets from 9.10.0.cl onwards. +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: diff --git a/modules/ROOT/pages/vercel-int.adoc b/modules/ROOT/pages/vercel-int.adoc index 1eb3ddaab..8efe5226e 100644 --- a/modules/ROOT/pages/vercel-int.adoc +++ b/modules/ROOT/pages/vercel-int.adoc @@ -79,18 +79,18 @@ To continue with integration, check if your Vercel project is integrated with Po * If Postgres is integrated, ThoughtSpot will automatically create a connection to the existing Postgres databases in your project. + -With Postgres, you can either use an existing Worksheet available on your instance or create a Model instantaneously. +With Postgres, you can either use an existing Model available on your instance or create a Model instantaneously. + Models in ThoughtSpot refer to logical representation of data and are used to model complex datasets. For more information, see link:https://docs.thoughtspot.com/cloud/latest/models[ThoughtSpot Product Documentation, window=_blank]. + -** To analyze data from an existing Worksheet, click **Connect to existing Worksheets**. -** To create a connection and Worksheet, click **Create a new connection**. +** To analyze data from an existing Model, click **Connect to existing Worksheets**. +** To create a connection and Model, click **Create a new connection**. .. Add Tables and Columns and click **Update connection**. + ThoughtSpot automatically detects joins between the selected Tables. .. Select the association of tables you would like to run your analysis on, and then click **Continue**. + -ThoughtSpot will create a Worksheet with the data set you selected. +ThoughtSpot will create a Model with the data set you selected. .. Click **Continue**. diff --git a/modules/ROOT/pages/version_control.adoc b/modules/ROOT/pages/version_control.adoc index 81e7a9c56..12963a93f 100644 --- a/modules/ROOT/pages/version_control.adoc +++ b/modules/ROOT/pages/version_control.adoc @@ -9,7 +9,7 @@ //// When embedding or deploying a third-party application in their environments, most organizations use defined practices at various stages of their SDLC process. Developers typically use a version control system and CI-CD pipeline to push their code from development to testing and production environments. Similarly, when deploying ThoughtSpot, you may want to publish your ThoughtSpot content from a development environment to a staging or production cluster. -ThoughtSpot objects such as Worksheets, Liveboards, and Answers are stored as link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] content. Users can download these TML files, edit these files locally, and import the updated content into ThoughtSpot. TML files are also useful when migrating content from one ThoughtSpot instance to another. +ThoughtSpot objects such as Models, Liveboards, and Answers are stored as link:https://docs.thoughtspot.com/cloud/latest/tml[ThoughtSpot Modeling Language (TML), window=_blank] content. Users can download these TML files, edit these files locally, and import the updated content into ThoughtSpot. TML files are also useful when migrating content from one ThoughtSpot instance to another. //// With the Git integration feature, ThoughtSpot provides the ability to connect ThoughtSpot Orgs to a Git repository, push link:https://docs.thoughtspot.com/cloud/latest/tml[TML files, window=_blank] on demand to Git branches, and deploy commits from branches back into ThoughtSpot. @@ -39,7 +39,7 @@ ThoughtSpot provides xref:git-rest-api-guide.adoc[REST API] for exporting TML fr The following figure illustrates a simple Git integration workflow with ThoughtSpot `Dev` and `Prod` environments. [.widthAuto] -image::./images/git-integration-workflow.svg[Git integration workflow] +image::./images/git-integration-workflow.png[Git integration workflow] [NOTE] ==== diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 97b6bd285..32350c5d8 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -8,6 +8,61 @@ This page lists new features, enhancements, and deprecated functionality in ThoughtSpot Embedded instances. +== Version 10.13.0.cl + +=== Spotter AI APIs +ThoughtSpot introduces the following new xref:spotter-apis.adoc[Spotter AI APIs] [beta betaBackground]^Beta^, to provide contextual and agentic capabilities for integration with external clients and custom AI applications: + +* `/api/rest/2.0/ai/agent/conversation/create` +* `/api/rest/2.0/ai/data-source-suggestions` +* `/api/rest/2.0/ai/relevant-questions/` +* `/api/rest/2.0/ai/agent/converse/sse` + +These APIs are designed to build context with each interaction, orchestrate reasoning, and expose tools and skills for natural language analytics. + +The new APIs, such as `/api/rest/2.0/ai/relevant-questions/`, `/api/rest/2.0/ai/agent/converse/sse` and `/api/rest/2.0/ai/data-source-suggestions`, can be accessed both directly and via xref:mcp-integration.adoc[ThoughtSpot's MCP (Model Context Protocol) server]. + +For more information, see xref:spotter-apis.adoc[Spotter AI APIs]. + +//// +With the introduction of these APIs, the following legacy API endpoints will be deprecated: + +* `POST /api/rest/2.0/ai/conversation/create` +* `POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse` +* `POST /api/rest/2.0/ai/analytical-questions` + +The above-listed AI endpoints will be available in the Playground until further notice. However, we recommend using the new APIs for better context management, extensibility, and integration options. +//// + +//// +=== Support for runtime overrides in Spotter embed +The Visual Embed SDK now supports runtime filters and Parameters. For more information, see xref:runtime-filters.adoc#_runtime_filters_in_visual_embed_sdk[Runtime filters] and xref:runtime-parameters.adoc#_apply_parameter_overrides_in_visual_embed_sdk[Runtime Parameters]. +//// +=== Full application embed experience + +* The new experience with a sliding navigation panel and modular home page is now available as an Early Access feature for ThoughtSpot embedded application users. ++ +The new experience introduces a sliding navigation panel with a persona-based app selector and a modular home page with customizable components. This feature is turned off by default on ThoughtSpot. If this feature is enabled on your instance, you can enable it in full application embed using the `discoveryExperience` SDK property. ++ +For more information, see xref:full-app-customize.adoc#_new_modular_home_page_and_navigation_with_sliding_panel[New navigation and home page experience]. + +* List pages, such as Answers and Liveboards, now include enhanced sorting and filtering capabilities. These pages also allow users to organize, find, and personalize content. Developers can customize the visibility of columns in their embeds by configuring the xref:AppViewConfig.adoc#_hiddenlistcolumns[`hiddenListColumns`] property in the SDK. ++ +For more information, see xref:full-app-customize.adoc#_hide_columns_on_list_pages_new_experience[Hide columns on List pages]. + +=== Worksheet deprecation and removal + +Worksheets are replaced with Models, and all application workflows will require you to use Models. If you are importing worksheet TMLs, the import operation may fail with an error, requiring users to convert Worksheets to Models. Please update your CI/CD and Git workflows to use Model TMLs instead of Worksheets. + +For more information, see xref:deprecated-features.adoc#_worksheet_deprecation_and_removal[Worksheet deprecation]. + +=== Visual Embed SDK + +For information about the new features and enhancements introduced in Visual Embed SDK version 1.42.0, see xref:api-changelog.adoc[Visual Embed changelog]. + +=== REST API +For information about REST API v2 enhancements, see xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. + == Version 10.12.0.cl === Liveboard grouping and styling [beta betaBackground]^Beta^ @@ -38,11 +93,6 @@ Spotter coaching:: Your application users can now coach Spotter based on an ongoing conversation. The *Add to coaching* feature is turned off by default on ThoughtSpot instances. To enable this feature, contact your administrator. -//// -TBA for 10.13 -Runtime filters and Parameters:: -You can now set runtime filters and runtime Parameters for Spotter embed. -//// Spotter Agent embedding:: To embed Spotter Agent in a React app, the SDK provides a React component and the `useSpotterAgent` custom React hook. For more information, see xref:embed-ts-react-app.adoc#_embed_spotter_agent_in_your_own_app[Embed Spotter Agent in your React app]. diff --git a/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc b/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc index 275bb67ad..8385d86b4 100644 --- a/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc +++ b/modules/tutorials/pages/spotter/spotter-in-custom-chatbot.adoc @@ -62,6 +62,7 @@ To use the Spotter conversational analytics, let's start by creating a new conve [source,javascript] ---- const conversation = new SpotterAgentEmbed({ + // Specify the GUID of the data source object worksheetId: "", }); ---- diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc index 97c5ba19c..145401076 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-03.adoc @@ -28,7 +28,7 @@ Security when using ThoughtSpot and ThoughtSpot Embedded can be in the following |Embed / web security are the security settings that allow you to embed ThoughtSpot into your application|ThoughtSpot Embedded |Authentication determines how you will authenticate the user with ThoughtSpot. Both the authentication supported by ThoughtSpot and ThoughtSpot Embedded have to be considered.| ThoughtSpot Embedded + ThoughtSpot Analytics application -|Content security is managed by ThoughtSpot to determine what content a user has access to, such as tables, worksheets, and liveboards. Data security can be controlled separately | ThoughtSpot Analytics application. +|Content security is managed by ThoughtSpot to determine what content a user has access to, such as Tables, Models (formerly Worksheets), and Liveboards. Data security can be controlled separately | ThoughtSpot Analytics application. For more information, see xref:_embed_web_security[the following sections]. |System privileges / roles define what a user can do inside ThoughtSpot, such as downloading data or using SpotIQ.|ThoughtSpot Analytics application |Data security restricts the columns or rows of data from the source data. Data security is managed via row-level security settings or column sharing in ThoughtSpot. It can also be controlled using pass-through security to the Cloud data warehouse.| ThoughtSpot Analytics application diff --git a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc index c88dfafe0..deaafb094 100644 --- a/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc +++ b/modules/tutorials/pages/tse-fundamentals/tse-fundamentals-lesson-06.adoc @@ -73,7 +73,7 @@ image:images/tutorials/tse-fundamentals/lesson-06-empty-sage-embed.png[empty sag Let's review the SageEmbed-specific settings and configure the embed. -* The `Select data source` dropdown is similar to what we used for the Search embed. It will display any worksheets enabled for natural language search. Select one from the dropdown to update the code with the data source's GUID. +* The `Select data source` dropdown is similar to what we used for the Search embed. It will display any Models enabled for natural language search. Select one from the dropdown to update the code with the data source's GUID. Unlike the Search embed, you can only have one data source for natural language search, and a data source is always required for natural language search, though it can be user-provided. @@ -83,7 +83,7 @@ Now, set some additional options: * **Hide Sage Answer header**: Hides the "AI answer" header in the results. * **Add search query**: Predefines a text query to run automatically, similar to the search embed. -For this exercise, select the options **Disable changing worksheet**, **Hide Sage Answer header**, and **Add search query**. Enter a search query, then press **Run**. You should see a result like this: +For this exercise, select the options **Disable changing model**, **Hide Sage Answer header**, and **Add search query**. Enter a search query, then press **Run**. You should see a result like this: [.widthAuto] [.bordered] diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index cbc51d78f..e5f20ab18 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -35,7 +35,7 @@ module.exports = { }, VERSION_DROPDOWN: [ { - label: '10.12.0.cl', + label: '10.13.0.cl', link: ' ', subLabel: 'Cloud (Latest)', }, diff --git a/static/doc-images/images/claudeDesktop.png b/static/doc-images/images/claudeDesktop.png new file mode 100644 index 000000000..ecef7ffa6 Binary files /dev/null and b/static/doc-images/images/claudeDesktop.png differ diff --git a/static/doc-images/images/create-lb-claude.png b/static/doc-images/images/create-lb-claude.png new file mode 100644 index 000000000..877325e1f Binary files /dev/null and b/static/doc-images/images/create-lb-claude.png differ diff --git a/static/doc-images/images/datasource-selection.png b/static/doc-images/images/datasource-selection.png new file mode 100644 index 000000000..3a7d8ef3f Binary files /dev/null and b/static/doc-images/images/datasource-selection.png differ diff --git a/static/doc-images/images/git-integration-workflow.png b/static/doc-images/images/git-integration-workflow.png index bac5f9313..4405e6942 100644 Binary files a/static/doc-images/images/git-integration-workflow.png and b/static/doc-images/images/git-integration-workflow.png differ diff --git a/static/doc-images/images/guid-mapping.png b/static/doc-images/images/guid-mapping.png index 0be05ea34..7fff11158 100644 Binary files a/static/doc-images/images/guid-mapping.png and b/static/doc-images/images/guid-mapping.png differ diff --git a/static/doc-images/images/mcp-integration.png b/static/doc-images/images/mcp-integration.png new file mode 100644 index 000000000..2d4b1e079 Binary files /dev/null and b/static/doc-images/images/mcp-integration.png differ diff --git a/static/doc-images/images/mcp-server-int-workflow.png b/static/doc-images/images/mcp-server-int-workflow.png new file mode 100644 index 000000000..2dacbe322 Binary files /dev/null and b/static/doc-images/images/mcp-server-int-workflow.png differ diff --git a/static/doc-images/images/mcp-tools-claude.png b/static/doc-images/images/mcp-tools-claude.png new file mode 100644 index 000000000..d0db1f342 Binary files /dev/null and b/static/doc-images/images/mcp-tools-claude.png differ diff --git a/static/doc-images/images/new-nav3.png b/static/doc-images/images/new-nav3.png new file mode 100644 index 000000000..6b314561d Binary files /dev/null and b/static/doc-images/images/new-nav3.png differ diff --git a/static/doc-images/images/object_model_hierarchy.png b/static/doc-images/images/object_model_hierarchy.png index 4675401cc..fa29c4913 100644 Binary files a/static/doc-images/images/object_model_hierarchy.png and b/static/doc-images/images/object_model_hierarchy.png differ diff --git a/static/doc-images/images/query-response-claude.png b/static/doc-images/images/query-response-claude.png new file mode 100644 index 000000000..384b5804f Binary files /dev/null and b/static/doc-images/images/query-response-claude.png differ diff --git a/static/doc-images/images/query-response-claude2.png b/static/doc-images/images/query-response-claude2.png new file mode 100644 index 000000000..0bb5e1b9b Binary files /dev/null and b/static/doc-images/images/query-response-claude2.png differ