From e7130d70e0914ae5006b0e50ebee527c69708839 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 26 Oct 2026 21:12:51 +0530 Subject: [PATCH 01/48] spottercode org awareness --- .../ROOT/pages/spottercode-prompt-guide.adoc | 29 +++++++ modules/ROOT/pages/spottercode.adoc | 78 ++++++++++++++++--- 2 files changed, 97 insertions(+), 10 deletions(-) diff --git a/modules/ROOT/pages/spottercode-prompt-guide.adoc b/modules/ROOT/pages/spottercode-prompt-guide.adoc index 807bbf8f6..5209e75e1 100644 --- a/modules/ROOT/pages/spottercode-prompt-guide.adoc +++ b/modules/ROOT/pages/spottercode-prompt-guide.adoc @@ -89,6 +89,35 @@ How do I create a new user with admin privileges via REST API? Provide the endpo |How do I see new actions in my app? | How do I get a list of custom actions added in my embed via REST API? |===== +=== Working with multiple Orgs +If your ThoughtSpot instance has Orgs enabled and you are connected via OAuth or SAML authentication, you can use SpotterCode to discover and switch between Orgs without leaving your IDE. + +[width="100%" cols="4,4" role="copy-cell-table prompt-guidance-table"] +[options='header'] +|===== +|Vague prompt|Clear prompt + +|What org am I in? +|Which Org is currently active in my SpotterCode session? + +|Show me my orgs +|List all Orgs I have access to on my ThoughtSpot instance, and indicate which one is currently active. + +|Switch org +|Switch my active Org to the one named "Sales EMEA" and confirm the switch was successful. + +|I can't find my Liveboard +a|I can't find a Liveboard called "Revenue Overview." List all Orgs I have access to — it may be in a different Org. Then switch to each Org and check whether the Liveboard exists there. + +|Use a different org for my API calls +|Switch to the Org with ID `123456` and then retrieve a list of all Liveboards in that Org via the REST API. +|===== + +[NOTE] +==== +The active Org selection is shared across all your active sessions. If you switch Orgs in one session, the change applies to all other concurrent sessions for your user account. +==== + == Prompting in the Visual Embed Playground The Visual Embed Playground includes a built-in SpotterCode panel with quick-starter prompts for each embed component. You can use these as starting points and refine them with follow-up prompts. diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index 0b29f2e5e..c03c76955 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -74,7 +74,11 @@ a| `\https://spottercode.thoughtspot.app/mcp` + The full-capability SpotterCode endpoint. Requires authentication with a ThoughtSpot instance. You can use this MCP endpoint to perform authenticated user operations on your ThoughtSpot instance via the public REST APIs. a| `get-rest-api-reference` + `get-developer-docs-reference` + -`execute-thoughtspot-code` +`execute-thoughtspot-code` + +`list_orgs` + +`switch_org` + +__The `list_orgs` and `switch_org` are available only on ThoughtSpot instances with Orgs enabled. These tools require OAuth or SAML authentication and are not available when connecting via the Bearer token endpoint (`/bearer/mcp`)__ a| *Documentation endpoint* + (`/mcp/docs`) @@ -96,18 +100,38 @@ Provides access to documentation on embedding, UI customization, deployment, sec * `execute-thoughtspot-code` + Executes authenticated ThoughtSpot API workflows directly from your IDE agent. This skill allows your IDE agent to perform common operations that can be done via public REST APIs. +* `list_orgs` + +Lists all Orgs the authenticated user can access on the connected ThoughtSpot instance. Each Org entry includes its `id`, `name`, and `description`. The currently active Org is indicated by `is_active: true`. ++ +This tool is available only on ThoughtSpot instances with Orgs enabled and requires OAuth or SAML authentication. It is not available when connecting via the Bearer token endpoint (`/bearer/mcp`). + +* `switch_org` + +Switches the active Org for the current authenticated session. All subsequent tool calls operate in the context of the selected Org. + ++ +Accepts a single input, `org_id`, which is the ID of the Org to switch to (returned by `list_orgs`). Returns `success: true` if the switch succeeded. If the switch fails, the active Org is unchanged. ++ +[IMPORTANT] +==== +The active Org selection is stored per user, not per conversation. If two concurrent AI sessions switch to different Orgs, the last operation takes effect for both sessions. The selection persists across reconnects and resets only on re-authentication or after a period of inactivity. +==== ++ +This tool is available only on ThoughtSpot instances with Orgs enabled and requires OAuth or SAML authentication. It is not available when connecting via the Bearer token endpoint (`/bearer/mcp`). + === Choosing the right endpoint -Use the following guidance to decide which endpoint to configure in your IDE: +Use the following guidance to decide which endpoint to configure in your IDE. -* *Use `/mcp` (authenticated)* if: -** You want the AI agent to execute ThoughtSpot API workflows from your IDE, for example, to generate a trusted authentication secret key, configure your application domain in CORS/CSP allowlists, or retrieve Liveboard and Answer object IDs from your instance. -** You want your IDE to use the full set of SpotterCode skills, including `run-ts-workflow`. -** You are building or configuring a ThoughtSpot embedded application and want end-to-end setup assistance without leaving the IDE. +Use `/mcp` (authenticated) if:: -* *Use `/mcp/docs` (unauthenticated)* if: -** You only need the AI agent to look up documentation, REST API reference material, and code samples. -** You are working in an environment where connecting to a ThoughtSpot instance is not appropriate. For example, a shared CI environment, a read-only developer workstation, or a demonstration setup. -** You do not have a ThoughtSpot Embedded subscription or instance credentials available. +* You want the AI agent to execute ThoughtSpot API workflows from your IDE, for example, to generate a trusted authentication secret key, configure your application domain in CORS/CSP allowlists, or retrieve Liveboard and Answer object IDs from your instance. +* You want your IDE to use the full set of SpotterCode skills, including `execute-thoughtspot-code`. +* You are building or configuring a ThoughtSpot embedded application and want end-to-end setup assistance without leaving the IDE. +* Your ThoughtSpot instance uses Orgs and you want the AI agent to list or switch Orgs during a session. Use the `list_orgs` and `switch_org` tools with this endpoint. + +Use `/mcp/docs` (unauthenticated) if:: +* You only need the AI agent to look up documentation, REST API reference material, and code samples. +* You are working in an environment where connecting to a ThoughtSpot instance is not appropriate. For example, a shared CI environment, a read-only developer workstation, or a demonstration setup. +* You do not have a ThoughtSpot Embedded subscription or instance credentials available. +* You do not need org-switching capabilities. The `/mcp/docs` unauthenticated endpoint does not support `list_orgs` or `switch_org`. [NOTE] ==== @@ -157,6 +181,40 @@ SpotterCode performs operations as the authenticated user. Grant SpotterCode acc * SpotterCode does not influence how the Spotter feature in your ThoughtSpot embed infers semantic modeling. SpotterCode is not intended for querying data models or interpreting definitions such as measures and attributes in your metadata objects. * The behavior of the IDE agent, including tool selection and reasoning, is not controlled by SpotterCode. +[#_multi_org_support] +== Multi-Org support + +If your ThoughtSpot instance has Orgs enabled, SpotterCode can list and switch between Orgs during a session. By default, SpotterCode operates in the Org that was active when you authenticated. To work with resources in a different Org, use the `list_orgs` and `switch_org` tools. + +=== How it works +When you switch to a different Org using `switch_org`, SpotterCode mints a new per-Org session token scoped to that Org and stores it for your user account. Subsequent tool calls use this token and operate within the selected Org. The selection persists across reconnects until you re-authenticate or the session expires after a period of inactivity. + +=== Example workflow + +To check which Org you are in and switch to a different Org, use the following prompts in your IDE agent: + +. Ask the agent to list your available Orgs: ++ +---- +List all Orgs I have access to on my ThoughtSpot instance. +---- ++ +The agent calls `list_orgs` and returns a list of Orgs. The currently active Org is marked with `is_active: true`. + +. Ask the agent to switch to the Org you want to work in: ++ +---- +Switch to the Sales EMEA Org. +---- ++ +The agent calls `switch_org` with the corresponding `org_id`. After a successful switch, all subsequent API calls operate within that Org. + +=== Prerequisites and limitations + +* Orgs must be enabled on your ThoughtSpot instance. +* You must authenticate using OAuth or SAML. Multi-Org tools are not available when connecting via the Bearer token endpoint (`/bearer/mcp`). +* The active Org selection is stored per user, not per conversation. If you have multiple active AI sessions, the last `switch_org` call takes effect across all sessions. Plan org switches accordingly when running concurrent sessions. + == Next steps ++++ From 9e3afdee5d945b29d59ecd049e96fd54d20dcfd8 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 26 Oct 2026 21:32:59 +0530 Subject: [PATCH 02/48] minor edits --- .../ROOT/pages/spottercode-prompt-guide.adoc | 1 + modules/ROOT/pages/spottercode.adoc | 18 +++++++----------- 2 files changed, 8 insertions(+), 11 deletions(-) diff --git a/modules/ROOT/pages/spottercode-prompt-guide.adoc b/modules/ROOT/pages/spottercode-prompt-guide.adoc index 5209e75e1..b5f34022a 100644 --- a/modules/ROOT/pages/spottercode-prompt-guide.adoc +++ b/modules/ROOT/pages/spottercode-prompt-guide.adoc @@ -89,6 +89,7 @@ How do I create a new user with admin privileges via REST API? Provide the endpo |How do I see new actions in my app? | How do I get a list of custom actions added in my embed via REST API? |===== + === Working with multiple Orgs If your ThoughtSpot instance has Orgs enabled and you are connected via OAuth or SAML authentication, you can use SpotterCode to discover and switch between Orgs without leaving your IDE. diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index c03c76955..b280b6490 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -175,12 +175,6 @@ Because code executes as the authenticated user, write operations, such as creat SpotterCode performs operations as the authenticated user. Grant SpotterCode access only to accounts with the minimum permissions required for the intended use case. ==== -== Limitations -* Responses from SpotterCode are determined by the features and parameters currently supported in the Visual Embed SDK, REST API, and official ThoughtSpot developer documentation. SpotterCode cannot generate code or solutions that rely on unsupported or undocumented features. -* SpotterCode can generate code samples for the most common use cases. Scenarios that require advanced customization or highly specialized workflows may require manual intervention or additional coding beyond what SpotterCode provides. -* SpotterCode does not influence how the Spotter feature in your ThoughtSpot embed infers semantic modeling. SpotterCode is not intended for querying data models or interpreting definitions such as measures and attributes in your metadata objects. -* The behavior of the IDE agent, including tool selection and reasoning, is not controlled by SpotterCode. - [#_multi_org_support] == Multi-Org support @@ -188,6 +182,7 @@ If your ThoughtSpot instance has Orgs enabled, SpotterCode can list and switch b === How it works When you switch to a different Org using `switch_org`, SpotterCode mints a new per-Org session token scoped to that Org and stores it for your user account. Subsequent tool calls use this token and operate within the selected Org. The selection persists across reconnects until you re-authenticate or the session expires after a period of inactivity. +The active Org selection is stored per user, not per conversation. If you have multiple active AI sessions, the last `switch_org` call takes effect across all sessions. Plan org switches accordingly when running concurrent sessions. === Example workflow @@ -208,12 +203,13 @@ Switch to the Sales EMEA Org. ---- + The agent calls `switch_org` with the corresponding `org_id`. After a successful switch, all subsequent API calls operate within that Org. + +== Limitations +* Responses from SpotterCode are determined by the features and parameters currently supported in the Visual Embed SDK, REST API, and official ThoughtSpot developer documentation. SpotterCode cannot generate code or solutions that rely on unsupported or undocumented features. +* SpotterCode can generate code samples for the most common use cases. Scenarios that require advanced customization or highly specialized workflows may require manual intervention or additional coding beyond what SpotterCode provides. +* SpotterCode does not influence how the Spotter feature in your ThoughtSpot embed infers semantic modeling. SpotterCode is not intended for querying data models or interpreting definitions such as measures and attributes in your metadata objects. +* The behavior of the IDE agent, including tool selection and reasoning, is not controlled by SpotterCode. -=== Prerequisites and limitations - -* Orgs must be enabled on your ThoughtSpot instance. -* You must authenticate using OAuth or SAML. Multi-Org tools are not available when connecting via the Bearer token endpoint (`/bearer/mcp`). -* The active Org selection is stored per user, not per conversation. If you have multiple active AI sessions, the last `switch_org` call takes effect across all sessions. Plan org switches accordingly when running concurrent sessions. == Next steps From 1c34768e0f7ed07249fe6d116cca14d297a14362 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 26 Oct 2026 21:34:59 +0530 Subject: [PATCH 03/48] formatting fixes --- modules/ROOT/pages/spottercode.adoc | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index b280b6490..17174c32b 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -190,20 +190,18 @@ To check which Org you are in and switch to a different Org, use the following p . Ask the agent to list your available Orgs: + ----- -List all Orgs I have access to on my ThoughtSpot instance. ----- +`List all Orgs I have access to on my ThoughtSpot instance.` + + The agent calls `list_orgs` and returns a list of Orgs. The currently active Org is marked with `is_active: true`. . Ask the agent to switch to the Org you want to work in: + ----- -Switch to the Sales EMEA Org. ----- +`Switch to the Sales EMEA Org.` + + The agent calls `switch_org` with the corresponding `org_id`. After a successful switch, all subsequent API calls operate within that Org. - + == Limitations * Responses from SpotterCode are determined by the features and parameters currently supported in the Visual Embed SDK, REST API, and official ThoughtSpot developer documentation. SpotterCode cannot generate code or solutions that rely on unsupported or undocumented features. * SpotterCode can generate code samples for the most common use cases. Scenarios that require advanced customization or highly specialized workflows may require manual intervention or additional coding beyond what SpotterCode provides. From 9916167add9af50fbfee3c9fcffc35fe38857404 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 28 Oct 2026 19:31:04 +0530 Subject: [PATCH 04/48] what's new and other edits --- modules/ROOT/pages/spottercode-integration.adoc | 2 ++ modules/ROOT/pages/spottercode-prompt-guide.adoc | 3 +++ modules/ROOT/pages/spottercode.adoc | 3 --- modules/ROOT/pages/whats-new.adoc | 7 +++++++ 4 files changed, 12 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/spottercode-integration.adoc b/modules/ROOT/pages/spottercode-integration.adoc index 5a5e4ac08..49d178bc0 100644 --- a/modules/ROOT/pages/spottercode-integration.adoc +++ b/modules/ROOT/pages/spottercode-integration.adoc @@ -44,6 +44,8 @@ This is the primary authentication flow for developers connecting an MCP client The session token is stored in a secure backend store. Contact your ThoughtSpot administrator if you encounter repeated authentication prompts. ==== +If the ThoughtSpot instance of the user has multiple Orgs, SpotterCode allows listing the Orgs they can access and switching the active Org during a session without reauthenticating. For more information, see xref:spottercode.adoc#_multi_org_support[Multi-Org support]. + === Bearer token authentication For programmatic or CI/CD scenarios where an MCP client cannot perform an interactive login, SpotterCode accepts a bearer token directly using a dedicated MCP Server endpoint: `https://spottercode.thoughtspot.app/bearer/mcp`. diff --git a/modules/ROOT/pages/spottercode-prompt-guide.adoc b/modules/ROOT/pages/spottercode-prompt-guide.adoc index b5f34022a..4ddc42e39 100644 --- a/modules/ROOT/pages/spottercode-prompt-guide.adoc +++ b/modules/ROOT/pages/spottercode-prompt-guide.adoc @@ -90,6 +90,7 @@ How do I create a new user with admin privileges via REST API? Provide the endpo |===== +//// === Working with multiple Orgs If your ThoughtSpot instance has Orgs enabled and you are connected via OAuth or SAML authentication, you can use SpotterCode to discover and switch between Orgs without leaving your IDE. @@ -118,6 +119,8 @@ a|I can't find a Liveboard called "Revenue Overview." List all Orgs I have acces ==== The active Org selection is shared across all your active sessions. If you switch Orgs in one session, the change applies to all other concurrent sessions for your user account. ==== +//// + == Prompting in the Visual Embed Playground diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index 17174c32b..f432c1ffa 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -184,8 +184,6 @@ If your ThoughtSpot instance has Orgs enabled, SpotterCode can list and switch b When you switch to a different Org using `switch_org`, SpotterCode mints a new per-Org session token scoped to that Org and stores it for your user account. Subsequent tool calls use this token and operate within the selected Org. The selection persists across reconnects until you re-authenticate or the session expires after a period of inactivity. The active Org selection is stored per user, not per conversation. If you have multiple active AI sessions, the last `switch_org` call takes effect across all sessions. Plan org switches accordingly when running concurrent sessions. -=== Example workflow - To check which Org you are in and switch to a different Org, use the following prompts in your IDE agent: . Ask the agent to list your available Orgs: @@ -208,7 +206,6 @@ The agent calls `switch_org` with the corresponding `org_id`. After a successful * SpotterCode does not influence how the Spotter feature in your ThoughtSpot embed infers semantic modeling. SpotterCode is not intended for querying data models or interpreting definitions such as measures and attributes in your metadata objects. * The behavior of the IDE agent, including tool selection and reasoning, is not controlled by SpotterCode. - == Next steps ++++ diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 105506f12..03e97aac1 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -37,6 +37,13 @@ a| a| +[discrete] +==== SpotterCode Org awareness +SpotterCode now supports new `list_orgs` and `switch_org` tools to allow users to get a list of the Orgs they can access and switch to without leaving the IDE. +For more information, see xref:spottercode.adoc#_multi_org_support[Multi-Org support in SpotterCode]. + +--- + [discrete] ==== Spotter Analyst From b788c5fd8fd97c662cc7c0de75804fe2760ad3b2 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 10:57:01 +0530 Subject: [PATCH 05/48] SCAL-280404 --- modules/ROOT/pages/api-changelog.adoc | 18 + modules/ROOT/pages/common/nav-embedding.adoc | 1 + .../pages/common/nav-in-product-help.adoc | 1 + .../pages/customize-liveboard-filters.adoc | 6 +- modules/ROOT/pages/embed-pinboard.adoc | 2 + modules/ROOT/pages/filters_overview.adoc | 7 +- modules/ROOT/pages/liveboard-overrides.adoc | 596 ++++++++++++++++++ modules/ROOT/pages/runtime-filters.adoc | 10 + modules/ROOT/pages/runtime-overrides.adoc | 5 +- modules/ROOT/pages/runtime-parameters.adoc | 12 +- modules/ROOT/pages/whats-new.adoc | 31 + 11 files changed, 683 insertions(+), 6 deletions(-) create mode 100644 modules/ROOT/pages/liveboard-overrides.adoc diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 08d32656a..23fbe3210 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,24 @@ This page documents the changes introduced in each release of the Visual Embed SDK. For information about the REST API v2.0 changes, see the xref:rest-apiv2-changelog.adoc[REST API v2.0 changelog]. +== #Version 1.54.0# + +[width="100%", cols="1,4"] +|==== +|[tag greenBackground]#NEW# +a| +[discrete] +===== #Liveboard embedding# +#`liveboardOverride` in `LiveboardViewConfig` sets the values of a Liveboard's existing filter and parameter chips when the Liveboard loads. New types:# + +* #`LiveboardOverride`# +* #`LiveboardDataSourceOverride`# +* #`LiveboardFilterQuery`# +* #`LiveboardParameterQuery`# + +#For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +|==== + == Version 1.53.0, October 2026 [width="100%", cols="1,4"] diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index e9ea19007..65b51b4dc 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -96,6 +96,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] +** link:{{navprefix}}/liveboard-overrides[#Liveboard filter and parameter overrides#] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index 86cc82b95..c26a27d33 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -112,6 +112,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] +** link:{{navprefix}}/liveboard-overrides[#Liveboard filter and parameter overrides#] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc index c695e2606..451dac905 100644 --- a/modules/ROOT/pages/customize-liveboard-filters.adoc +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -52,7 +52,9 @@ The `showMaskedFilterChip` property is also available in full application embedd [#filters-at-load] == Apply filters at load time -By default, Liveboard filters cannot be applied at load. You can either embed a Liveboard that already includes filters or use the xref:runtime-filters.adoc[runtime filters] feature in the Visual Embed SDK to apply filters at load time. +#To open an embedded Liveboard with specific filter and parameter values, set `liveboardOverride`. The values appear in the Liveboard's filter and parameter chips. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To change values after load, use `HostEvent.UpdateFilters`.# + +#To add a filter condition that doesn't appear in the chips, use xref:runtime-filters.adoc[runtime filters] instead.# [IMPORTANT] ==== @@ -116,6 +118,8 @@ To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and ` For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. +#To set tab-level and group-level filter and parameter values at load, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# + [#update-filters] == Updating filters Use the following host events in the Visual Embed SDK to update filters: diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index 2664f383a..e901c3380 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -115,6 +115,8 @@ The customization options are grouped into the following pages: |Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling. |xref:customize-liveboard-filters.adoc[Customize Liveboard filters] |Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events. +|#xref:liveboard-overrides.adoc[Set filter and parameter values at load]# +|#Values of existing filter and parameter chips at load, through `liveboardOverride` or the Liveboard URL, with targeting by model, tab, or group.# |xref:liveboard-data-downloads.adoc[Customize data refresh and download options] |Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports. |==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index 7936588de..c1ef71f8d 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -37,7 +37,8 @@ xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more i 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + Liveboard filters are visible as UI components at the top of a Liveboard page. By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>. When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + -Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. +Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. + +#To set Liveboard filter and parameter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Overrides set the values of the Liveboard filters in this layer. They are not runtime filters (layer 3).# 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + Cross filters are ad-hoc filters based on user selection. These filters are used for brushing and linking Liveboard visualizations. + @@ -182,7 +183,7 @@ Any data restrictions resulting from filter rules will be seen in the visible fi xref:runtime-filters.adoc[Runtime filters] can be applied at load via Visual Embed SDK, REST API, or URL parameters. -Liveboard filters cannot be applied at load. However, they can be updated using `HostEvent.UpdateFilters` in the SDK. +#To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. After load, Liveboard filters can be updated using `HostEvent.UpdateFilters` in the SDK.# Search query filters can be applied at load by specifying them in the initial search query when embedding an Answer or Spotter session. For example, in Spotter embed, you can use the `searchQuery` property to set a pre-defined search (including filters) at load. @@ -196,7 +197,7 @@ If the column already has a Liveboard filter and the user applies cross filters, Whenever any user action affects a cross filter, a link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_crossfilterchanged[EmbedEvent.CrossFilterChanged] fires, which can then be used to trigger a specific action. == Updating filters using host events in Visual Embed SDK -There is no programmatic way to adjust the filter values before loading the Liveboard, but there are events that can adjust the values after the Liveboard is rendered. +#To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To adjust the values after the Liveboard is rendered, use the following events.# === OpenFilter event If you have hidden the Liveboard header, you can trigger the action of opening a filter modal dialog using link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_openfilter[HostEvent.OpenFilter]: diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc new file mode 100644 index 000000000..798c68b5d --- /dev/null +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -0,0 +1,596 @@ += Liveboard filter and parameter overrides +:toc: true +:toclevels: 2 + +:page-title: Liveboard filter and parameter overrides +:page-pageid: liveboard-overrides +:page-description: Set the values of a Liveboard's existing filter and parameter chips at load time, through the Liveboard URL or the liveboardOverride property of the Visual Embed SDK. + +[earlyAccess eaBackground]#Early Access# + +Liveboard filter and parameter overrides set the values of a Liveboard's existing filter and parameter chips when the Liveboard loads. This feature is available from ThoughtSpot Cloud 26.11.0.cl and Visual Embed SDK 1.54.0. + +== Overview + +You can supply overrides in two ways: + +* In the Liveboard URL, through the `filter` and `parameter` query parameters. +* In an embedded Liveboard, through the `liveboardOverride` property of the Visual Embed SDK. + +The Liveboard opens with the chips already showing the values you passed, and it fetches data once, with those values applied. Users can change the chips afterwards, just as they can after any other load. + +Use overrides for these tasks: + +* Open an embedded Liveboard with filters and parameters that match your application's context, such as the signed-in customer's region or the period selected in your app. +* Build links that open a Liveboard in a specific filtered state, for example a link from a row in one Liveboard to a detail Liveboard filtered on that row's values. +* Share a filtered state of a Liveboard without saving a personalized view for every combination of values. + +[#comparison] +== How overrides differ from runtime filters and runtime parameters + +xref:runtime-filters.adoc[Runtime filters] work on model columns. They add a filter behind the scenes, combine with the Liveboard's own filters as an AND condition, and don't appear in the filter chips. Overrides work on the Liveboard's filter and parameter chips instead. They replace the values selected in a chip, and the chip shows the new values. + +[width="100%", cols="2,3,3,3,3,3,3"] +[options='header'] +|===== +| +|Liveboard filter and parameter overrides +|Runtime filters +|Runtime Parameter overrides +|`UpdateFilters` and `UpdateParameters` host events +|`UpdateRuntimeFilters` host event +|Personalized views + +|*What it changes* +|Selected values of existing filter and parameter chips +|Adds a filter condition on a model column +|Sets a parameter's value +|Selected values of existing chips. `UpdateParameters` also sets runtime parameter values. +|Adds runtime filter conditions on model columns, appended to any runtime filters already applied +|A saved set of chip values + +|*Shown in the chips* +|Yes +|No +|No. The parameter chip is hidden. +|Yes. `UpdateParameters` can hide the chip with `isVisibleToUser: false`. +|No +|Yes + +|*Needs a chip on the Liveboard* +|Yes +|No +|No +|Yes +|No +|Yes + +|*When it applies* +|At load, before data is fetched +|At load +|At load +|After the Liveboard has rendered, which triggers a second data fetch +|After load. Resets the Liveboard to its original state, clearing drills and other user changes, then fetches data again. +|At load + +|*Effect on existing filter values* +|Replaces the chip's selection +|Combined with them (AND) +|Replaces the value +|Replaces the chip's selection +|Combined with them (AND) +|Replaces the chip's selection + +|*Rolling dates (for example, last 30 days)* +|Yes +|No. Dates are epoch values. +|No +|Yes +|No. Dates are epoch values. +|Yes + +|*Target a specific model, tab, or group* +|Yes +|No +|No +|Yes, with `applicability` +|No +|Not applicable + +|*Where it works* +|Liveboards: Liveboard URL and `LiveboardEmbed` +|Liveboards, Answers, visualizations, REST APIs +|Liveboards, Answers, REST APIs +|Embedded objects +|`LiveboardEmbed` and `AppEmbed` +|Liveboards + +|*Saved* +|No, unless the user saves a view +|No +|No +|No +|No +|Yes +|===== + +Use overrides when users should see and adjust the values in the Liveboard's own chips. + +== Before you begin + +* Your administrator must turn on *Filtered Liveboard URLs* on the *Early Access* page of the Admin portal. The setting is Org-aware. When it is off, overrides are ignored without an error. +* To use `liveboardOverride`, use Visual Embed SDK 1.54.0 or later. +* Every filter or parameter you want to set must already exist as a chip on the Liveboard. Overrides never add a chip. +* To target a tab or group, xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[contextual filtering] (tab-level and group-level filters) must be turned on. When it is off, any clause that names a tab or group is ignored. + +== Example Liveboard + +Every example on this page uses a Liveboard named *Retail Sales Overview*, set up as follows: + +* Two models: *Retail Sales* and *Returns*. Both have a *Region* column. +* Two tabs: *Summary* and *Regional Detail*. The *Regional Detail* tab has a group named *Top Stores*. +* Liveboard-level filter chips: +** *Region* on Retail Sales, and *Region* on Returns +** *Product Type* (attribute) +** *Sales* (measure) +** *Order Date* (date) +* Tab-level filter chips, on the *Regional Detail* tab: +** *Product Type* (attribute) +* Group-level filter chips, in the *Top Stores* group: +** *Store Name* (attribute) +* Parameter chips, at the Liveboard level: +** *Discount Rate*: Double, range 0 to 0.5 +** *Top N*: Integer, range 1 to 50 +** *Target Region*: String, list of West, East, Central, South +** *Forecast Start*: Date + +[#embed] +== Apply overrides in an embedded Liveboard + +Set `liveboardOverride` in the `LiveboardEmbed` configuration. The overrides apply when the Liveboard loads. + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + liveboardId: '', + liveboardOverride: { + dataSourceOverride: [ + { + // No dataSourceIdentifier: matching chips on every model are updated + filterQuery: [ + { filterQueryToken: 'Region = West, East' }, + { filterQueryToken: 'Order Date = last 30 days' }, + ], + parameterQuery: [ + { parameterQueryToken: 'Discount Rate = 0.15' }, + ], + }, + { + dataSourceIdentifier: 'Retail Sales', + filterQuery: [ + { + tabName: 'Regional Detail', + groupName: 'Top Stores', + filterQueryToken: 'Store Name = Downtown, Airport', + }, + ], + }, + ], + }, +}); +embed.render(); +---- + +=== liveboardOverride properties + +[width="100%", cols="3,2,6"] +[options='header'] +|===== +|Property |Type |Description +|`dataSourceOverride` +|Array, required +|A list of override entries. Each entry groups the filter and parameter clauses for one model, or for all models when `dataSourceIdentifier` is omitted. + +|`dataSourceOverride[].dataSourceIdentifier` +|String, optional +a|The name or GUID of a model used by the Liveboard. Names are not case-sensitive. + +* When set, the entry's clauses update only that model's chips. +* When omitted or empty, they update matching chips on every model. +* If the identifier doesn't match a model on the Liveboard, every clause in the entry is ignored. + +|`dataSourceOverride[].filterQuery` +|Array, optional +a|Filter clauses. Each item has: + +* `filterQueryToken` (string, required): one filter clause, such as `Region = West`. See <>. +* `tabName` (string, optional): the tab whose chips to update. +* `groupName` (string, optional): the group whose chips to update. + +|`dataSourceOverride[].parameterQuery` +|Array, optional +a|Parameter clauses. Each item has: + +* `parameterQueryToken` (string, required): one parameter clause, such as `Top N = 10`. See <>. +* `tabName` (string, optional) +* `groupName` (string, optional) +|===== + +Each token holds exactly one clause. Don't join clauses with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. Leave out properties you don't need rather than setting them to empty strings. + +=== Behavior in an embedded Liveboard + +* `liveboardOverride` is the only way to pass overrides to an embedded Liveboard. Unlike runtime filters, which you can add to an embedded object's URL, adding `filter=` or `parameter=` to the URL of an embedded Liveboard has no effect. +* Overrides apply when the Liveboard loads. Changing `liveboardOverride` after the Liveboard has rendered doesn't reload it. To change filter or parameter values after load, use the xref:filters_overview.adoc#_updatefilters_event[`UpdateFilters`] and `UpdateParameters` host events. +* Clauses with no token are dropped, and so are properties the SDK doesn't recognize. +* When a personalized view is loaded in the embedded Liveboard, for example because the user selects one, the view opens with its saved values, and the overrides aren't applied to it. + +[#url] +== Apply overrides in a Liveboard URL + +Add the `filter` and `parameter` query parameters after the Liveboard's route, that is, after the `+#+`: + +---- +https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter clauses}¶meter={parameter clauses} +---- + +* Both keys are optional, and both are singular: `filter`, not `filters`. +* Put them in the query string after the route. If they come before the `+#+`, they are ignored. Legacy runtime filters work the other way: `col1`, `op1` and `val1` go before the `+#+`. +* You can combine them with other Liveboard URL parameters, such as a tab (`+#/pinboard/{liveboard-id}/tab/{tab-id}?filter=...+`) or a personalized view (`+?view={view-id}&filter=...+`). +* Separate clauses with a semicolon (`;`). +* Spaces around operators are optional: `Region=West` and `Region = West` are the same clause. +* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region = West"+`. Curly quotes are not removed, and quoting individual clauses isn't supported. + +=== URL examples + +Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region = West, East+`. + +[width="100%", cols="3,5"] +[options='header'] +|===== +|Goal |Add to the URL +|Show the West and East regions |`+?filter=Region = West, East+` +|Show the last 30 days |`+?filter=Order Date = last 30 days+` +|Set three filters and a parameter |`+?filter=Region = West; Order Date = this quarter; Sales > 10000¶meter=Discount Rate = 0.15+` +|Update only the Retail Sales model's Region chip |`+?filter=Retail Sales::Region = West+` +|Update the Product Type chip on the Regional Detail tab |`+?filter=Regional Detail::Product Type = Shoes, Jackets+` +|Update the Store Name chip in the Top Stores group |`+?filter=Regional Detail::Top Stores::Store Name = Downtown, Airport+` +|Clear the Product Type chip |`+?filter=Product Type =+` +|Set two parameters |`+?parameter=Forecast Start = 2026-07-01; Top N = 10+` +|Apply on top of a personalized view |`+?view={view-id}&filter=Region = West+` +|===== + +=== Encoding + +You can type or paste these values as shown. The browser encodes spaces and other characters when it opens the URL. Encode a value yourself only in these cases: + +* The value contains `&`, `+++`, `%`, `+#+` or `\`. Write them as `%26`, `%2B`, `%25`, `%23` and `%5C`. Otherwise the browser reads them as part of the URL itself. +* You build the URL in code, or send it where spaces break links, such as email or chat. Use `encodeURIComponent()` on each value. For example, `+?filter=Region = West, East+` becomes `+?filter=Region%20%3D%20West%2C%20East+`. + +[#filter-clauses] +== Filter clauses + +A filter clause has this form: + +---- +{Column name} {operator} {value}[, {value}...] +---- + +* *Column name*: the name shown on the filter chip. It is not case-sensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. +* *Operators*: `=`, `!=`, `<`, `+<=+`, `>`, `>=`. Which operators you can use depends on the column type, as shown in the tables below. +* *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name = New York Downtown, San Francisco Bay` is a list of two values. +* *Keywords*: keywords such as `between`, `last` and `today` are not case-sensitive. + +=== Attribute columns + +[width="100%", cols="4,5"] +[options='header'] +|===== +|Clause |Result +|`Region = West` |Region is West +|`Region = West, East, Central` |Region is any of West, East, Central +|`Region != South` |Region is not South +|`Region != South, Central` |Region is none of South, Central +|`+Store Name = Smith\, Jones and Co+` |One value that contains a comma +|`Region =` |Clears the chip, so all values are shown +|===== + +Not accepted on attribute columns: + +* `<`, `+<=+`, `>`, `>=` (for example, `Region > West`) +* `between` +* Contains, begins with, or ends with matching +* An empty list item, such as `Region = West,` or `Region = West,,East` +* `{null}`. Filtering on null values isn't supported. + +Values are passed as written. Type them as they appear in the data. + +=== Measure columns + +[width="100%", cols="4,5"] +[options='header'] +|===== +|Clause |Result +|`Sales > 10000` |Greater than 10000. `>=`, `<` and `+<=+` work the same way. +|`Sales = between 1000 5000` |Between 1000 and 5000, inclusive +|`Sales =` |Clears the chip +|===== + +Rules for measure values: + +* Comparison operators take exactly one value. +* `between` takes exactly two values, separated by a space, with the smaller value first. +* Decimal values (`1250.75`) and negative values (`-200`) are supported. +* Thousands separators (`10,000`), currency symbols (`$100`), and percent signs are not supported. + +Not accepted: + +* `Sales > 100, 200` +* `Sales = between 1000, 5000` (comma between the values) +* `Sales = between 5000 1000` (larger value first) +* `Sales != between 1000 5000` (measures have no "not between") + +=== Date columns: rolling dates + +[width="100%", cols="4,5"] +[options='header'] +|===== +|Clause |Result +|`Order Date = today` |Today. `yesterday` and `tomorrow` also work. +|`Order Date = this quarter` |The current quarter +|`Order Date = last 30 days` |The last 30 days +|`Order Date = last quarter` |The last quarter (same as `last 1 quarter`) +|`Order Date = last 24 hours` |The last 24 hours. Periods can be as short as `second`, `minute` and `hour`. +|`Order Date = next 2 weeks` |The next 2 weeks +|`Order Date = next quarter` |The next quarter (same as `next 1 quarter`) +|`Order Date = year to date` |Year to date. `week`, `month`, and `quarter to date` also work. +|`Order Date > last 2 months` |After the last 2 months +|`+Order Date <= this month+` |On or before this month +|`Order Date < today` |Before today. The before/after operators also work with `today`, `yesterday` and `tomorrow`. +|===== + +Periods are `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, and `year`, in singular or plural form. Abbreviations such as `wk` or `yr` are not supported. + +Operators for rolling dates: + +* Rolling dates accept `=`, `<`, `+<=+`, `>`, and `>=`. +* Rolling dates do not accept `!=`. +* "To date" periods accept only `=`. + +=== Date columns: fixed dates + +[width="100%", cols="4,5"] +[options='header'] +|===== +|Clause |Result +|`Order Date = 2026-08-31` |On that day. `!=`, `<`, `+<=+`, `>`, and `>=` also work. +|`Order Date = between 2026-01-01 2026-06-30` |Between the two dates, inclusive +|`Order Date != between 2026-01-01 2026-06-30` |Not between the two dates +|`Order Date = january 2026` |The whole month +|`Order Date = q1 2026` |The whole quarter (`q1` to `q4`) +|`Order Date = 2026` |The whole year +|`Order Date =` |Clears the chip +|===== + +Rules for fixed dates: + +* Write dates in ISO format, `yyyy-MM-dd`. A date is read as the start of that day in the ThoughtSpot cluster's time zone. +* Write month names in full (`january`, not `jan`), followed by a four-digit year. +* Month, quarter, and year values accept only `=`. +* In a `between` range, the earlier date comes first. +* Commas are not allowed in date clauses. + +Not accepted: + +* `08/31/2026` or other non-ISO formats +* `jan 2026` or `january` without a year +* `Q1-2026`, or fiscal quarters written as `fiscal q1 2026` +* Date and time values, such as `2026-08-31 10:00` +* Free-form phrases, such as `start of week`, `3 days ago`, `now`, or `last 7 days inclusive` +* `day to date` +* `Order Date = after last 2 months`. Write before and after as operators instead: `Order Date > last 2 months`. + +[#parameter-clauses] +== Parameter clauses + +A parameter clause has this form: + +---- +{Parameter name} = {value} +---- + +* *Parameter name*: the parameter's name, or the label shown on its chip. It is not case-sensitive. +* *Value*: exactly one value, written for the parameter's data type. + +[width="100%", cols="2,4,4"] +[options='header'] +|===== +|Data type |Example |Notes +|Integer |`Top N = 10` |Whole numbers only +|Double |`Discount Rate = 0.15` | +|String |`Target Region = West` | +|Boolean |`Include Returns = true` |Use `true` or `false` +|Date |`Forecast Start = 2026-07-01` |ISO format, `yyyy-MM-dd` +|===== + +The value must satisfy the parameter's own restrictions: + +* For a parameter with a list of values, use one of the values or one of their display names. Display names are not case-sensitive. +* For a parameter with a range, the value must fall inside the range. +* A value that doesn't meet these restrictions is ignored, and the chip keeps its current value. + +Not accepted: + +* Any operator other than `=` +* More than one value, such as `Top N = 5, 10` +* An empty value (`Top N =`). Parameter chips can't be cleared. +* `{null}` +* Dynamic date values, such as `Forecast Start = today` or `last 7 days` +* Date-time and time parameters + +== Special characters in values + +Use a backslash (`\`) to write a character that the syntax would otherwise read as part of the clause structure: + +[width="100%", cols="3,2,4"] +[options='header'] +|===== +|To include |Write |Where needed +|A comma inside a value |`+\,+` |URL and SDK +|`=`, `<`, `>` inside a value |`+\=+`, `+\<+`, `+\>+` |URL and SDK +|A semicolon inside a value |`+\;+` |URL only. In the SDK, each token is already one clause. +|`::` inside a value |`+\::+` |URL only +|===== + +A single colon needs no escaping. For example, `Region = sales: eu` is read as one value. + +[#scoping] +== Target a model, tab, or group + +When no model, tab, or group is given, a clause updates every chip with a matching name: on every model, and at the Liveboard, tab, and group levels. For example, `Region = West` updates the Region chip on both Retail Sales and Returns. + +To narrow a clause, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK: + +[width="100%", cols="4,3,4"] +[options='header'] +|===== +|URL clause |SDK equivalent |Chips updated +|`Region = West` |`{ filterQueryToken: 'Region = West' }` |Region chips on all models, at every level +|`Retail Sales::Region = West` |`dataSourceIdentifier: 'Retail Sales'` |Region chips on the Retail Sales model only, at every level +|`Regional Detail::Product Type = Shoes` |`tabName: 'Regional Detail'` |Product Type chips on the Regional Detail tab, including groups on that tab. Liveboard-level chips are not updated. +|`Top Stores::Store Name = Downtown` |`groupName: 'Top Stores'` |Store Name chips in every group named Top Stores +|`Regional Detail::Top Stores::Store Name = Downtown` |`tabName` and `groupName` |Store Name chips in the Top Stores group on the Regional Detail tab +|`Retail Sales::Regional Detail::Top Stores::Store Name = Downtown` |All three properties |As above, for the Retail Sales model only +|===== + +How prefixes are matched in a URL: + +* Names are matched against the display names of models, tabs, and groups. Matching is not case-sensitive. +* A model can also be given by its GUID. Tabs and groups are matched by name only. +* When all three prefixes are given, they are read in order: model, tab, group. +* With one or two prefixes, each name is looked up as a model first, then as a tab, then as a group. So if a model and a tab share a name, the name is read as the model. To name the tab in that case, use the SDK properties. +* A clause with more than three prefixes is ignored. +* A clause whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. + +Parameters use the same prefixes. For example, `Retail Sales::Discount Rate = 0.15` updates the Discount Rate chip for the Retail Sales model only. + +There is no prefix that targets only a Liveboard-level chip. A clause without a tab or group prefix also updates tab-level and group-level chips with the same name. To change only a tab or a group, add its prefix. + +== How overrides behave + +=== Only existing chips are updated + +* A clause updates a chip only if the chip already exists on the Liveboard. If a column or parameter is used in a visualization but has no chip, the clause is ignored, and no chip is added. +* xref:runtime-parameters.adoc[Runtime parameter overrides] behave differently: they apply to any parameter used in the Liveboard. +* To change a linked parameter, target its primary parameter. Clauses that target a linked secondary parameter are ignored. + +=== Invalid clauses are skipped + +* Each clause is applied independently. If a clause can't be applied, because of a misspelled name, an invalid value, an unknown prefix, or a missing chip, only that clause is skipped. The other clauses still apply, and the Liveboard always loads. +* No error or warning is shown, so check the chips after the Liveboard loads to confirm which values were applied. +* Overrides can be applied differently for different users. For example, a clause on a model the user can't access is skipped for that user. + +=== Personalized views + +For a URL that includes a view (`+?view={view-id}&filter=...+`): + +* The Liveboard opens the view, then applies the overrides on top of it. +* Chips you don't override keep the view's values. +* The view shows as modified, and the user can update it with the new values. + +For a URL with overrides but no view: + +* The Liveboard opens with its saved values plus the overrides, even if the user has set a default view. +* The *Save view* option becomes available, so the user can save the overridden state as a new view. + +=== How long overrides last + +Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the URL while the user works in view mode: + +[width="100%", cols="3,6"] +[options='header'] +|===== +|Action |Result +|Reload the page |The overrides are applied again. Filter changes the user made after load are lost. +|Switch tabs |The overrides stay in effect. +|Open and close *Explore* on a visualization |The overrides stay in effect. +|Reset filters in the filter window |The overrides are removed from the URL, and the chips return to their saved values. +|Enter edit mode |The overrides are removed from the URL, and the Liveboard returns to its saved state. Any other filter changes made in view mode are discarded too. Saving the Liveboard never saves override values. +|Save or update a personalized view |The view stores the values currently shown, including overridden ones. +|Open the Liveboard without the `filter` and `parameter` keys |The Liveboard opens with its saved values, or with the default view. +|===== + +=== Downloads, schedules, and alerts + +* Downloads from the Liveboard, such as PDF or a visualization's CSV, use the overridden values. +* Scheduled Liveboard jobs and alerts use the saved values. Overrides aren't applied to them. + +[#precedence] +=== Security and precedence + +* Overrides are not a security feature. Anyone who can edit the URL can change the values or remove them. To restrict data, use xref:rls-rules.adoc[row-level security (RLS)] or the xref:abac-user-parameters.adoc[ABAC and JWT security methods]. +* Overrides can't expose data the user isn't allowed to see. RLS applies to the overridden values as it does to any filter. Clauses on columns the user can't access are skipped. +* A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, if a JWT token pins `Discount Rate` to `0.1` and the URL sets `Discount Rate = 0.15`, the Liveboard uses `0.1`. Sources, from highest to lowest priority: +.. A value pinned through ABAC with a JWT token +.. A runtime parameter override (`runtimeParameters`, or `param1` and `paramVal1` in the URL) +.. A Liveboard parameter override +.. The personalized view's value +.. The Liveboard's saved value +.. The parameter's default value +* Don't set the same parameter with both a runtime parameter override and a Liveboard override. The runtime override wins, and the chip is hidden. +* Runtime filters and Liveboard filter overrides can be used together. The runtime filter restricts the column's data, and the override sets the chip's selection, and both apply. + +== Limitations + +* Overrides work on Liveboards only. Answers, saved Answers, Search, and Spotter don't support them, in the UI or in embeds. +* In embedded deployments, only `LiveboardEmbed` is supported. Full application embedding (`AppEmbed`) is not supported in this release. +* Overrides apply only at load. To change values after load in an embed, use the `UpdateFilters` and `UpdateParameters` host events. +* Dynamic date values for parameters are not supported, and date-time and time parameters are not supported. +* A parameter chip can't be cleared. +* Overrides don't create chips, and they don't apply to columns or parameters without a chip. +* Scheduled jobs and alerts don't use overrides. +* Skipped clauses aren't reported in the UI or through an embed event. + +== Troubleshooting + +[width="100%", cols="3,6"] +[options='header'] +|===== +|Symptom |Check +|Nothing is applied +a| +* *Filtered Liveboard URLs* is turned on for the Org. +* The keys are `filter` and `parameter`, singular. +* The keys come after the `+#+` route. +* In an embed, the overrides are in `liveboardOverride`, not in the URL. + +|One clause is not applied +a| +* A chip exists for that column or parameter, at the scope you targeted. +* The name matches the chip name in full. +* The value format matches the tables above: ISO dates, one value for parameters, a value inside the parameter's list or range. +* Any prefix matches a model, tab, or group name. + +|A clause works for some users but not others +|The user may not have access to the model or column. Clauses on sources a user can't access are skipped for that user. + +|The URL is cut off or a value is wrong +|Encode `&`, `+++`, `%`, `+#+`, and `\` in values. + +|Values disappear after entering edit mode +|Expected. Edit mode always shows the saved Liveboard. + +|A tab or group clause is ignored +|Contextual filtering must be turned on. Check the tab and group names. +|===== + +To check what was sent, open the browser's developer tools. On the *Network* tab, find the `LoadPinboardSession` request: its `liveboardOverride` variable shows the clauses ThoughtSpot received. + +== Related information + +* xref:runtime-filters.adoc[Runtime filters] +* xref:runtime-parameters.adoc[Runtime Parameter overrides] +* xref:filters_overview.adoc[Filter types and application layers] +* xref:customize-liveboard-filters.adoc[Customize Liveboard filters] +* xref:LiveboardViewConfig.adoc#_liveboardoverride[LiveboardViewConfig.liveboardOverride (SDK reference)] diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index d9791fbcb..787b8a0f7 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -28,6 +28,11 @@ Pass filter properties as query parameters in the URL. * Runtime filters is not a security feature. To implement data security rules in ThoughtSpot, please use xref:rls-rules.adoc[Row Level Security (RLS rules)]. ==== +[NOTE] +==== +#Runtime filters add a hidden filter condition on a model column. To set the values shown in a Liveboard's filter chips instead, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. For a side-by-side comparison, see xref:liveboard-overrides.adoc#comparison[How overrides differ from runtime filters and runtime parameters].# +==== + === Runtime filter properties A runtime filter consists of the following attributes: @@ -729,6 +734,11 @@ The following example passes multiple variables to a single column as well as mu == Apply runtime filters on a Liveboard or visualization URL +[NOTE] +==== +#Runtime filter keys such as `col1`, `op1`, and `val1` go before the `+#+` in the URL. To set the values of a Liveboard's filter chips through the URL, use the `filter` and `parameter` keys after the `+#+` instead. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides].# +==== + The following examples show the runtime filter query string in a Liveboard URL: `\https://{ThoughtSpot-Host}/?col1=State&op1=EQ&val1=California#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a` diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 44093dd9d..eb4f4a6c1 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -40,6 +40,9 @@ Like runtime filters, xref:runtime-parameters.adoc[Parameters] can be applied on * xref:SearchViewConfig.adoc[SearchEmbed] * xref:AppViewConfig.adoc[AppEmbed] -After the object loads, Parameter values can be link:runtime-parameters.adoc#_adjust_parameter_values_using_sdk_events[adjusted using the SDK events]. +#After the object loads, Parameter values can be xref:runtime-parameters.adoc#_adjust_parameter_values_using_a_host_event[adjusted using the SDK events].# + +== #Liveboard filter and parameter overrides# [earlyAccess eaBackground]#Early Access# +#xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides] set the values of a Liveboard's existing filter and parameter chips when it loads, through the Liveboard URL or the `liveboardOverride` SDK property. Unlike runtime filters, the chips show the values. See xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index ca32d4642..e188c4030 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -28,6 +28,11 @@ Pass Parameter name and values as query parameters in the URL. When applied, runtime parameters override the default or saved Parameter values for the user session or API call, and the changes are reflected in the resulting data and visualizations, but not saved to the object itself. +[NOTE] +==== +#Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +==== + === Supported data types You can apply runtime Parameters on the following data types: @@ -382,6 +387,11 @@ You can apply overrides to Parameter values at runtime and visualize data with t For example, if you want to override the value of the inflation Parameter on a Liveboard or Answer, add the Parameters to the object URL as shown in these examples: +[NOTE] +==== +#The `param1` and `paramVal1` keys go before the `+#+` and hide the parameter chip. The `parameter` key that comes after the `+#+` in a Liveboard URL is a different feature, which sets the value of a visible parameter chip. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides].# +==== + .Liveboard ---- https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a @@ -406,7 +416,7 @@ ThoughtSpot returns an error if an object URL with Parameter attributes exceeds Parameters work differently when used in JWT tokens to secure values for users. Setting a Parameter value via a JWT token will not hide the Parameter value by default. It lets you display a placeholder value on the Parameter chip, for example “Secured”, to indicate that the Parameter is used for security purposes. Note that the placeholder Parameter value is the default value set in your Parameter. Business users will see this value on the Parameter chip. However, the value of the parameter being used in the data displayed will be the one passed via the JWT token. -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. +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. #JWT-pinned values also take precedence over xref:liveboard-overrides.adoc#precedence[Liveboard filter and parameter overrides].# 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: diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 9628f34b3..f34dd815d 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -23,6 +23,37 @@ This page lists new features, enhancements, and deprecated functionality introdu // ============================================================ +== #November 2026# + +#**Release version**: ThoughtSpot Cloud 26.11.0.cl# + +#*Recommended SDK versions*: Visual Embed SDK v1.54.0 or later# + +[.cl-table, cols="2,4", frame=none, grid=none] +|=== +a| +[.cl-label] +#*Version 26.11.0.cl*# + +a| + +[discrete] +==== #Liveboard filter and parameter overrides# [earlyAccess eaBackground]#Early Access# +#You can now set the values of a Liveboard's filter and parameter chips when the Liveboard loads. Two ways are available:# + +* #The new `liveboardOverride` property in `LiveboardViewConfig`, for embedded Liveboards.# +* #The `filter` and `parameter` query parameters in a Liveboard URL.# + +#Unlike runtime filters, overrides update the chips the user sees. They support rolling dates, and they can target a specific model, tab, or group. The Liveboard fetches its data once, with the values already applied. To enable this feature, ask your administrator to turn on *Filtered Liveboard URLs* in the Admin portal. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# + +--- + +[discrete] +==== #Visual Embed SDK# +#For information about the new features and enhancements introduced in Visual Embed SDK version 1.54.0, see xref:api-changelog.adoc[Visual Embed SDK changelog].# + +|=== + + == October 2026 **Release version**: ThoughtSpot Cloud 26.10.0.cl + From 7e530bb599c3a410709cb5e288d5af76bb7164a3 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 14:34:40 +0530 Subject: [PATCH 06/48] SCAL-280404-1 --- modules/ROOT/pages/liveboard-overrides.adoc | 34 ++++++++++++--------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 798c68b5d..3ba9c1280 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -8,7 +8,7 @@ [earlyAccess eaBackground]#Early Access# -Liveboard filter and parameter overrides set the values of a Liveboard's existing filter and parameter chips when the Liveboard loads. This feature is available from ThoughtSpot Cloud 26.11.0.cl and Visual Embed SDK 1.54.0. +Liveboard filter and parameter overrides set the values of a Liveboard's existing filter and parameter chips at load time. This feature requires ThoughtSpot Cloud 26.11.0.cl and Visual Embed SDK 1.54.0 or later. == Overview @@ -17,7 +17,7 @@ You can supply overrides in two ways: * In the Liveboard URL, through the `filter` and `parameter` query parameters. * In an embedded Liveboard, through the `liveboardOverride` property of the Visual Embed SDK. -The Liveboard opens with the chips already showing the values you passed, and it fetches data once, with those values applied. Users can change the chips afterwards, just as they can after any other load. +The Liveboard opens with the chips already showing the values you passed, and it fetches data once, with those values applied. Users can change the chips afterward, just as they can after any other load. Use overrides for these tasks: @@ -28,7 +28,9 @@ Use overrides for these tasks: [#comparison] == How overrides differ from runtime filters and runtime parameters -xref:runtime-filters.adoc[Runtime filters] work on model columns. They add a filter behind the scenes, combine with the Liveboard's own filters as an AND condition, and don't appear in the filter chips. Overrides work on the Liveboard's filter and parameter chips instead. They replace the values selected in a chip, and the chip shows the new values. +xref:runtime-filters.adoc[Runtime filters] work on model columns. They add a filter condition behind the scenes and combine with the Liveboard's existing filters using an AND condition. They do not appear in the filter chips. + +Overrides work on the Liveboard's filter and parameter chips instead. They replace the values selected in a chip, and the chip shows the new values. [width="100%", cols="2,3,3,3,3,3,3"] [options='header'] @@ -194,7 +196,7 @@ embed.render(); |`dataSourceOverride[].dataSourceIdentifier` |String, optional -a|The name or GUID of a model used by the Liveboard. Names are not case-sensitive. +a|The name or GUID of a model used by the Liveboard. Names are case-insensitive. * When set, the entry's clauses update only that model's chips. * When omitted or empty, they update matching chips on every model. @@ -217,7 +219,9 @@ a|Parameter clauses. Each item has: * `groupName` (string, optional) |===== -Each token holds exactly one clause. Don't join clauses with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. Leave out properties you don't need rather than setting them to empty strings. +Each token holds exactly one clause. Do not join clauses with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. + +Leave out properties you don't need rather than setting them to empty strings. === Behavior in an embedded Liveboard @@ -232,7 +236,7 @@ Each token holds exactly one clause. Don't join clauses with `;` or add `Model:: Add the `filter` and `parameter` query parameters after the Liveboard's route, that is, after the `+#+`: ---- -https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter clauses}¶meter={parameter clauses} +https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter={filter clauses}¶meter={parameter clauses} ---- * Both keys are optional, and both are singular: `filter`, not `filters`. @@ -244,7 +248,7 @@ https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter clauses}&par === URL examples -Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region = West, East+`. +Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter=Region = West, East+`. [width="100%", cols="3,5"] [options='header'] @@ -277,10 +281,10 @@ A filter clause has this form: {Column name} {operator} {value}[, {value}...] ---- -* *Column name*: the name shown on the filter chip. It is not case-sensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. +* *Column name*: the name shown on the filter chip. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. * *Operators*: `=`, `!=`, `<`, `+<=+`, `>`, `>=`. Which operators you can use depends on the column type, as shown in the tables below. * *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name = New York Downtown, San Francisco Bay` is a list of two values. -* *Keywords*: keywords such as `between`, `last` and `today` are not case-sensitive. +* *Keywords*: keywords such as `between`, `last` and `today` are case-insensitive. === Attribute columns @@ -400,7 +404,7 @@ A parameter clause has this form: {Parameter name} = {value} ---- -* *Parameter name*: the parameter's name, or the label shown on its chip. It is not case-sensitive. +* *Parameter name*: the parameter's name, or the label shown on its chip. It is case-insensitive. * *Value*: exactly one value, written for the parameter's data type. [width="100%", cols="2,4,4"] @@ -416,7 +420,7 @@ A parameter clause has this form: The value must satisfy the parameter's own restrictions: -* For a parameter with a list of values, use one of the values or one of their display names. Display names are not case-sensitive. +* For a parameter with a list of values, use one of the values or one of their display names. Display names are case-insensitive. * For a parameter with a range, the value must fall inside the range. * A value that doesn't meet these restrictions is ignored, and the chip keeps its current value. @@ -448,7 +452,7 @@ A single colon needs no escaping. For example, `Region = sales: eu` is read as o [#scoping] == Target a model, tab, or group -When no model, tab, or group is given, a clause updates every chip with a matching name: on every model, and at the Liveboard, tab, and group levels. For example, `Region = West` updates the Region chip on both Retail Sales and Returns. +When no model, tab, or group is given, a clause updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region = West` updates the Region chip on both Retail Sales and Returns. To narrow a clause, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK: @@ -466,7 +470,7 @@ To narrow a clause, prefix it with names separated by `::` in a URL, or set `dat How prefixes are matched in a URL: -* Names are matched against the display names of models, tabs, and groups. Matching is not case-sensitive. +* Names are matched against the display names of models, tabs, and groups. Matching is case-insensitive. * A model can also be given by its GUID. Tabs and groups are matched by name only. * When all three prefixes are given, they are read in order: model, tab, group. * With one or two prefixes, each name is looked up as a model first, then as a tab, then as a group. So if a model and a tab share a name, the name is read as the model. To name the tab in that case, use the SDK properties. @@ -475,7 +479,7 @@ How prefixes are matched in a URL: Parameters use the same prefixes. For example, `Retail Sales::Discount Rate = 0.15` updates the Discount Rate chip for the Retail Sales model only. -There is no prefix that targets only a Liveboard-level chip. A clause without a tab or group prefix also updates tab-level and group-level chips with the same name. To change only a tab or a group, add its prefix. +There is no prefix that targets only a Liveboard-level chip. A clause without a tab or group prefix updates all chips with a matching column name, including tab-level and group-level chips. To target only a tab or group, add its prefix. == How overrides behave @@ -593,4 +597,4 @@ To check what was sent, open the browser's developer tools. On the *Network* tab * xref:runtime-parameters.adoc[Runtime Parameter overrides] * xref:filters_overview.adoc[Filter types and application layers] * xref:customize-liveboard-filters.adoc[Customize Liveboard filters] -* xref:LiveboardViewConfig.adoc#_liveboardoverride[LiveboardViewConfig.liveboardOverride (SDK reference)] +* xref:LiveboardViewConfig.adoc#_liveboardoverride[SDK reference] \ No newline at end of file From 334ef5abff28f03adcae785d2f1769b169660248 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 21:15:45 +0530 Subject: [PATCH 07/48] SCAL-280404-2 --- modules/ROOT/pages/liveboard-overrides.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 3ba9c1280..f456f1ea2 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -291,7 +291,7 @@ A filter clause has this form: [width="100%", cols="4,5"] [options='header'] |===== -|Clause |Result +|Input |Result |`Region = West` |Region is West |`Region = West, East, Central` |Region is any of West, East, Central |`Region != South` |Region is not South @@ -315,7 +315,7 @@ Values are passed as written. Type them as they appear in the data. [width="100%", cols="4,5"] [options='header'] |===== -|Clause |Result +|Input |Result |`Sales > 10000` |Greater than 10000. `>=`, `<` and `+<=+` work the same way. |`Sales = between 1000 5000` |Between 1000 and 5000, inclusive |`Sales =` |Clears the chip @@ -340,7 +340,7 @@ Not accepted: [width="100%", cols="4,5"] [options='header'] |===== -|Clause |Result +|Input |Result |`Order Date = today` |Today. `yesterday` and `tomorrow` also work. |`Order Date = this quarter` |The current quarter |`Order Date = last 30 days` |The last 30 days @@ -364,10 +364,10 @@ Operators for rolling dates: === Date columns: fixed dates -[width="100%", cols="4,5"] +[width="100%", cols="53,47"] [options='header'] |===== -|Clause |Result +|Input |Result |`Order Date = 2026-08-31` |On that day. `!=`, `<`, `+<=+`, `>`, and `>=` also work. |`Order Date = between 2026-01-01 2026-06-30` |Between the two dates, inclusive |`Order Date != between 2026-01-01 2026-06-30` |Not between the two dates From c81527a1ae2e4e8391b83ede4c319bc3767f89b6 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 22:04:09 +0530 Subject: [PATCH 08/48] SCAL-280404-3 --- modules/ROOT/pages/liveboard-overrides.adoc | 62 +++++++-------------- 1 file changed, 19 insertions(+), 43 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index f456f1ea2..ae7c2dc8d 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -32,90 +32,66 @@ xref:runtime-filters.adoc[Runtime filters] work on model columns. They add a fil Overrides work on the Liveboard's filter and parameter chips instead. They replace the values selected in a chip, and the chip shows the new values. -[width="100%", cols="2,3,3,3,3,3,3"] +[width="100%", cols="4,3,3,3,3"] [options='header'] |===== | -|Liveboard filter and parameter overrides +|Liveboard overrides |Runtime filters |Runtime Parameter overrides -|`UpdateFilters` and `UpdateParameters` host events -|`UpdateRuntimeFilters` host event |Personalized views -|*What it changes* -|Selected values of existing filter and parameter chips -|Adds a filter condition on a model column -|Sets a parameter's value -|Selected values of existing chips. `UpdateParameters` also sets runtime parameter values. -|Adds runtime filter conditions on model columns, appended to any runtime filters already applied +|*What it sets* +|Values in existing filter and parameter chips +|A filter condition on a model column +|A parameter's value |A saved set of chip values |*Shown in the chips* |Yes |No -|No. The parameter chip is hidden. -|Yes. `UpdateParameters` can hide the chip with `isVisibleToUser: false`. -|No +|No (chip is hidden) |Yes -|*Needs a chip on the Liveboard* +|*Needs a chip* |Yes |No |No |Yes -|No -|Yes -|*When it applies* -|At load, before data is fetched -|At load -|At load -|After the Liveboard has rendered, which triggers a second data fetch -|After load. Resets the Liveboard to its original state, clearing drills and other user changes, then fetches data again. -|At load - -|*Effect on existing filter values* -|Replaces the chip's selection -|Combined with them (AND) +|*Effect on existing values* +|Replaces the selection +|Adds an AND condition |Replaces the value -|Replaces the chip's selection -|Combined with them (AND) -|Replaces the chip's selection +|Replaces the selection -|*Rolling dates (for example, last 30 days)* +|*Rolling dates* |Yes -|No. Dates are epoch values. |No -|Yes -|No. Dates are epoch values. +|No |Yes -|*Target a specific model, tab, or group* +|*Targets a model, tab, or group* |Yes |No |No -|Yes, with `applicability` -|No |Not applicable -|*Where it works* -|Liveboards: Liveboard URL and `LiveboardEmbed` +|*Works on* +|Liveboards |Liveboards, Answers, visualizations, REST APIs |Liveboards, Answers, REST APIs -|Embedded objects -|`LiveboardEmbed` and `AppEmbed` |Liveboards |*Saved* -|No, unless the user saves a view -|No |No |No |No |Yes |===== +To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters and resets the Liveboard to its original state. + Use overrides when users should see and adjust the values in the Liveboard's own chips. == Before you begin From 86332c4ac189353a71494e83eb3656f9b7056655 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 23:22:33 +0530 Subject: [PATCH 09/48] SCAL-280404-4 --- modules/ROOT/pages/liveboard-overrides.adoc | 150 ++++++++++---------- 1 file changed, 74 insertions(+), 76 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index ae7c2dc8d..0659b5df7 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -99,7 +99,7 @@ Use overrides when users should see and adjust the values in the Liveboard's own * Your administrator must turn on *Filtered Liveboard URLs* on the *Early Access* page of the Admin portal. The setting is Org-aware. When it is off, overrides are ignored without an error. * To use `liveboardOverride`, use Visual Embed SDK 1.54.0 or later. * Every filter or parameter you want to set must already exist as a chip on the Liveboard. Overrides never add a chip. -* To target a tab or group, xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[contextual filtering] (tab-level and group-level filters) must be turned on. When it is off, any clause that names a tab or group is ignored. +* To target a tab or group, xref:customize-liveboard-filters.adoc#contextual-liveboard-filtering[contextual filtering] (tab-level and group-level filters) must be turned on. When it is off, any override that names a tab or group is ignored. == Example Liveboard @@ -162,40 +162,36 @@ embed.render(); === liveboardOverride properties -[width="100%", cols="3,2,6"] -[options='header'] -|===== -|Property |Type |Description -|`dataSourceOverride` -|Array, required -|A list of override entries. Each entry groups the filter and parameter clauses for one model, or for all models when `dataSourceIdentifier` is omitted. +[width="100%", cols="2,5a"] +|==== +|Property |Description + +|`dataSourceOverride` __Required__ +|__Array__. A list of override entries. Each entry groups the filter and parameter overrides for one model, or for all models when `dataSourceIdentifier` is omitted. Each entry has the `dataSourceIdentifier`, `filterQuery`, and `parameterQuery` properties. -|`dataSourceOverride[].dataSourceIdentifier` -|String, optional -a|The name or GUID of a model used by the Liveboard. Names are case-insensitive. +|`dataSourceIdentifier` __Optional__ +|__String__. The name or GUID of a model used by the Liveboard. Names are case-insensitive. -* When set, the entry's clauses update only that model's chips. +* When set, the entry's overrides update only that model's chips. * When omitted or empty, they update matching chips on every model. -* If the identifier doesn't match a model on the Liveboard, every clause in the entry is ignored. +* If the identifier doesn't match a model on the Liveboard, every override in the entry is ignored. -|`dataSourceOverride[].filterQuery` -|Array, optional -a|Filter clauses. Each item has: +|`filterQuery` __Optional__ +|__Array__. Filter overrides. Each item has the following properties: -* `filterQueryToken` (string, required): one filter clause, such as `Region = West`. See <>. -* `tabName` (string, optional): the tab whose chips to update. -* `groupName` (string, optional): the group whose chips to update. +* `filterQueryToken`: __String__. Required. One filter override, such as `Region = West`. See <>. +* `tabName`: __String__. Optional. The tab whose chips to update. +* `groupName`: __String__. Optional. The group whose chips to update. -|`dataSourceOverride[].parameterQuery` -|Array, optional -a|Parameter clauses. Each item has: +|`parameterQuery` __Optional__ +|__Array__. Parameter overrides. Each item has the following properties: -* `parameterQueryToken` (string, required): one parameter clause, such as `Top N = 10`. See <>. -* `tabName` (string, optional) -* `groupName` (string, optional) -|===== +* `parameterQueryToken`: __String__. Required. One parameter override, such as `Top N = 10`. See <>. +* `tabName`: __String__. Optional. The tab whose chips to update. +* `groupName`: __String__. Optional. The group whose chips to update. +|==== -Each token holds exactly one clause. Do not join clauses with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. +Each token holds exactly one override. Do not join overrides with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. Leave out properties you don't need rather than setting them to empty strings. @@ -203,7 +199,7 @@ Leave out properties you don't need rather than setting them to empty strings. * `liveboardOverride` is the only way to pass overrides to an embedded Liveboard. Unlike runtime filters, which you can add to an embedded object's URL, adding `filter=` or `parameter=` to the URL of an embedded Liveboard has no effect. * Overrides apply when the Liveboard loads. Changing `liveboardOverride` after the Liveboard has rendered doesn't reload it. To change filter or parameter values after load, use the xref:filters_overview.adoc#_updatefilters_event[`UpdateFilters`] and `UpdateParameters` host events. -* Clauses with no token are dropped, and so are properties the SDK doesn't recognize. +* Overrides with no token are dropped, and so are properties the SDK doesn't recognize. * When a personalized view is loaded in the embedded Liveboard, for example because the user selects one, the view opens with its saved values, and the overrides aren't applied to it. [#url] @@ -212,15 +208,15 @@ Leave out properties you don't need rather than setting them to empty strings. Add the `filter` and `parameter` query parameters after the Liveboard's route, that is, after the `+#+`: ---- -https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter={filter clauses}¶meter={parameter clauses} +https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter={filter overrides}¶meter={parameter overrides} ---- * Both keys are optional, and both are singular: `filter`, not `filters`. * Put them in the query string after the route. If they come before the `+#+`, they are ignored. Legacy runtime filters work the other way: `col1`, `op1` and `val1` go before the `+#+`. * You can combine them with other Liveboard URL parameters, such as a tab (`+#/pinboard/{liveboard-id}/tab/{tab-id}?filter=...+`) or a personalized view (`+?view={view-id}&filter=...+`). -* Separate clauses with a semicolon (`;`). -* Spaces around operators are optional: `Region=West` and `Region = West` are the same clause. -* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region = West"+`. Curly quotes are not removed, and quoting individual clauses isn't supported. +* Separate overrides with a semicolon (`;`). +* Spaces around operators are optional: `Region=West` and `Region = West` are the same override. +* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region = West"+`. Curly quotes are not removed, and quoting individual overrides isn't supported. === URL examples @@ -248,10 +244,10 @@ You can type or paste these values as shown. The browser encodes spaces and othe * The value contains `&`, `+++`, `%`, `+#+` or `\`. Write them as `%26`, `%2B`, `%25`, `%23` and `%5C`. Otherwise the browser reads them as part of the URL itself. * You build the URL in code, or send it where spaces break links, such as email or chat. Use `encodeURIComponent()` on each value. For example, `+?filter=Region = West, East+` becomes `+?filter=Region%20%3D%20West%2C%20East+`. -[#filter-clauses] -== Filter clauses +[#filter-syntax] +== Filter syntax -A filter clause has this form: +A filter override has this form: ---- {Column name} {operator} {value}[, {value}...] @@ -276,7 +272,7 @@ A filter clause has this form: |`Region =` |Clears the chip, so all values are shown |===== -Not accepted on attribute columns: +Not supported on attribute columns:: * `<`, `+<=+`, `>`, `>=` (for example, `Region > West`) * `between` @@ -297,14 +293,14 @@ Values are passed as written. Type them as they appear in the data. |`Sales =` |Clears the chip |===== -Rules for measure values: +Measure value requirements:: * Comparison operators take exactly one value. * `between` takes exactly two values, separated by a space, with the smaller value first. * Decimal values (`1250.75`) and negative values (`-200`) are supported. * Thousands separators (`10,000`), currency symbols (`$100`), and percent signs are not supported. -Not accepted: +Not supported:: * `Sales > 100, 200` * `Sales = between 1000, 5000` (comma between the values) @@ -332,11 +328,11 @@ Not accepted: Periods are `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, and `year`, in singular or plural form. Abbreviations such as `wk` or `yr` are not supported. -Operators for rolling dates: +Supported operators:: -* Rolling dates accept `=`, `<`, `+<=+`, `>`, and `>=`. -* Rolling dates do not accept `!=`. -* "To date" periods accept only `=`. +* Rolling dates support `=`, `<`, `+<=+`, `>`, and `>=`. +* Rolling dates do not support `!=`. +* "To date" periods support only `=`. === Date columns: fixed dates @@ -353,15 +349,15 @@ Operators for rolling dates: |`Order Date =` |Clears the chip |===== -Rules for fixed dates: +Fixed date requirements:: * Write dates in ISO format, `yyyy-MM-dd`. A date is read as the start of that day in the ThoughtSpot cluster's time zone. * Write month names in full (`january`, not `jan`), followed by a four-digit year. -* Month, quarter, and year values accept only `=`. +* Month, quarter, and year values support only `=`. * In a `between` range, the earlier date comes first. -* Commas are not allowed in date clauses. +* Commas are not allowed in date filters. -Not accepted: +Not supported:: * `08/31/2026` or other non-ISO formats * `jan 2026` or `january` without a year @@ -371,10 +367,10 @@ Not accepted: * `day to date` * `Order Date = after last 2 months`. Write before and after as operators instead: `Order Date > last 2 months`. -[#parameter-clauses] -== Parameter clauses +[#parameter-syntax] +== Parameter syntax -A parameter clause has this form: +A parameter override has this form: ---- {Parameter name} = {value} @@ -386,12 +382,12 @@ A parameter clause has this form: [width="100%", cols="2,4,4"] [options='header'] |===== -|Data type |Example |Notes -|Integer |`Top N = 10` |Whole numbers only -|Double |`Discount Rate = 0.15` | -|String |`Target Region = West` | -|Boolean |`Include Returns = true` |Use `true` or `false` -|Date |`Forecast Start = 2026-07-01` |ISO format, `yyyy-MM-dd` +|Data type |Input |Notes +|INT |`Top N = 10` |Whole numbers only +|DOUBLE |`Discount Rate = 0.15` |Decimal values are supported +|VARCHAR |`Target Region = West` |For a parameter with a list of values, use a value or its display name +|BOOLEAN |`Include Returns = true` |Use `true` or `false` +|DATE |`Forecast Start = 2026-07-01` |ISO format, `yyyy-MM-dd` |===== The value must satisfy the parameter's own restrictions: @@ -400,7 +396,9 @@ The value must satisfy the parameter's own restrictions: * For a parameter with a range, the value must fall inside the range. * A value that doesn't meet these restrictions is ignored, and the chip keeps its current value. -Not accepted: +// + +Not supported:: * Any operator other than `=` * More than one value, such as `Top N = 5, 10` @@ -411,7 +409,7 @@ Not accepted: == Special characters in values -Use a backslash (`\`) to write a character that the syntax would otherwise read as part of the clause structure: +Use a backslash (`\`) to write a character that the syntax would otherwise read as part of the override syntax: [width="100%", cols="3,2,4"] [options='header'] @@ -419,7 +417,7 @@ Use a backslash (`\`) to write a character that the syntax would otherwise read |To include |Write |Where needed |A comma inside a value |`+\,+` |URL and SDK |`=`, `<`, `>` inside a value |`+\=+`, `+\<+`, `+\>+` |URL and SDK -|A semicolon inside a value |`+\;+` |URL only. In the SDK, each token is already one clause. +|A semicolon inside a value |`+\;+` |URL only. In the SDK, each token is already one override. |`::` inside a value |`+\::+` |URL only |===== @@ -428,14 +426,14 @@ A single colon needs no escaping. For example, `Region = sales: eu` is read as o [#scoping] == Target a model, tab, or group -When no model, tab, or group is given, a clause updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region = West` updates the Region chip on both Retail Sales and Returns. +When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region = West` updates the Region chip on both Retail Sales and Returns. -To narrow a clause, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK: +To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK: [width="100%", cols="4,3,4"] [options='header'] |===== -|URL clause |SDK equivalent |Chips updated +|URL input |SDK equivalent |Chips updated |`Region = West` |`{ filterQueryToken: 'Region = West' }` |Region chips on all models, at every level |`Retail Sales::Region = West` |`dataSourceIdentifier: 'Retail Sales'` |Region chips on the Retail Sales model only, at every level |`Regional Detail::Product Type = Shoes` |`tabName: 'Regional Detail'` |Product Type chips on the Regional Detail tab, including groups on that tab. Liveboard-level chips are not updated. @@ -450,26 +448,26 @@ How prefixes are matched in a URL: * A model can also be given by its GUID. Tabs and groups are matched by name only. * When all three prefixes are given, they are read in order: model, tab, group. * With one or two prefixes, each name is looked up as a model first, then as a tab, then as a group. So if a model and a tab share a name, the name is read as the model. To name the tab in that case, use the SDK properties. -* A clause with more than three prefixes is ignored. -* A clause whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. +* An override with more than three prefixes is ignored. +* An override whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. Parameters use the same prefixes. For example, `Retail Sales::Discount Rate = 0.15` updates the Discount Rate chip for the Retail Sales model only. -There is no prefix that targets only a Liveboard-level chip. A clause without a tab or group prefix updates all chips with a matching column name, including tab-level and group-level chips. To target only a tab or group, add its prefix. +There is no prefix that targets only a Liveboard-level chip. An override without a tab or group prefix updates all chips with a matching column name, including tab-level and group-level chips. To target only a tab or group, add its prefix. == How overrides behave === Only existing chips are updated -* A clause updates a chip only if the chip already exists on the Liveboard. If a column or parameter is used in a visualization but has no chip, the clause is ignored, and no chip is added. +* An override updates a chip only if the chip already exists on the Liveboard. If a column or parameter is used in a visualization but has no chip, the override is ignored, and no chip is added. * xref:runtime-parameters.adoc[Runtime parameter overrides] behave differently: they apply to any parameter used in the Liveboard. -* To change a linked parameter, target its primary parameter. Clauses that target a linked secondary parameter are ignored. +* To change a linked parameter, target its primary parameter. Overrides that target a linked secondary parameter are ignored. -=== Invalid clauses are skipped +=== Invalid overrides are skipped -* Each clause is applied independently. If a clause can't be applied, because of a misspelled name, an invalid value, an unknown prefix, or a missing chip, only that clause is skipped. The other clauses still apply, and the Liveboard always loads. +* Each override is applied independently. If an override can't be applied, because of a misspelled name, an invalid value, an unknown prefix, or a missing chip, only that override is skipped. The other overrides still apply, and the Liveboard always loads. * No error or warning is shown, so check the chips after the Liveboard loads to confirm which values were applied. -* Overrides can be applied differently for different users. For example, a clause on a model the user can't access is skipped for that user. +* Overrides can be applied differently for different users. For example, an override on a model the user can't access is skipped for that user. === Personalized views @@ -510,7 +508,7 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U === Security and precedence * Overrides are not a security feature. Anyone who can edit the URL can change the values or remove them. To restrict data, use xref:rls-rules.adoc[row-level security (RLS)] or the xref:abac-user-parameters.adoc[ABAC and JWT security methods]. -* Overrides can't expose data the user isn't allowed to see. RLS applies to the overridden values as it does to any filter. Clauses on columns the user can't access are skipped. +* Overrides can't expose data the user isn't allowed to see. RLS applies to the overridden values as it does to any filter. Overrides on columns the user can't access are skipped. * A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, if a JWT token pins `Discount Rate` to `0.1` and the URL sets `Discount Rate = 0.15`, the Liveboard uses `0.1`. Sources, from highest to lowest priority: .. A value pinned through ABAC with a JWT token .. A runtime parameter override (`runtimeParameters`, or `param1` and `paramVal1` in the URL) @@ -530,7 +528,7 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U * A parameter chip can't be cleared. * Overrides don't create chips, and they don't apply to columns or parameters without a chip. * Scheduled jobs and alerts don't use overrides. -* Skipped clauses aren't reported in the UI or through an embed event. +* Skipped overrides aren't reported in the UI or through an embed event. == Troubleshooting @@ -545,15 +543,15 @@ a| * The keys come after the `+#+` route. * In an embed, the overrides are in `liveboardOverride`, not in the URL. -|One clause is not applied +|One override is not applied a| * A chip exists for that column or parameter, at the scope you targeted. * The name matches the chip name in full. * The value format matches the tables above: ISO dates, one value for parameters, a value inside the parameter's list or range. * Any prefix matches a model, tab, or group name. -|A clause works for some users but not others -|The user may not have access to the model or column. Clauses on sources a user can't access are skipped for that user. +|An override works for some users but not others +|The user may not have access to the model or column. Overrides on sources a user can't access are skipped for that user. |The URL is cut off or a value is wrong |Encode `&`, `+++`, `%`, `+#+`, and `\` in values. @@ -561,11 +559,11 @@ a| |Values disappear after entering edit mode |Expected. Edit mode always shows the saved Liveboard. -|A tab or group clause is ignored +|A tab or group override is ignored |Contextual filtering must be turned on. Check the tab and group names. |===== -To check what was sent, open the browser's developer tools. On the *Network* tab, find the `LoadPinboardSession` request: its `liveboardOverride` variable shows the clauses ThoughtSpot received. +To check what was sent, open the browser's developer tools. On the *Network* tab, find the `LoadPinboardSession` request: its `liveboardOverride` variable shows the overrides ThoughtSpot received. == Related information From d3d60afb6eb44152a865f40972291498e868f71c Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Thu, 29 Oct 2026 23:42:59 +0530 Subject: [PATCH 10/48] SCAL-280404-5 --- modules/ROOT/pages/liveboard-overrides.adoc | 63 +++++++++++++++------ 1 file changed, 45 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 0659b5df7..b7a9cbbc8 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -8,7 +8,7 @@ [earlyAccess eaBackground]#Early Access# -Liveboard filter and parameter overrides set the values of a Liveboard's existing filter and parameter chips at load time. This feature requires ThoughtSpot Cloud 26.11.0.cl and Visual Embed SDK 1.54.0 or later. +Liveboard filter and parameter overrides set the values of a Liveboard's existing filter and parameter chips at load time. == Overview @@ -280,6 +280,7 @@ Not supported on attribute columns:: * An empty list item, such as `Region = West,` or `Region = West,,East` * `{null}`. Filtering on null values isn't supported. +NOTE:: Values are passed as written. Type them as they appear in the data. === Measure columns @@ -379,16 +380,25 @@ A parameter override has this form: * *Parameter name*: the parameter's name, or the label shown on its chip. It is case-insensitive. * *Value*: exactly one value, written for the parameter's data type. -[width="100%", cols="2,4,4"] -[options='header'] -|===== -|Data type |Input |Notes -|INT |`Top N = 10` |Whole numbers only -|DOUBLE |`Discount Rate = 0.15` |Decimal values are supported -|VARCHAR |`Target Region = West` |For a parameter with a list of values, use a value or its display name -|BOOLEAN |`Include Returns = true` |Use `true` or `false` -|DATE |`Forecast Start = 2026-07-01` |ISO format, `yyyy-MM-dd` -|===== +[width="100%", cols="2,5a"] +|==== +|Data type |Description + +|`INT` +|Whole numbers only. For example, `Top N = 10`. + +|`DOUBLE` +|Decimal values are supported. For example, `Discount Rate = 0.15`. + +|`VARCHAR` +|Text values. For a parameter with a list of values, use a value or its display name. For example, `Target Region = West`. + +|`BOOLEAN` +|`true` or `false`. For example, `Include Returns = true`. + +|`DATE` +|ISO format, `yyyy-MM-dd`. For example, `Forecast Start = 2026-07-01`. +|==== The value must satisfy the parameter's own restrictions: @@ -409,18 +419,35 @@ Not supported:: == Special characters in values -Use a backslash (`\`) to write a character that the syntax would otherwise read as part of the override syntax: +Some characters have a special meaning in an override. To use one of them as part of a value, put a backslash (`\`) before it. -[width="100%", cols="3,2,4"] +[width="100%", cols="2,5,4"] [options='header'] |===== -|To include |Write |Where needed -|A comma inside a value |`+\,+` |URL and SDK -|`=`, `<`, `>` inside a value |`+\=+`, `+\<+`, `+\>+` |URL and SDK -|A semicolon inside a value |`+\;+` |URL only. In the SDK, each token is already one override. -|`::` inside a value |`+\::+` |URL only +|Character |Input |Result +|Comma (`,`) +|`+Store Name = Smith\, Jones and Co+` +|One value, `Smith, Jones and Co`. Without the backslash, the comma separates two values, `Smith` and `Jones and Co`. + +|Equals sign (`=`) +|`+Product Type = Size\=XL+` +|The value `Size=XL`. Without the backslash, the second `=` is read as an operator. + +|Angle brackets (`<`, `>`) +|`+Product Type = \+` +|The value ``. Without the backslashes, `<` and `>` are read as operators. + +|Semicolon (`;`) +|`+Store Name = Mall\; North Wing+` +|The value `Mall; North Wing`. Without the backslash, the semicolon starts a new override. Needed in URLs only. + +|Double colon (`::`) +|`+Store Name = Airport\::Gate 5+` +|The value `Airport::Gate 5`. Without the backslash, `::` is read as a model, tab, or group prefix. Needed in URLs only. |===== +In the SDK, you don't need to escape `;` or `::`. Each token already holds one override, and models, tabs, and groups are set through properties. + A single colon needs no escaping. For example, `Region = sales: eu` is read as one value. [#scoping] From 653738ea2a2ac7bc8e3fc2f59cc63a3491b25234 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Fri, 30 Oct 2026 14:08:57 +0530 Subject: [PATCH 11/48] SCAL-280404-6 --- modules/ROOT/pages/liveboard-overrides.adoc | 231 +++++++++++++++++--- 1 file changed, 195 insertions(+), 36 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index b7a9cbbc8..32df1837c 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -105,28 +105,178 @@ Use overrides when users should see and adjust the values in the Liveboard's own Every example on this page uses a Liveboard named *Retail Sales Overview*, set up as follows: -* Two models: *Retail Sales* and *Returns*. Both have a *Region* column. -* Two tabs: *Summary* and *Regional Detail*. The *Regional Detail* tab has a group named *Top Stores*. -* Liveboard-level filter chips: -** *Region* on Retail Sales, and *Region* on Returns -** *Product Type* (attribute) -** *Sales* (measure) -** *Order Date* (date) -* Tab-level filter chips, on the *Regional Detail* tab: -** *Product Type* (attribute) -* Group-level filter chips, in the *Top Stores* group: -** *Store Name* (attribute) -* Parameter chips, at the Liveboard level: -** *Discount Rate*: Double, range 0 to 0.5 -** *Top N*: Integer, range 1 to 50 -** *Target Region*: String, list of West, East, Central, South -** *Forecast Start*: Date +* Two models: *Retail Sales* and *Returns*. Both have *Region* and *Store Name* columns. +* Two tabs: *Summary* and *Regional Detail*. Each tab has a group named *Top Stores*. +* The *Top Stores* group on the *Regional Detail* tab has visualizations from both models. + +The Liveboard has the following filter chips. The examples on this page refer to each chip by its number. + +[width="100%", cols="1,3,2,3,6"] +[options='header'] +|===== +|# |Chip |Type |Model |Where it is +|1 |Region |Attribute |Retail Sales |Liveboard +|2 |Region |Attribute |Returns |Liveboard +|3 |Order Date |Date |Retail Sales |Liveboard +|4 |Sales |Measure |Retail Sales |Liveboard +|5 |Product Type |Attribute |Retail Sales |Summary tab +|6 |Product Type |Attribute |Retail Sales |Regional Detail tab +|7 |Store Name |Attribute |Retail Sales |Top Stores group on the Summary tab +|8 |Store Name |Attribute |Retail Sales |Top Stores group on the Regional Detail tab +|9 |Store Name |Attribute |Returns |Top Stores group on the Regional Detail tab +|===== + +The Liveboard also has the following parameter chips, all at the Liveboard level and from the Retail Sales model: + +[width="100%", cols="3,2,5"] +[options='header'] +|===== +|Parameter |Type |Allowed values +|Discount Rate |DOUBLE |0 to 0.5 +|Top N |INT |1 to 50 +|Target Region |VARCHAR |West, East, Central, South +|Forecast Start |DATE |Any date +|===== [#embed] == Apply overrides in an embedded Liveboard Set `liveboardOverride` in the `LiveboardEmbed` configuration. The overrides apply when the Liveboard loads. +=== Step 1: Set one filter + +[source,JavaScript] +---- +const embed = new LiveboardEmbed('#embed-container', { + frameParams: { width: '100%', height: '100%' }, + liveboardId: '', + liveboardOverride: { + dataSourceOverride: [ + { + filterQuery: [ + { filterQueryToken: 'Order Date = last 30 days' }, // Chip 3 + ], + }, + ], + }, +}); +embed.render(); +---- + +Result: chip 3 shows the last 30 days. All other chips keep their saved values. + +=== Step 2: Set several filters and parameters + +Put each override in its own token: filter overrides in `filterQuery`, and parameter overrides in `parameterQuery`. + +[source,JavaScript] +---- +liveboardOverride: { + dataSourceOverride: [ + { + filterQuery: [ + { filterQueryToken: 'Order Date = this quarter' }, // Chip 3 + { filterQueryToken: 'Sales > 10000' }, // Chip 4 + ], + parameterQuery: [ + { parameterQueryToken: 'Discount Rate = 0.15' }, // Discount Rate chip + { parameterQueryToken: 'Top N = 10' }, // Top N chip + ], + }, + ], +}, +---- + +Result: chip 3 shows this quarter, chip 4 shows Sales greater than 10000, Discount Rate is 0.15, and Top N is 10. All other chips keep their saved values. + +To clear a filter chip, leave the value empty: + +[source,JavaScript] +---- +filterQuery: [ + { filterQueryToken: 'Sales =' }, // Chip 4 +], +---- + +Result: chip 4 is cleared and shows all values. + +=== Step 3: Use the same name in several places + +An override without `dataSourceIdentifier`, `tabName`, or `groupName` updates every chip with that name, on every model and at every level. + +[source,JavaScript] +---- +filterQuery: [ + { filterQueryToken: 'Region = West' }, // Chips 1, 2 + { filterQueryToken: 'Product Type = Shoes' }, // Chips 5, 6 + { filterQueryToken: 'Store Name = Downtown' }, // Chips 7, 8, 9 +], +---- + +Result: both Region chips show West, because Region is on both models. Both Product Type chips show Shoes, because Product Type is on both tabs. All three Store Name chips show Downtown, because Store Name is in both groups and on both models. + +=== Step 4: Target a model, tab, or group + +Use these properties to narrow which chips an override updates: + +* `dataSourceIdentifier`: set on the entry, so it applies to every override in the entry. Use a separate entry for each model. +* `tabName`: set on each override. A tab also covers the groups on it, but not Liveboard-level chips. +* `groupName`: set on each override. A group name matches every group with that name. Add `tabName` to pick the group on one tab. + +In this table, the numbers refer to the chips of the example Liveboard. An empty cell means the property isn't set. + +[width="100%", cols="21,18,14,29,18"] +[options='header'] +|===== +|dataSourceIdentifier |tabName |groupName |filterQueryToken |Chips updated +| | | |`Store Name = Downtown` |7, 8, 9 +|Retail Sales | | |`Region = West` |1 +|Retail Sales | | |`Store Name = Downtown` |7, 8 +| |Regional Detail | |`Product Type = Shoes` |6 +| |Regional Detail | |`Store Name = Downtown` |8, 9. The tab covers its group. +| | |Top Stores |`Store Name = Downtown` |7, 8, 9. Both groups are named Top Stores. +| |Regional Detail |Top Stores |`Store Name = Downtown` |8, 9 +|Retail Sales | |Top Stores |`Store Name = Downtown` |7, 8 +|Returns |Regional Detail | |`Store Name = Downtown` |9 +|Retail Sales |Regional Detail |Top Stores |`Store Name = Downtown` |8 +|===== + +For example, the last row in code: + +[source,JavaScript] +---- +{ + dataSourceIdentifier: 'Retail Sales', + filterQuery: [ + { + tabName: 'Regional Detail', + groupName: 'Top Stores', + filterQueryToken: 'Store Name = Downtown', // Chip 8 + }, + ], +}, +---- + +Result: only chip 8 shows Downtown. Chips 7 and 9 keep their saved values. + +=== Overrides that are skipped + +Each of these overrides is skipped: + +[width="100%", cols="21,13,14,29,23"] +[options='header'] +|===== +|dataSourceIdentifier |tabName |groupName |filterQueryToken |Why it's skipped +| |Summary | |`Region = West` |A tab doesn't cover Liveboard-level chips, and the Summary tab has no Region chip. +| |Summary |Top Stores |`Product Type = Shoes` |A group doesn't cover its tab's chips. Product Type is on the Summary tab, not in the group. +|Returns |Summary | |`Store Name = Downtown` |The Summary tab has no Store Name chip from Returns. +|Retail | | |`Region = West` |No model is named Retail. When the model doesn't match, every override in the entry is skipped. +|===== + +Only the skipped override is affected. Its chips keep their saved values, and the other overrides still apply. + +=== Step 5: Put it all together + [source,JavaScript] ---- const embed = new LiveboardEmbed('#embed-container', { @@ -135,23 +285,25 @@ const embed = new LiveboardEmbed('#embed-container', { liveboardOverride: { dataSourceOverride: [ { - // No dataSourceIdentifier: matching chips on every model are updated + // No dataSourceIdentifier: matching chips on every model filterQuery: [ - { filterQueryToken: 'Region = West, East' }, - { filterQueryToken: 'Order Date = last 30 days' }, + { filterQueryToken: 'Order Date = last 30 days' }, // Chip 3 + { tabName: 'Regional Detail', filterQueryToken: 'Product Type = Shoes' }, // Chip 6 ], parameterQuery: [ - { parameterQueryToken: 'Discount Rate = 0.15' }, + { parameterQueryToken: 'Discount Rate = 0.15' }, // Discount Rate chip ], }, { dataSourceIdentifier: 'Retail Sales', filterQuery: [ - { - tabName: 'Regional Detail', - groupName: 'Top Stores', - filterQueryToken: 'Store Name = Downtown, Airport', - }, + { filterQueryToken: 'Region = West, East' }, // Chip 1 + ], + }, + { + dataSourceIdentifier: 'Returns', + filterQuery: [ + { tabName: 'Regional Detail', filterQueryToken: 'Store Name = Downtown' }, // Chip 9 ], }, ], @@ -160,6 +312,8 @@ const embed = new LiveboardEmbed('#embed-container', { embed.render(); ---- +Result: chips 1, 3, 6, and 9, and the Discount Rate chip, are updated. Chips 2, 4, 5, 7, and 8, and the other parameter chips, keep their saved values. No two overrides target the same chip. + === liveboardOverride properties [width="100%", cols="2,5a"] @@ -231,8 +385,8 @@ Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot- |Set three filters and a parameter |`+?filter=Region = West; Order Date = this quarter; Sales > 10000¶meter=Discount Rate = 0.15+` |Update only the Retail Sales model's Region chip |`+?filter=Retail Sales::Region = West+` |Update the Product Type chip on the Regional Detail tab |`+?filter=Regional Detail::Product Type = Shoes, Jackets+` -|Update the Store Name chip in the Top Stores group |`+?filter=Regional Detail::Top Stores::Store Name = Downtown, Airport+` -|Clear the Product Type chip |`+?filter=Product Type =+` +|Update the Store Name chips in the Top Stores group on the Regional Detail tab |`+?filter=Regional Detail::Top Stores::Store Name = Downtown, Airport+` +|Clear both Product Type chips |`+?filter=Product Type =+` |Set two parameters |`+?parameter=Forecast Start = 2026-07-01; Top N = 10+` |Apply on top of a personalized view |`+?view={view-id}&filter=Region = West+` |===== @@ -455,26 +609,31 @@ A single colon needs no escaping. For example, `Region = sales: eu` is read as o When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region = West` updates the Region chip on both Retail Sales and Returns. -To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK: +To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>: [width="100%", cols="4,3,4"] [options='header'] |===== |URL input |SDK equivalent |Chips updated -|`Region = West` |`{ filterQueryToken: 'Region = West' }` |Region chips on all models, at every level -|`Retail Sales::Region = West` |`dataSourceIdentifier: 'Retail Sales'` |Region chips on the Retail Sales model only, at every level -|`Regional Detail::Product Type = Shoes` |`tabName: 'Regional Detail'` |Product Type chips on the Regional Detail tab, including groups on that tab. Liveboard-level chips are not updated. -|`Top Stores::Store Name = Downtown` |`groupName: 'Top Stores'` |Store Name chips in every group named Top Stores -|`Regional Detail::Top Stores::Store Name = Downtown` |`tabName` and `groupName` |Store Name chips in the Top Stores group on the Regional Detail tab -|`Retail Sales::Regional Detail::Top Stores::Store Name = Downtown` |All three properties |As above, for the Retail Sales model only +|`Region = West` |`{ filterQueryToken: 'Region = West' }` |Chips 1 and 2 +|`Retail Sales::Region = West` |`dataSourceIdentifier: 'Retail Sales'` |Chip 1 +|`Regional Detail::Product Type = Shoes` |`tabName: 'Regional Detail'` |Chip 6. A tab prefix also covers the groups on that tab, but not Liveboard-level chips. +|`Top Stores::Store Name = Downtown` |`groupName: 'Top Stores'` |Chips 7, 8, and 9. A group name matches every group with that name. +|`Regional Detail::Top Stores::Store Name = Downtown` |`tabName` and `groupName` |Chips 8 and 9 +|`Retail Sales::Top Stores::Store Name = Downtown` |`dataSourceIdentifier` and `groupName` |Chips 7 and 8 +|`Returns::Regional Detail::Store Name = Downtown` |`dataSourceIdentifier` and `tabName` |Chip 9 +|`Retail Sales::Regional Detail::Top Stores::Store Name = Downtown` |All three properties |Chip 8 |===== How prefixes are matched in a URL: * Names are matched against the display names of models, tabs, and groups. Matching is case-insensitive. * A model can also be given by its GUID. Tabs and groups are matched by name only. -* When all three prefixes are given, they are read in order: model, tab, group. -* With one or two prefixes, each name is looked up as a model first, then as a tab, then as a group. So if a model and a tab share a name, the name is read as the model. To name the tab in that case, use the SDK properties. +* Prefixes always go in the order model > tab > group, and you can leave any of them out: +** With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type = Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab. +** With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name = Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group. +** With three prefixes, they are read as model, tab, and group. +* Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK. * An override with more than three prefixes is ignored. * An override whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. From 209d5e878a61b872445ba63a3d5799ec0306511e Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 2 Nov 2026 07:33:18 +0530 Subject: [PATCH 12/48] version update --- src/configs/doc-configs.js | 36 ------------------------------------ 1 file changed, 36 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index de8224dd7..2943987cc 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -53,42 +53,6 @@ module.exports = { subLabel: 'Cloud (Latest)', iframeUrl: 'https://developer-docs-26-11-0-cl.vercel.app/docs/', }, - { - label: '26.10.0.cl', - link: '26.10.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-10-0-cl.vercel.app/docs/', - }, - { - label: '26.9.0.cl', - link: '26.9.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-9-0-cl.vercel.app/docs/', - }, - { - label: '26.8.0.cl', - link: '26.8.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', - }, - { - label: '26.3.0.sw', - link: '26.3.0.sw', - subLabel: 'Software (Latest)', - iframeUrl: 'https://visual-embed-sdk-26-3.vercel.app/docs/', - }, - { - label: '10.10.0.sw', - link: '10.10.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-10.vercel.app/docs/', - }, - { - label: '10.1.0.sw', - link: '10.1.0.sw', - subLabel: 'Software', - iframeUrl: 'https://visual-embed-sdk-10-1.vercel.app/docs/', - }, ], CUSTOM_PAGE_ID: { API_PLAYGROUND: 'restV2-playground', From 93355372b247614f4a4d6db78b13f49244c0d36e Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 10:35:25 +0530 Subject: [PATCH 13/48] feedback --- .../pages/customize-liveboard-filters.adoc | 2 +- modules/ROOT/pages/liveboard-overrides.adoc | 231 +++++++++--------- modules/ROOT/pages/runtime-parameters.adoc | 2 +- 3 files changed, 118 insertions(+), 117 deletions(-) diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc index 451dac905..f2b0e5c93 100644 --- a/modules/ROOT/pages/customize-liveboard-filters.adoc +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -118,7 +118,7 @@ To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and ` For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. -#To set tab-level and group-level filter and parameter values at load, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# +#To set tab-level and group-level filter and parameter values at load, use the `liveboardOverride` property. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group] in xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# [#update-filters] == Updating filters diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 32df1837c..38befd537 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -3,7 +3,7 @@ :toclevels: 2 :page-title: Liveboard filter and parameter overrides -:page-pageid: liveboard-overrides +:page-pageid: liveboard-filter-and-parameter-overrides :page-description: Set the values of a Liveboard's existing filter and parameter chips at load time, through the Liveboard URL or the liveboardOverride property of the Visual Embed SDK. [earlyAccess eaBackground]#Early Access# @@ -17,7 +17,7 @@ You can supply overrides in two ways: * In the Liveboard URL, through the `filter` and `parameter` query parameters. * In an embedded Liveboard, through the `liveboardOverride` property of the Visual Embed SDK. -The Liveboard opens with the chips already showing the values you passed, and it fetches data once, with those values applied. Users can change the chips afterward, just as they can after any other load. +The Liveboard opens with the chips already showing the values you passed, with those values applied. Users can change the chips afterward, just as they can after any other load. Use overrides for these tasks: @@ -68,7 +68,7 @@ Overrides work on the Liveboard's filter and parameter chips instead. They repla |*Rolling dates* |Yes |No -|No +|Not applicable |Yes |*Targets a model, tab, or group* @@ -90,7 +90,7 @@ Overrides work on the Liveboard's filter and parameter chips instead. They repla |Yes |===== -To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters and resets the Liveboard to its original state. +To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters on top of any already applied. Use overrides when users should see and adjust the values in the Liveboard's own chips. @@ -126,6 +126,7 @@ The Liveboard has the following filter chips. The examples on this page refer to |9 |Store Name |Attribute |Returns |Top Stores group on the Regional Detail tab |===== + The Liveboard also has the following parameter chips, all at the Liveboard level and from the Retail Sales model: [width="100%", cols="3,2,5"] @@ -154,7 +155,7 @@ const embed = new LiveboardEmbed('#embed-container', { dataSourceOverride: [ { filterQuery: [ - { filterQueryToken: 'Order Date = last 30 days' }, // Chip 3 + { filterQueryToken: 'Order Date=last 30 days' }, // Chip 3 ], }, ], @@ -175,12 +176,12 @@ liveboardOverride: { dataSourceOverride: [ { filterQuery: [ - { filterQueryToken: 'Order Date = this quarter' }, // Chip 3 - { filterQueryToken: 'Sales > 10000' }, // Chip 4 + { filterQueryToken: 'Order Date=this quarter' }, // Chip 3 + { filterQueryToken: 'Sales>10000' }, // Chip 4 ], parameterQuery: [ - { parameterQueryToken: 'Discount Rate = 0.15' }, // Discount Rate chip - { parameterQueryToken: 'Top N = 10' }, // Top N chip + { parameterQueryToken: 'Discount Rate=0.15' }, // Discount Rate chip + { parameterQueryToken: 'Top N=10' }, // Top N chip ], }, ], @@ -194,7 +195,7 @@ To clear a filter chip, leave the value empty: [source,JavaScript] ---- filterQuery: [ - { filterQueryToken: 'Sales =' }, // Chip 4 + { filterQueryToken: 'Sales=' }, // Chip 4 ], ---- @@ -207,9 +208,9 @@ An override without `dataSourceIdentifier`, `tabName`, or `groupName` updates ev [source,JavaScript] ---- filterQuery: [ - { filterQueryToken: 'Region = West' }, // Chips 1, 2 - { filterQueryToken: 'Product Type = Shoes' }, // Chips 5, 6 - { filterQueryToken: 'Store Name = Downtown' }, // Chips 7, 8, 9 + { filterQueryToken: 'Region=West' }, // Chips 1, 2 + { filterQueryToken: 'Product Type=Shoes' }, // Chips 5, 6 + { filterQueryToken: 'Store Name=Downtown' }, // Chips 7, 8, 9 ], ---- @@ -229,16 +230,16 @@ In this table, the numbers refer to the chips of the example Liveboard. An empty [options='header'] |===== |dataSourceIdentifier |tabName |groupName |filterQueryToken |Chips updated -| | | |`Store Name = Downtown` |7, 8, 9 -|Retail Sales | | |`Region = West` |1 -|Retail Sales | | |`Store Name = Downtown` |7, 8 -| |Regional Detail | |`Product Type = Shoes` |6 -| |Regional Detail | |`Store Name = Downtown` |8, 9. The tab covers its group. -| | |Top Stores |`Store Name = Downtown` |7, 8, 9. Both groups are named Top Stores. -| |Regional Detail |Top Stores |`Store Name = Downtown` |8, 9 -|Retail Sales | |Top Stores |`Store Name = Downtown` |7, 8 -|Returns |Regional Detail | |`Store Name = Downtown` |9 -|Retail Sales |Regional Detail |Top Stores |`Store Name = Downtown` |8 +| | | |`Store Name=Downtown` |7, 8, 9 +|Retail Sales | | |`Region=West` |1 +|Retail Sales | | |`Store Name=Downtown` |7, 8 +| |Regional Detail | |`Product Type=Shoes` |6 +| |Regional Detail | |`Store Name=Downtown` |8, 9. The tab covers its group. +| | |Top Stores |`Store Name=Downtown` |7, 8, 9. Both groups are named Top Stores. +| |Regional Detail |Top Stores |`Store Name=Downtown` |8, 9 +|Retail Sales | |Top Stores |`Store Name=Downtown` |7, 8 +|Returns |Regional Detail | |`Store Name=Downtown` |9 +|Retail Sales |Regional Detail |Top Stores |`Store Name=Downtown` |8 |===== For example, the last row in code: @@ -251,7 +252,7 @@ For example, the last row in code: { tabName: 'Regional Detail', groupName: 'Top Stores', - filterQueryToken: 'Store Name = Downtown', // Chip 8 + filterQueryToken: 'Store Name=Downtown', // Chip 8 }, ], }, @@ -267,10 +268,10 @@ Each of these overrides is skipped: [options='header'] |===== |dataSourceIdentifier |tabName |groupName |filterQueryToken |Why it's skipped -| |Summary | |`Region = West` |A tab doesn't cover Liveboard-level chips, and the Summary tab has no Region chip. -| |Summary |Top Stores |`Product Type = Shoes` |A group doesn't cover its tab's chips. Product Type is on the Summary tab, not in the group. -|Returns |Summary | |`Store Name = Downtown` |The Summary tab has no Store Name chip from Returns. -|Retail | | |`Region = West` |No model is named Retail. When the model doesn't match, every override in the entry is skipped. +| |Summary | |`Region=West` |A tab doesn't cover Liveboard-level chips, and the Summary tab has no Region chip. +| |Summary |Top Stores |`Product Type=Shoes` |A group doesn't cover its tab's chips. Product Type is on the Summary tab, not in the group. +|Returns |Summary | |`Store Name=Downtown` |The Summary tab has no Store Name chip from Returns. +|Retail | | |`Region=West` |No model is named Retail. When the model doesn't match, every override in the entry is skipped. |===== Only the skipped override is affected. Its chips keep their saved values, and the other overrides still apply. @@ -287,23 +288,23 @@ const embed = new LiveboardEmbed('#embed-container', { { // No dataSourceIdentifier: matching chips on every model filterQuery: [ - { filterQueryToken: 'Order Date = last 30 days' }, // Chip 3 - { tabName: 'Regional Detail', filterQueryToken: 'Product Type = Shoes' }, // Chip 6 + { filterQueryToken: 'Order Date=last 30 days' }, // Chip 3 + { tabName: 'Regional Detail', filterQueryToken: 'Product Type=Shoes' }, // Chip 6 ], parameterQuery: [ - { parameterQueryToken: 'Discount Rate = 0.15' }, // Discount Rate chip + { parameterQueryToken: 'Discount Rate=0.15' }, // Discount Rate chip ], }, { dataSourceIdentifier: 'Retail Sales', filterQuery: [ - { filterQueryToken: 'Region = West, East' }, // Chip 1 + { filterQueryToken: 'Region=West, East' }, // Chip 1 ], }, { dataSourceIdentifier: 'Returns', filterQuery: [ - { tabName: 'Regional Detail', filterQueryToken: 'Store Name = Downtown' }, // Chip 9 + { tabName: 'Regional Detail', filterQueryToken: 'Store Name=Downtown' }, // Chip 9 ], }, ], @@ -333,14 +334,14 @@ Result: chips 1, 3, 6, and 9, and the Discount Rate chip, are updated. Chips 2, |`filterQuery` __Optional__ |__Array__. Filter overrides. Each item has the following properties: -* `filterQueryToken`: __String__. Required. One filter override, such as `Region = West`. See <>. +* `filterQueryToken`: __String__. Required. One filter override, such as `Region=West`. See <>. * `tabName`: __String__. Optional. The tab whose chips to update. * `groupName`: __String__. Optional. The group whose chips to update. |`parameterQuery` __Optional__ |__Array__. Parameter overrides. Each item has the following properties: -* `parameterQueryToken`: __String__. Required. One parameter override, such as `Top N = 10`. See <>. +* `parameterQueryToken`: __String__. Required. One parameter override, such as `Top N=10`. See <>. * `tabName`: __String__. Optional. The tab whose chips to update. * `groupName`: __String__. Optional. The group whose chips to update. |==== @@ -362,7 +363,7 @@ Leave out properties you don't need rather than setting them to empty strings. Add the `filter` and `parameter` query parameters after the Liveboard's route, that is, after the `+#+`: ---- -https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter={filter overrides}¶meter={parameter overrides} +https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter overrides}¶meter={parameter overrides} ---- * Both keys are optional, and both are singular: `filter`, not `filters`. @@ -370,25 +371,25 @@ https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter={filter overrides}& * You can combine them with other Liveboard URL parameters, such as a tab (`+#/pinboard/{liveboard-id}/tab/{tab-id}?filter=...+`) or a personalized view (`+?view={view-id}&filter=...+`). * Separate overrides with a semicolon (`;`). * Spaces around operators are optional: `Region=West` and `Region = West` are the same override. -* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region = West"+`. Curly quotes are not removed, and quoting individual overrides isn't supported. +* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region=West"+`. Curly quotes are not removed, and quoting individual overrides isn't supported. === URL examples -Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/liveboard/{liveboard-id}?filter=Region = West, East+`. +Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region=West, East+`. [width="100%", cols="3,5"] [options='header'] |===== |Goal |Add to the URL -|Show the West and East regions |`+?filter=Region = West, East+` -|Show the last 30 days |`+?filter=Order Date = last 30 days+` -|Set three filters and a parameter |`+?filter=Region = West; Order Date = this quarter; Sales > 10000¶meter=Discount Rate = 0.15+` -|Update only the Retail Sales model's Region chip |`+?filter=Retail Sales::Region = West+` -|Update the Product Type chip on the Regional Detail tab |`+?filter=Regional Detail::Product Type = Shoes, Jackets+` -|Update the Store Name chips in the Top Stores group on the Regional Detail tab |`+?filter=Regional Detail::Top Stores::Store Name = Downtown, Airport+` -|Clear both Product Type chips |`+?filter=Product Type =+` -|Set two parameters |`+?parameter=Forecast Start = 2026-07-01; Top N = 10+` -|Apply on top of a personalized view |`+?view={view-id}&filter=Region = West+` +|Show the West and East regions |`+?filter=Region=West, East+` +|Show the last 30 days |`+?filter=Order Date=last 30 days+` +|Set three filters and a parameter |`+?filter=Region=West; Order Date=this quarter; Sales>10000¶meter=Discount Rate=0.15+` +|Update only the Retail Sales model's Region chip |`+?filter=Retail Sales::Region=West+` +|Update the Product Type chip on the Regional Detail tab |`+?filter=Regional Detail::Product Type=Shoes, Jackets+` +|Update the Store Name chips in the Top Stores group on the Regional Detail tab |`+?filter=Regional Detail::Top Stores::Store Name=Downtown, Airport+` +|Clear both Product Type chips |`+?filter=Product Type=+` +|Set two parameters |`+?parameter=Forecast Start=2026-07-01; Top N=10+` +|Apply on top of a personalized view |`+?view={view-id}&filter=Region=West+` |===== === Encoding @@ -396,7 +397,7 @@ Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot- You can type or paste these values as shown. The browser encodes spaces and other characters when it opens the URL. Encode a value yourself only in these cases: * The value contains `&`, `+++`, `%`, `+#+` or `\`. Write them as `%26`, `%2B`, `%25`, `%23` and `%5C`. Otherwise the browser reads them as part of the URL itself. -* You build the URL in code, or send it where spaces break links, such as email or chat. Use `encodeURIComponent()` on each value. For example, `+?filter=Region = West, East+` becomes `+?filter=Region%20%3D%20West%2C%20East+`. +* You build the URL in code, or send it where spaces break links, such as email or chat. Use `encodeURIComponent()` on each value. For example, `+?filter=Region=West, East+` becomes `+?filter=Region%3DWest%2C%20East+`. [#filter-syntax] == Filter syntax @@ -404,12 +405,12 @@ You can type or paste these values as shown. The browser encodes spaces and othe A filter override has this form: ---- -{Column name} {operator} {value}[, {value}...] +{Column name}{operator}{value}[, {value}...] ---- -* *Column name*: the name shown on the filter chip. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. +* *Column name*: the name of the filter. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. * *Operators*: `=`, `!=`, `<`, `+<=+`, `>`, `>=`. Which operators you can use depends on the column type, as shown in the tables below. -* *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name = New York Downtown, San Francisco Bay` is a list of two values. +* *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name=New York Downtown, San Francisco Bay` is a list of two values. * *Keywords*: keywords such as `between`, `last` and `today` are case-insensitive. === Attribute columns @@ -418,20 +419,20 @@ A filter override has this form: [options='header'] |===== |Input |Result -|`Region = West` |Region is West -|`Region = West, East, Central` |Region is any of West, East, Central -|`Region != South` |Region is not South -|`Region != South, Central` |Region is none of South, Central -|`+Store Name = Smith\, Jones and Co+` |One value that contains a comma -|`Region =` |Clears the chip, so all values are shown +|`Region=West` |Region is West +|`Region=West, East, Central` |Region is any of West, East, Central +|`Region!=South` |Region is not South +|`Region!=South, Central` |Region is none of South, Central +|`+Store Name=Smith\, Jones and Co+` |One value that contains a comma +|`Region=` |Clears the chip, so all values are shown |===== Not supported on attribute columns:: -* `<`, `+<=+`, `>`, `>=` (for example, `Region > West`) +* `<`, `+<=+`, `>`, `>=` (for example, `Region>West`) * `between` * Contains, begins with, or ends with matching -* An empty list item, such as `Region = West,` or `Region = West,,East` +* An empty list item, such as `Region=West,` or `Region=West,,East` * `{null}`. Filtering on null values isn't supported. NOTE:: @@ -443,9 +444,9 @@ Values are passed as written. Type them as they appear in the data. [options='header'] |===== |Input |Result -|`Sales > 10000` |Greater than 10000. `>=`, `<` and `+<=+` work the same way. -|`Sales = between 1000 5000` |Between 1000 and 5000, inclusive -|`Sales =` |Clears the chip +|`Sales>10000` |Greater than 10000. `>=`, `<` and `+<=+` work the same way. +|`Sales=between 1000 5000` |Between 1000 and 5000, inclusive +|`Sales=` |Clears the chip |===== Measure value requirements:: @@ -457,10 +458,10 @@ Measure value requirements:: Not supported:: -* `Sales > 100, 200` -* `Sales = between 1000, 5000` (comma between the values) -* `Sales = between 5000 1000` (larger value first) -* `Sales != between 1000 5000` (measures have no "not between") +* `Sales>100, 200` +* `Sales=between 1000, 5000` (comma between the values) +* `Sales=between 5000 1000` (larger value first) +* `Sales!=between 1000 5000` (measures have no "not between") === Date columns: rolling dates @@ -468,17 +469,17 @@ Not supported:: [options='header'] |===== |Input |Result -|`Order Date = today` |Today. `yesterday` and `tomorrow` also work. -|`Order Date = this quarter` |The current quarter -|`Order Date = last 30 days` |The last 30 days -|`Order Date = last quarter` |The last quarter (same as `last 1 quarter`) -|`Order Date = last 24 hours` |The last 24 hours. Periods can be as short as `second`, `minute` and `hour`. -|`Order Date = next 2 weeks` |The next 2 weeks -|`Order Date = next quarter` |The next quarter (same as `next 1 quarter`) -|`Order Date = year to date` |Year to date. `week`, `month`, and `quarter to date` also work. -|`Order Date > last 2 months` |After the last 2 months -|`+Order Date <= this month+` |On or before this month -|`Order Date < today` |Before today. The before/after operators also work with `today`, `yesterday` and `tomorrow`. +|`Order Date=today` |Today. `yesterday` and `tomorrow` also work. +|`Order Date=this quarter` |The current quarter +|`Order Date=last 30 days` |The last 30 days +|`Order Date=last quarter` |The last quarter (same as `last 1 quarter`) +|`Order Date=last 24 hours` |The last 24 hours. Periods can be as short as `second`, `minute` and `hour`. +|`Order Date=next 2 weeks` |The next 2 weeks +|`Order Date=next quarter` |The next quarter (same as `next 1 quarter`) +|`Order Date=year to date` |Year to date. `week`, `month`, and `quarter to date` also work. +|`Order Date>last 2 months` |After the last 2 months +|`+Order Date<=this month+` |On or before this month +|`Order Date`, and `>=` also work. -|`Order Date = between 2026-01-01 2026-06-30` |Between the two dates, inclusive -|`Order Date != between 2026-01-01 2026-06-30` |Not between the two dates -|`Order Date = january 2026` |The whole month -|`Order Date = q1 2026` |The whole quarter (`q1` to `q4`) -|`Order Date = 2026` |The whole year -|`Order Date =` |Clears the chip +|`Order Date=2026-08-31` |On that day. `!=`, `<`, `+<=+`, `>`, and `>=` also work. +|`Order Date=between 2026-01-01 2026-06-30` |Between the two dates, inclusive +|`Order Date!=between 2026-01-01 2026-06-30` |Not between the two dates +|`Order Date=january 2026` |The whole month +|`Order Date=q1 2026` |The whole quarter (`q1` to `q4`) +|`Order Date=2026` |The whole year +|`Order Date=` |Clears the chip |===== Fixed date requirements:: @@ -520,7 +521,7 @@ Not supported:: * Date and time values, such as `2026-08-31 10:00` * Free-form phrases, such as `start of week`, `3 days ago`, `now`, or `last 7 days inclusive` * `day to date` -* `Order Date = after last 2 months`. Write before and after as operators instead: `Order Date > last 2 months`. +* `Order Date=after last 2 months`. Write before and after as operators instead: `Order Date>last 2 months`. [#parameter-syntax] == Parameter syntax @@ -528,10 +529,10 @@ Not supported:: A parameter override has this form: ---- -{Parameter name} = {value} +{Parameter name}={value} ---- -* *Parameter name*: the parameter's name, or the label shown on its chip. It is case-insensitive. +* *Parameter name*: the parameter's name. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. * *Value*: exactly one value, written for the parameter's data type. [width="100%", cols="2,5a"] @@ -539,19 +540,19 @@ A parameter override has this form: |Data type |Description |`INT` -|Whole numbers only. For example, `Top N = 10`. +|Whole numbers only. For example, `Top N=10`. |`DOUBLE` -|Decimal values are supported. For example, `Discount Rate = 0.15`. +|Decimal values are supported. For example, `Discount Rate=0.15`. |`VARCHAR` -|Text values. For a parameter with a list of values, use a value or its display name. For example, `Target Region = West`. +|Text values. For a parameter with a list of values, use a value or its display name. For example, `Target Region=West`. |`BOOLEAN` -|`true` or `false`. For example, `Include Returns = true`. +|`true` or `false`. For example, `Include Returns=true`. |`DATE` -|ISO format, `yyyy-MM-dd`. For example, `Forecast Start = 2026-07-01`. +|ISO format, `yyyy-MM-dd`. For example, `Forecast Start=2026-07-01`. |==== The value must satisfy the parameter's own restrictions: @@ -565,10 +566,10 @@ The value must satisfy the parameter's own restrictions: Not supported:: * Any operator other than `=` -* More than one value, such as `Top N = 5, 10` -* An empty value (`Top N =`). Parameter chips can't be cleared. +* More than one value, such as `Top N=5, 10` +* An empty value (`Top N=`). Parameter chips can't be cleared. * `{null}` -* Dynamic date values, such as `Forecast Start = today` or `last 7 days` +* Dynamic date values, such as `Forecast Start=today` or `last 7 days` * Date-time and time parameters == Special characters in values @@ -580,34 +581,34 @@ Some characters have a special meaning in an override. To use one of them as par |===== |Character |Input |Result |Comma (`,`) -|`+Store Name = Smith\, Jones and Co+` +|`+Store Name=Smith\, Jones and Co+` |One value, `Smith, Jones and Co`. Without the backslash, the comma separates two values, `Smith` and `Jones and Co`. |Equals sign (`=`) -|`+Product Type = Size\=XL+` +|`+Product Type=Size\=XL+` |The value `Size=XL`. Without the backslash, the second `=` is read as an operator. |Angle brackets (`<`, `>`) -|`+Product Type = \+` +|`+Product Type=\+` |The value ``. Without the backslashes, `<` and `>` are read as operators. |Semicolon (`;`) -|`+Store Name = Mall\; North Wing+` +|`+Store Name=Mall\; North Wing+` |The value `Mall; North Wing`. Without the backslash, the semicolon starts a new override. Needed in URLs only. |Double colon (`::`) -|`+Store Name = Airport\::Gate 5+` +|`+Store Name=Airport\::Gate 5+` |The value `Airport::Gate 5`. Without the backslash, `::` is read as a model, tab, or group prefix. Needed in URLs only. |===== In the SDK, you don't need to escape `;` or `::`. Each token already holds one override, and models, tabs, and groups are set through properties. -A single colon needs no escaping. For example, `Region = sales: eu` is read as one value. +A single colon needs no escaping. For example, `Region=sales: eu` is read as one value. [#scoping] == Target a model, tab, or group -When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region = West` updates the Region chip on both Retail Sales and Returns. +When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region=West` updates the Region chip on both Retail Sales and Returns. To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>: @@ -615,14 +616,14 @@ To narrow an override, prefix it with names separated by `::` in a URL, or set ` [options='header'] |===== |URL input |SDK equivalent |Chips updated -|`Region = West` |`{ filterQueryToken: 'Region = West' }` |Chips 1 and 2 -|`Retail Sales::Region = West` |`dataSourceIdentifier: 'Retail Sales'` |Chip 1 -|`Regional Detail::Product Type = Shoes` |`tabName: 'Regional Detail'` |Chip 6. A tab prefix also covers the groups on that tab, but not Liveboard-level chips. -|`Top Stores::Store Name = Downtown` |`groupName: 'Top Stores'` |Chips 7, 8, and 9. A group name matches every group with that name. -|`Regional Detail::Top Stores::Store Name = Downtown` |`tabName` and `groupName` |Chips 8 and 9 -|`Retail Sales::Top Stores::Store Name = Downtown` |`dataSourceIdentifier` and `groupName` |Chips 7 and 8 -|`Returns::Regional Detail::Store Name = Downtown` |`dataSourceIdentifier` and `tabName` |Chip 9 -|`Retail Sales::Regional Detail::Top Stores::Store Name = Downtown` |All three properties |Chip 8 +|`Region=West` |`{ filterQueryToken: 'Region=West' }` |Chips 1 and 2 +|`Retail Sales::Region=West` |`dataSourceIdentifier: 'Retail Sales'` |Chip 1 +|`Regional Detail::Product Type=Shoes` |`tabName: 'Regional Detail'` |Chip 6. A tab prefix also covers the groups on that tab, but not Liveboard-level chips. +|`Top Stores::Store Name=Downtown` |`groupName: 'Top Stores'` |Chips 7, 8, and 9. A group name matches every group with that name. +|`Regional Detail::Top Stores::Store Name=Downtown` |`tabName` and `groupName` |Chips 8 and 9 +|`Retail Sales::Top Stores::Store Name=Downtown` |`dataSourceIdentifier` and `groupName` |Chips 7 and 8 +|`Returns::Regional Detail::Store Name=Downtown` |`dataSourceIdentifier` and `tabName` |Chip 9 +|`Retail Sales::Regional Detail::Top Stores::Store Name=Downtown` |All three properties |Chip 8 |===== How prefixes are matched in a URL: @@ -630,14 +631,14 @@ How prefixes are matched in a URL: * Names are matched against the display names of models, tabs, and groups. Matching is case-insensitive. * A model can also be given by its GUID. Tabs and groups are matched by name only. * Prefixes always go in the order model > tab > group, and you can leave any of them out: -** With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type = Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab. -** With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name = Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group. +** With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type=Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab. +** With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name=Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group. ** With three prefixes, they are read as model, tab, and group. * Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK. * An override with more than three prefixes is ignored. * An override whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. -Parameters use the same prefixes. For example, `Retail Sales::Discount Rate = 0.15` updates the Discount Rate chip for the Retail Sales model only. +Parameters use the same prefixes. For example, `Retail Sales::Discount Rate=0.15` updates the Discount Rate chip for the Retail Sales model only. There is no prefix that targets only a Liveboard-level chip. An override without a tab or group prefix updates all chips with a matching column name, including tab-level and group-level chips. To target only a tab or group, add its prefix. @@ -695,7 +696,7 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U * Overrides are not a security feature. Anyone who can edit the URL can change the values or remove them. To restrict data, use xref:rls-rules.adoc[row-level security (RLS)] or the xref:abac-user-parameters.adoc[ABAC and JWT security methods]. * Overrides can't expose data the user isn't allowed to see. RLS applies to the overridden values as it does to any filter. Overrides on columns the user can't access are skipped. -* A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, if a JWT token pins `Discount Rate` to `0.1` and the URL sets `Discount Rate = 0.15`, the Liveboard uses `0.1`. Sources, from highest to lowest priority: +* A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, if a JWT token pins `Discount Rate` to `0.1` and the URL sets `Discount Rate=0.15`, the Liveboard uses `0.1`. Sources, from highest to lowest priority: .. A value pinned through ABAC with a JWT token .. A runtime parameter override (`runtimeParameters`, or `param1` and `paramVal1` in the URL) .. A Liveboard parameter override @@ -732,7 +733,7 @@ a| |One override is not applied a| * A chip exists for that column or parameter, at the scope you targeted. -* The name matches the chip name in full. +* The name matches the filter or parameter name in full. * The value format matches the tables above: ISO dates, one value for parameters, a value inside the parameter's list or range. * Any prefix matches a model, tab, or group name. diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index e188c4030..939df608c 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -30,7 +30,7 @@ When applied, runtime parameters override the default or saved Parameter values [NOTE] ==== -#Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +#Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Liveboard overrides can also target a parameter chip on a specific tab or group, which runtime parameter overrides can't. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# ==== === Supported data types From 25fff7180c830c1ee823d600ab2cc65716364f32 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 2 Nov 2026 10:54:18 +0530 Subject: [PATCH 14/48] rate limit update --- modules/ROOT/pages/spottercode.adoc | 30 +++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/modules/ROOT/pages/spottercode.adoc b/modules/ROOT/pages/spottercode.adoc index f432c1ffa..b2e5d384b 100644 --- a/modules/ROOT/pages/spottercode.adoc +++ b/modules/ROOT/pages/spottercode.adoc @@ -138,6 +138,36 @@ Use `/mcp/docs` (unauthenticated) if:: The IDE configuration steps in this guide use the authenticated `/mcp` endpoint by default. If you want to use the unauthenticated `/mcp/docs` endpoint instead, replace the endpoint URL in the relevant configuration snippet before saving. All other configuration steps remain the same. ==== +[#spottercode-rate-limits] +== Rate limits +The SpotterCode MCP endpoint (`/mcp`) limits how many requests it accepts from a single IP address. + +[options="header", cols="1,3"] +|==== +| Setting | Value + +| Request limit +| 120 requests per minute for each IP address + +| Block duration +| 10 minutes after the limit is exceeded +|==== + +When you exceed the limit, requests to the endpoint are blocked for 10 minutes. You may see a an `HTTP 429` response, or a connection timeout. Some MCP clients don't display the error page, so a blocked connection may appear as a timeout instead. + +[NOTE] +==== +Rate limits are counted for each IP address, not for each user. If your organization connects through a shared VPN, proxy, or NAT gateway, all users behind that address share the same allowance. +==== + +To avoid reaching the limit: + +* Break large tasks into smaller, sequential prompts instead of running many requests in parallel. +* Don't run several automated agent workflows from the same network at the same time. +* If you are blocked, wait 10 minutes and try again. + +If you want to change the default rate limit for your organization, contact ThoughtSpot Support. + [#_security_and_data_governance] == Security and data governance SpotterCode is designed to operate within ThoughtSpot's existing security and governance model. The following table shows what data SpotterCode sends to its hosted MCP server and how your ThoughtSpot access controls apply across all SpotterCode surfaces. From 3a62fa2b7bbbcf295fc2affb2dde14e09ee861b5 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 11:18:10 +0530 Subject: [PATCH 15/48] feedback-1 --- .../pages/customize-liveboard-filters.adoc | 4 +-- modules/ROOT/pages/liveboard-overrides.adoc | 26 +++++++++---------- modules/ROOT/pages/runtime-parameters.adoc | 6 ++--- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc index f2b0e5c93..223a38c3e 100644 --- a/modules/ROOT/pages/customize-liveboard-filters.adoc +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -52,9 +52,9 @@ The `showMaskedFilterChip` property is also available in full application embedd [#filters-at-load] == Apply filters at load time -#To open an embedded Liveboard with specific filter and parameter values, set `liveboardOverride`. The values appear in the Liveboard's filter and parameter chips. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To change values after load, use `HostEvent.UpdateFilters`.# +To open an embedded Liveboard with specific filter and parameter values, set `liveboardOverride`. The values appear in the Liveboard's filter and parameter chips. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To change values after load, use `HostEvent.UpdateFilters`. -#To add a filter condition that doesn't appear in the chips, use xref:runtime-filters.adoc[runtime filters] instead.# +To add a filter condition that doesn't appear in the chips, use xref:runtime-filters.adoc[runtime filters] instead. [IMPORTANT] ==== diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 38befd537..7fd3f3d76 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -17,7 +17,7 @@ You can supply overrides in two ways: * In the Liveboard URL, through the `filter` and `parameter` query parameters. * In an embedded Liveboard, through the `liveboardOverride` property of the Visual Embed SDK. -The Liveboard opens with the chips already showing the values you passed, with those values applied. Users can change the chips afterward, just as they can after any other load. +#The Liveboard opens with the chips already showing the values you passed, with those values applied. Users can change the chips afterward, just as they can after any other load.# Use overrides for these tasks: @@ -90,7 +90,7 @@ Overrides work on the Liveboard's filter and parameter chips instead. They repla |Yes |===== -To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters on top of any already applied. +#To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters on top of any already applied.# Use overrides when users should see and adjust the values in the Liveboard's own chips. @@ -260,7 +260,7 @@ For example, the last row in code: Result: only chip 8 shows Downtown. Chips 7 and 9 keep their saved values. -=== Overrides that are skipped +==== Overrides that are skipped Each of these overrides is skipped: @@ -375,7 +375,7 @@ https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter overrides}&p === URL examples -Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region=West, East+`. +#Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region=West, East+`.# [width="100%", cols="3,5"] [options='header'] @@ -408,7 +408,7 @@ A filter override has this form: {Column name}{operator}{value}[, {value}...] ---- -* *Column name*: the name of the filter. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. +* #*Column name*: the name of the filter. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes.# * *Operators*: `=`, `!=`, `<`, `+<=+`, `>`, `>=`. Which operators you can use depends on the column type, as shown in the tables below. * *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name=New York Downtown, San Francisco Bay` is a list of two values. * *Keywords*: keywords such as `between`, `last` and `today` are case-insensitive. @@ -532,7 +532,7 @@ A parameter override has this form: {Parameter name}={value} ---- -* *Parameter name*: the parameter's name. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. +* #*Parameter name*: the parameter's name. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes.# * *Value*: exactly one value, written for the parameter's data type. [width="100%", cols="2,5a"] @@ -610,7 +610,7 @@ A single colon needs no escaping. For example, `Region=sales: eu` is read as one When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region=West` updates the Region chip on both Retail Sales and Returns. -To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>: +#To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>:# [width="100%", cols="4,3,4"] [options='header'] @@ -630,11 +630,11 @@ How prefixes are matched in a URL: * Names are matched against the display names of models, tabs, and groups. Matching is case-insensitive. * A model can also be given by its GUID. Tabs and groups are matched by name only. -* Prefixes always go in the order model > tab > group, and you can leave any of them out: -** With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type=Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab. -** With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name=Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group. -** With three prefixes, they are read as model, tab, and group. -* Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK. +* #Prefixes always go in the order model > tab > group, and you can leave any of them out:# +** #With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type=Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab.# +** #With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name=Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group.# +** #With three prefixes, they are read as model, tab, and group.# +* #Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK.# * An override with more than three prefixes is ignored. * An override whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. @@ -733,7 +733,7 @@ a| |One override is not applied a| * A chip exists for that column or parameter, at the scope you targeted. -* The name matches the filter or parameter name in full. +* #The name matches the filter or parameter name in full.# * The value format matches the tables above: ISO dates, one value for parameters, a value inside the parameter's list or range. * Any prefix matches a model, tab, or group name. diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 939df608c..9934f5b19 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -30,7 +30,7 @@ When applied, runtime parameters override the default or saved Parameter values [NOTE] ==== -#Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Liveboard overrides can also target a parameter chip on a specific tab or group, which runtime parameter overrides can't. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# +Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. #Liveboard overrides can also target a parameter chip on a specific tab or group, which runtime parameter overrides can't. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# ==== === Supported data types @@ -389,7 +389,7 @@ For example, if you want to override the value of the inflation Parameter on a L [NOTE] ==== -#The `param1` and `paramVal1` keys go before the `+#+` and hide the parameter chip. The `parameter` key that comes after the `+#+` in a Liveboard URL is a different feature, which sets the value of a visible parameter chip. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides].# +The `param1` and `paramVal1` keys go before the `+#+` and hide the parameter chip. The `parameter` key that comes after the `+#+` in a Liveboard URL is a different feature, which sets the value of a visible parameter chip. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides]. ==== .Liveboard @@ -416,7 +416,7 @@ ThoughtSpot returns an error if an object URL with Parameter attributes exceeds Parameters work differently when used in JWT tokens to secure values for users. Setting a Parameter value via a JWT token will not hide the Parameter value by default. It lets you display a placeholder value on the Parameter chip, for example “Secured”, to indicate that the Parameter is used for security purposes. Note that the placeholder Parameter value is the default value set in your Parameter. Business users will see this value on the Parameter chip. However, the value of the parameter being used in the data displayed will be the one passed via the JWT token. -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. #JWT-pinned values also take precedence over xref:liveboard-overrides.adoc#precedence[Liveboard filter and parameter overrides].# +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. JWT-pinned values also take precedence over xref:liveboard-overrides.adoc#precedence[Liveboard filter and parameter overrides]. 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: From 13377fc3a1246088f0137e268a502d244611ae04 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 11:34:01 +0530 Subject: [PATCH 16/48] feedback-2 --- modules/ROOT/pages/common/nav-embedding.adoc | 2 +- modules/ROOT/pages/common/nav-in-product-help.adoc | 2 +- modules/ROOT/pages/embed-pinboard.adoc | 4 ++-- modules/ROOT/pages/filters_overview.adoc | 1 + modules/ROOT/pages/runtime-filters.adoc | 4 ++-- modules/ROOT/pages/runtime-overrides.adoc | 6 +++--- 6 files changed, 10 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index 65b51b4dc..ab410c90c 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -96,7 +96,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] -** link:{{navprefix}}/liveboard-overrides[#Liveboard filter and parameter overrides#] +** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[#Liveboard filter and parameter overrides#] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index c26a27d33..b61ee048c 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -112,7 +112,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] -** link:{{navprefix}}/liveboard-overrides[#Liveboard filter and parameter overrides#] +** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[#Liveboard filter and parameter overrides#] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/embed-pinboard.adoc b/modules/ROOT/pages/embed-pinboard.adoc index e901c3380..17359dd9e 100644 --- a/modules/ROOT/pages/embed-pinboard.adoc +++ b/modules/ROOT/pages/embed-pinboard.adoc @@ -115,8 +115,8 @@ The customization options are grouped into the following pages: |Header visibility and compact header, tabs, visible tabs and visualizations, tile gutter, Note tiles, responsive breakpoints and 12-column layout, and grouping and styling. |xref:customize-liveboard-filters.adoc[Customize Liveboard filters] |Filter chip visibility, masked filter chips, filters at load time, contextual filtering at the Liveboard, tab, and group levels, and updating filters with host events. -|#xref:liveboard-overrides.adoc[Set filter and parameter values at load]# -|#Values of existing filter and parameter chips at load, through `liveboardOverride` or the Liveboard URL, with targeting by model, tab, or group.# +|xref:liveboard-overrides.adoc[Set filter and parameter values at load] +|Values of existing filter and parameter chips at load, through `liveboardOverride` or the Liveboard URL, with targeting by model, tab, or group. |xref:liveboard-data-downloads.adoc[Customize data refresh and download options] |Browser data cache and refresh, PDF, XLSX, and CSV downloads, download action IDs and host events, and scheduled exports. |==== diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index c1ef71f8d..2b7f7c64a 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -208,6 +208,7 @@ liveboardEmbed.trigger(HostEvent.OpenFilter, { columnId: ''}) ---- +[#_updatefilters_event] === UpdateFilters event The link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updatefilters[HostEvent.UpdateFilters] directly updates the values of an existing filter currently applied on a Liveboard: diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 787b8a0f7..48dd63160 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -30,7 +30,7 @@ Pass filter properties as query parameters in the URL. [NOTE] ==== -#Runtime filters add a hidden filter condition on a model column. To set the values shown in a Liveboard's filter chips instead, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. For a side-by-side comparison, see xref:liveboard-overrides.adoc#comparison[How overrides differ from runtime filters and runtime parameters].# +Runtime filters add a hidden filter condition on a model column. To set the values shown in a Liveboard's filter chips instead, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. For a side-by-side comparison, see xref:liveboard-overrides.adoc#comparison[How overrides differ from runtime filters and runtime parameters]. ==== === Runtime filter properties @@ -736,7 +736,7 @@ The following example passes multiple variables to a single column as well as mu [NOTE] ==== -#Runtime filter keys such as `col1`, `op1`, and `val1` go before the `+#+` in the URL. To set the values of a Liveboard's filter chips through the URL, use the `filter` and `parameter` keys after the `+#+` instead. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides].# +Runtime filter keys such as `col1`, `op1`, and `val1` go before the `+#+` in the URL. To set the values of a Liveboard's filter chips through the URL, use the `filter` and `parameter` keys after the `+#+` instead. For more information, see xref:liveboard-overrides.adoc#url[Liveboard filter and parameter overrides]. ==== The following examples show the runtime filter query string in a Liveboard URL: diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index eb4f4a6c1..d1982b2ea 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -40,9 +40,9 @@ Like runtime filters, xref:runtime-parameters.adoc[Parameters] can be applied on * xref:SearchViewConfig.adoc[SearchEmbed] * xref:AppViewConfig.adoc[AppEmbed] -#After the object loads, Parameter values can be xref:runtime-parameters.adoc#_adjust_parameter_values_using_a_host_event[adjusted using the SDK events].# +After the object loads, Parameter values can be xref:runtime-parameters.adoc#_adjust_parameter_values_using_a_host_event[adjusted using the SDK events]. -== #Liveboard filter and parameter overrides# [earlyAccess eaBackground]#Early Access# -#xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides] set the values of a Liveboard's existing filter and parameter chips when it loads, through the Liveboard URL or the `liveboardOverride` SDK property. Unlike runtime filters, the chips show the values. See xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +== Liveboard filter and parameter overrides [earlyAccess eaBackground]#Early Access# +xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides] set the values of a Liveboard's existing filter and parameter chips when it loads, through the Liveboard URL or the `liveboardOverride` SDK property. Unlike runtime filters, the chips show the values. See xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. From 6587cb898941e7ee1dce6bd71cd731ebf45d5dea Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 11:53:17 +0530 Subject: [PATCH 17/48] feedback-3 --- modules/ROOT/pages/common/nav-embedding.adoc | 2 +- modules/ROOT/pages/common/nav-in-product-help.adoc | 2 +- modules/ROOT/pages/liveboard-overrides.adoc | 12 ++++++------ 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/modules/ROOT/pages/common/nav-embedding.adoc b/modules/ROOT/pages/common/nav-embedding.adoc index ab410c90c..cedc1670b 100644 --- a/modules/ROOT/pages/common/nav-embedding.adoc +++ b/modules/ROOT/pages/common/nav-embedding.adoc @@ -96,7 +96,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] -** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[#Liveboard filter and parameter overrides#] +** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[Liveboard filter and parameter overrides] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/common/nav-in-product-help.adoc b/modules/ROOT/pages/common/nav-in-product-help.adoc index b61ee048c..9ce2a9007 100644 --- a/modules/ROOT/pages/common/nav-in-product-help.adoc +++ b/modules/ROOT/pages/common/nav-in-product-help.adoc @@ -112,7 +112,7 @@ Customize and integrate ** link:{{navprefix}}/runtime-overrides[Runtime overrides] ** link:{{navprefix}}/runtime-filters[Runtime filters] ** link:{{navprefix}}/runtime-params[Runtime Parameters] -** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[#Liveboard filter and parameter overrides#] +** link:{{navprefix}}/liveboard-filter-and-parameter-overrides[Liveboard filter and parameter overrides] * link:{{navprefix}}/action-config[Customize menus] ** link:{{navprefix}}/actions[Action IDs in the SDK] * link:{{navprefix}}/events-app-integration[Events and app interactions] diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 7fd3f3d76..8e4fb0b5f 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -224,7 +224,7 @@ Use these properties to narrow which chips an override updates: * `tabName`: set on each override. A tab also covers the groups on it, but not Liveboard-level chips. * `groupName`: set on each override. A group name matches every group with that name. Add `tabName` to pick the group on one tab. -In this table, the numbers refer to the chips of the example Liveboard. An empty cell means the property isn't set. +In this table, the numbers refer to the chips of the example Liveboard. An empty cell means the property is not set. [width="100%", cols="21,18,14,29,18"] [options='header'] @@ -267,7 +267,7 @@ Each of these overrides is skipped: [width="100%", cols="21,13,14,29,23"] [options='header'] |===== -|dataSourceIdentifier |tabName |groupName |filterQueryToken |Why it's skipped +|dataSourceIdentifier |tabName |groupName |filterQueryToken |Why the override is skipped | |Summary | |`Region=West` |A tab doesn't cover Liveboard-level chips, and the Summary tab has no Region chip. | |Summary |Top Stores |`Product Type=Shoes` |A group doesn't cover its tab's chips. Product Type is on the Summary tab, not in the group. |Returns |Summary | |`Store Name=Downtown` |The Summary tab has no Store Name chip from Returns. @@ -315,7 +315,7 @@ embed.render(); Result: chips 1, 3, 6, and 9, and the Discount Rate chip, are updated. Chips 2, 4, 5, 7, and 8, and the other parameter chips, keep their saved values. No two overrides target the same chip. -=== liveboardOverride properties +=== Liveboard override SDK flag properties [width="100%", cols="2,5a"] |==== @@ -329,8 +329,8 @@ Result: chips 1, 3, 6, and 9, and the Discount Rate chip, are updated. Chips 2, * When set, the entry's overrides update only that model's chips. * When omitted or empty, they update matching chips on every model. -* If the identifier doesn't match a model on the Liveboard, every override in the entry is ignored. - +* a model on the Liveboard, every override in the entry is ignored. +If the identifier does not match |`filterQuery` __Optional__ |__Array__. Filter overrides. Each item has the following properties: @@ -348,7 +348,7 @@ Result: chips 1, 3, 6, and 9, and the Discount Rate chip, are updated. Chips 2, Each token holds exactly one override. Do not join overrides with `;` or add `Model::Tab::` prefixes inside a token. Use the `dataSourceIdentifier`, `tabName`, and `groupName` properties instead. -Leave out properties you don't need rather than setting them to empty strings. +Leave out properties you do not need rather than setting them to empty strings. === Behavior in an embedded Liveboard From 26f0ea0f0a8c772cf3d90d0915bb0221fe5cd914 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 12:45:33 +0530 Subject: [PATCH 18/48] added to index --- src/components/SecondaryHeader/index.tsx | 2 +- src/configs/doc-configs.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/components/SecondaryHeader/index.tsx b/src/components/SecondaryHeader/index.tsx index 0dfcc5513..03a6e9f79 100644 --- a/src/components/SecondaryHeader/index.tsx +++ b/src/components/SecondaryHeader/index.tsx @@ -92,7 +92,7 @@ export const CATEGORY_PAGEIDS: Record = { 'embed-ts-swift', 'embed-ts-android', 'style-customization', 'customize-style', 'custom-css', 'css-variables-reference', 'customize-icons', 'customize-text', 'theme-builder-doc', - 'filters-overview', 'runtime-overrides', 'runtime-filters', 'runtime-params', + 'filters-overview', 'runtime-overrides', 'runtime-filters', 'runtime-params', 'liveboard-filter-and-parameter-overrides', 'action-config', 'actions', 'events-app-integration', 'embed-events', 'host-events', 'context-aware-event-routing', 'hostEventsV2-migration', 'api-search-intercept', 'custom-action-intro', 'customize-actions', 'custom-action-url', 'custom-action-callback', diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index 2943987cc..c6e95e915 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -94,7 +94,7 @@ module.exports = { 'customize-nav-controls', 'set-default-page', 'customize-homepage-experience', 'in-app-navigation', 'set-locale', 'custom-domain-config', 'customize-emails', 'customize-email-apis', - 'filters-overview', 'runtime-overrides', 'runtime-filters', 'runtime-params', + 'filters-overview', 'runtime-overrides', 'runtime-filters', 'runtime-params', 'liveboard-filter-and-parameter-overrides', 'action-config', 'actions', 'events-app-integration', 'embed-events', 'host-events', 'context-aware-event-routing', 'api-search-intercept', 'custom-action-intro', 'customize-actions', 'add-action-viz', 'add-action-worksheet', From 79d4d671de69ded5948d1bb19dce8f0d9af5591f Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Mon, 2 Nov 2026 13:03:57 +0530 Subject: [PATCH 19/48] rel version removed --- src/configs/doc-configs.js | 6 ------ 1 file changed, 6 deletions(-) diff --git a/src/configs/doc-configs.js b/src/configs/doc-configs.js index de8224dd7..a94a65c1e 100644 --- a/src/configs/doc-configs.js +++ b/src/configs/doc-configs.js @@ -65,12 +65,6 @@ module.exports = { subLabel: 'Cloud', iframeUrl: 'https://developer-docs-26-9-0-cl.vercel.app/docs/', }, - { - label: '26.8.0.cl', - link: '26.8.0.cl', - subLabel: 'Cloud', - iframeUrl: 'https://developer-docs-26-8-0-cl.vercel.app/docs/', - }, { label: '26.3.0.sw', link: '26.3.0.sw', From 060af0ce3d0936f911c2f644d4eadef982da3f5b Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 13:58:43 +0530 Subject: [PATCH 20/48] lang style changes --- modules/ROOT/pages/liveboard-overrides.adoc | 44 +++++++++++---------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 8e4fb0b5f..79f952778 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -17,12 +17,10 @@ You can supply overrides in two ways: * In the Liveboard URL, through the `filter` and `parameter` query parameters. * In an embedded Liveboard, through the `liveboardOverride` property of the Visual Embed SDK. -#The Liveboard opens with the chips already showing the values you passed, with those values applied. Users can change the chips afterward, just as they can after any other load.# - Use overrides for these tasks: * Open an embedded Liveboard with filters and parameters that match your application's context, such as the signed-in customer's region or the period selected in your app. -* Build links that open a Liveboard in a specific filtered state, for example a link from a row in one Liveboard to a detail Liveboard filtered on that row's values. +* Build links that open a Liveboard in a specific filtered state, for example, a link from a row in one Liveboard to a detail Liveboard filtered to that row's values. * Share a filtered state of a Liveboard without saving a personalized view for every combination of values. [#comparison] @@ -214,7 +212,11 @@ filterQuery: [ ], ---- -Result: both Region chips show West, because Region is on both models. Both Product Type chips show Shoes, because Product Type is on both tabs. All three Store Name chips show Downtown, because Store Name is in both groups and on both models. +Result: + +* Both Region chips show West (Region is on both models). +* Both Product Type chips show Shoes (Product Type is on both tabs). +* All three Store Name chips show Downtown (Store Name is in both groups and on both models). === Step 4: Target a model, tab, or group @@ -355,10 +357,10 @@ Leave out properties you do not need rather than setting them to empty strings. * `liveboardOverride` is the only way to pass overrides to an embedded Liveboard. Unlike runtime filters, which you can add to an embedded object's URL, adding `filter=` or `parameter=` to the URL of an embedded Liveboard has no effect. * Overrides apply when the Liveboard loads. Changing `liveboardOverride` after the Liveboard has rendered doesn't reload it. To change filter or parameter values after load, use the xref:filters_overview.adoc#_updatefilters_event[`UpdateFilters`] and `UpdateParameters` host events. * Overrides with no token are dropped, and so are properties the SDK doesn't recognize. -* When a personalized view is loaded in the embedded Liveboard, for example because the user selects one, the view opens with its saved values, and the overrides aren't applied to it. +* When a personalized view is loaded in the embedded Liveboard, for example because the user selects one, the view opens with its saved values, and . [#url] -== Apply overrides in a Liveboard URL +== Apply overrides in a Liveboard URLthe overrides are not applied to it Add the `filter` and `parameter` query parameters after the Liveboard's route, that is, after the `+#+`: @@ -371,7 +373,7 @@ https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter overrides}&p * You can combine them with other Liveboard URL parameters, such as a tab (`+#/pinboard/{liveboard-id}/tab/{tab-id}?filter=...+`) or a personalized view (`+?view={view-id}&filter=...+`). * Separate overrides with a semicolon (`;`). * Spaces around operators are optional: `Region=West` and `Region = West` are the same override. -* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region=West"+`. Curly quotes are not removed, and quoting individual overrides isn't supported. +* You can wrap the whole value in one pair of straight double quotes, for example `+filter="Region=West"+`. Curly quotes are not removed, and quoting individual overrides is not supported. === URL examples @@ -433,10 +435,12 @@ Not supported on attribute columns:: * `between` * Contains, begins with, or ends with matching * An empty list item, such as `Region=West,` or `Region=West,,East` -* `{null}`. Filtering on null values isn't supported. +* `{null}`. Filtering on null values is not supported. -NOTE:: +[NOTE] +==== Values are passed as written. Type them as they appear in the data. +==== === Measure columns @@ -561,13 +565,11 @@ The value must satisfy the parameter's own restrictions: * For a parameter with a range, the value must fall inside the range. * A value that doesn't meet these restrictions is ignored, and the chip keeps its current value. -// - Not supported:: * Any operator other than `=` * More than one value, such as `Top N=5, 10` -* An empty value (`Top N=`). Parameter chips can't be cleared. +* An empty value (`Top N=`). Parameter chips cannot be cleared. * `{null}` * Dynamic date values, such as `Forecast Start=today` or `last 7 days` * Date-time and time parameters @@ -601,7 +603,7 @@ Some characters have a special meaning in an override. To use one of them as par |The value `Airport::Gate 5`. Without the backslash, `::` is read as a model, tab, or group prefix. Needed in URLs only. |===== -In the SDK, you don't need to escape `;` or `::`. Each token already holds one override, and models, tabs, and groups are set through properties. +In the SDK, you do not need to escape `;` or `::`. Each token already holds one override, and models, tabs, and groups are set through properties. A single colon needs no escaping. For example, `Region=sales: eu` is read as one value. @@ -653,7 +655,7 @@ There is no prefix that targets only a Liveboard-level chip. An override without === Invalid overrides are skipped * Each override is applied independently. If an override can't be applied, because of a misspelled name, an invalid value, an unknown prefix, or a missing chip, only that override is skipped. The other overrides still apply, and the Liveboard always loads. -* No error or warning is shown, so check the chips after the Liveboard loads to confirm which values were applied. +* No error or warning is shown, so verify the chip values after the Liveboard loads to confirm which overrides were applied. * Overrides can be applied differently for different users. For example, an override on a model the user can't access is skipped for that user. === Personalized views @@ -677,7 +679,7 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U [options='header'] |===== |Action |Result -|Reload the page |The overrides are applied again. Filter changes the user made after load are lost. +|Reload the page |The overrides are applied again. Any filter changes the user made after the initial load are discarded. |Switch tabs |The overrides stay in effect. |Open and close *Explore* on a visualization |The overrides stay in effect. |Reset filters in the filter window |The overrides are removed from the URL, and the chips return to their saved values. @@ -689,21 +691,21 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U === Downloads, schedules, and alerts * Downloads from the Liveboard, such as PDF or a visualization's CSV, use the overridden values. -* Scheduled Liveboard jobs and alerts use the saved values. Overrides aren't applied to them. +* Scheduled Liveboard jobs and alerts use the saved values. Overrides are not applied to them. [#precedence] === Security and precedence * Overrides are not a security feature. Anyone who can edit the URL can change the values or remove them. To restrict data, use xref:rls-rules.adoc[row-level security (RLS)] or the xref:abac-user-parameters.adoc[ABAC and JWT security methods]. * Overrides can't expose data the user isn't allowed to see. RLS applies to the overridden values as it does to any filter. Overrides on columns the user can't access are skipped. -* A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, if a JWT token pins `Discount Rate` to `0.1` and the URL sets `Discount Rate=0.15`, the Liveboard uses `0.1`. Sources, from highest to lowest priority: +* A parameter can get its value from several places. When more than one sets it, ThoughtSpot uses the value from the highest-priority source. For example, a JWT token pinning `Discount Rate` to `0.1` takes precedence over a URL setting it to `0.15`. Sources, from highest to lowest priority: .. A value pinned through ABAC with a JWT token .. A runtime parameter override (`runtimeParameters`, or `param1` and `paramVal1` in the URL) .. A Liveboard parameter override .. The personalized view's value .. The Liveboard's saved value .. The parameter's default value -* Don't set the same parameter with both a runtime parameter override and a Liveboard override. The runtime override wins, and the chip is hidden. +* Avoid setting the same parameter with both a runtime parameter override and a Liveboard override. The runtime override wins, and the chip is hidden. * Runtime filters and Liveboard filter overrides can be used together. The runtime filter restricts the column's data, and the override sets the chip's selection, and both apply. == Limitations @@ -712,9 +714,9 @@ Overrides are not saved to the Liveboard. In a Liveboard URL, they stay in the U * In embedded deployments, only `LiveboardEmbed` is supported. Full application embedding (`AppEmbed`) is not supported in this release. * Overrides apply only at load. To change values after load in an embed, use the `UpdateFilters` and `UpdateParameters` host events. * Dynamic date values for parameters are not supported, and date-time and time parameters are not supported. -* A parameter chip can't be cleared. +* A parameter chip cannot be cleared. * Overrides don't create chips, and they don't apply to columns or parameters without a chip. -* Scheduled jobs and alerts don't use overrides. +* Scheduled jobs and alerts do not use overrides. * Skipped overrides aren't reported in the UI or through an embed event. == Troubleshooting @@ -750,7 +752,7 @@ a| |Contextual filtering must be turned on. Check the tab and group names. |===== -To check what was sent, open the browser's developer tools. On the *Network* tab, find the `LoadPinboardSession` request: its `liveboardOverride` variable shows the overrides ThoughtSpot received. +To check what was sent, open the browser's developer tools. On the *Network* tab, find the `LoadPinboardSession` request. The `liveboardOverride` variable in that request shows the overrides ThoughtSpot received. == Related information From 96dc05fd53264c4faba0aa22ecc6d874a5ddedba Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 14:37:02 +0530 Subject: [PATCH 21/48] removed extra hyphens --- modules/ROOT/pages/whats-new.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 56b2790d5..83234b839 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -69,7 +69,7 @@ For more information, see xref:link-customization-api.adoc[Link Customization AP ThoughtSpot introduces new REST API endpoints to create and manage input tables, which are user-editable tables stored in your Cloud Data Warehouse and linked to a ThoughtSpot model. For more information, see xref:input-table-api.adoc[Input Table APIs]. ---- + [discrete] ==== Spotter usage limits From d525699ab6cc4def3b40fa8bca6c93f9694cd6a9 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 17:48:48 +0530 Subject: [PATCH 22/48] feedback-1 --- modules/ROOT/pages/liveboard-overrides.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 79f952778..2c3886ce7 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -88,7 +88,7 @@ Overrides work on the Liveboard's filter and parameter chips instead. They repla |Yes |===== -#To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` adds runtime filters on top of any already applied.# +#To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` replaces the runtime filter for any column you specify with the new value, filters on columns you don't specify are preserved.# Use overrides when users should see and adjust the values in the Liveboard's own chips. From 8674bb9f95042f9f56fd73941f1a6f7f41307be2 Mon Sep 17 00:00:00 2001 From: Rani Gangwar Date: Mon, 2 Nov 2026 17:59:54 +0530 Subject: [PATCH 23/48] removed highlight markers --- modules/ROOT/pages/api-changelog.adoc | 14 ++++++------ .../pages/customize-liveboard-filters.adoc | 2 +- modules/ROOT/pages/filters_overview.adoc | 6 ++--- modules/ROOT/pages/liveboard-overrides.adoc | 22 +++++++++---------- modules/ROOT/pages/runtime-parameters.adoc | 2 +- modules/ROOT/pages/whats-new.adoc | 10 ++++----- 6 files changed, 28 insertions(+), 28 deletions(-) diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index ed0b76072..988175179 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -15,15 +15,15 @@ This page documents the changes introduced in each release of the Visual Embed S |[tag greenBackground]#NEW# a| [discrete] -===== #Liveboard embedding# -#`liveboardOverride` in `LiveboardViewConfig` sets the values of a Liveboard's existing filter and parameter chips when the Liveboard loads. New types:# +===== Liveboard embedding +`liveboardOverride` in `LiveboardViewConfig` sets the values of a Liveboard's existing filter and parameter chips when the Liveboard loads. New types: -* #`LiveboardOverride`# -* #`LiveboardDataSourceOverride`# -* #`LiveboardFilterQuery`# -* #`LiveboardParameterQuery`# +* `LiveboardOverride` +* `LiveboardDataSourceOverride` +* `LiveboardFilterQuery` +* `LiveboardParameterQuery` -#For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. ===== Spotter file upload in SpotterViz The following `SpotterVizConfig` options control file upload in the SpotterViz chat input: diff --git a/modules/ROOT/pages/customize-liveboard-filters.adoc b/modules/ROOT/pages/customize-liveboard-filters.adoc index 223a38c3e..480e03561 100644 --- a/modules/ROOT/pages/customize-liveboard-filters.adoc +++ b/modules/ROOT/pages/customize-liveboard-filters.adoc @@ -118,7 +118,7 @@ To listen for filter and parameter changes, use `EmbedEvent.FilterChanged` and ` For more information, see xref:events-hostEvents.adoc#liveboard-group-events[Liveboard group and parameter events] and xref:events-hostEvents.adoc#applicability-host-events[Scoped filter and parameter host events]. -#To set tab-level and group-level filter and parameter values at load, use the `liveboardOverride` property. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group] in xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +To set tab-level and group-level filter and parameter values at load, use the `liveboardOverride` property. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group] in xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. [#update-filters] == Updating filters diff --git a/modules/ROOT/pages/filters_overview.adoc b/modules/ROOT/pages/filters_overview.adoc index e7a7747fe..21dd4c200 100644 --- a/modules/ROOT/pages/filters_overview.adoc +++ b/modules/ROOT/pages/filters_overview.adoc @@ -38,7 +38,7 @@ xref:runtime-filters.adoc#_maximum_filter_count[Runtime filter limit] for more i 4. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters[Liveboard filters, window=_blank] + Liveboard filters are visible as UI components at the top of a Liveboard page. By default, a Liveboard filter applies to all visualizations on the Liveboard. Starting with ThoughtSpot Cloud 26.10.0.cl, a filter can also be scoped to a specific tab or group. For more information, see <>. When a filter is clicked, a modal with filter options appropriate for the data type is displayed. + Liveboard users can add or modify filters as needed. If you are embedding a Liveboard that includes preset filters, you can programmatically update, reset, or remove filters using `HostEvent.UpdateFilters`. + -#To set Liveboard filter and parameter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Overrides set the values of the Liveboard filters in this layer. They are not runtime filters (layer 3).# +To set Liveboard filter and parameter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Overrides set the values of the Liveboard filters in this layer. They are not runtime filters (layer 3). 5. link:https://docs.thoughtspot.com/cloud/latest/liveboard-filters-cross[Liveboard cross filters, window=_blank] + Cross filters are ad-hoc filters based on user selection. These filters are used for brushing and linking Liveboard visualizations. + @@ -183,7 +183,7 @@ Any data restrictions resulting from filter rules will be seen in the visible fi xref:runtime-filters.adoc[Runtime filters] can be applied at load via Visual Embed SDK, REST API, or URL parameters. -#To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. After load, Liveboard filters can be updated using `HostEvent.UpdateFilters` in the SDK.# +To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. After load, Liveboard filters can be updated using `HostEvent.UpdateFilters` in the SDK. Search query filters can be applied at load by specifying them in the initial search query when embedding an Answer or Spotter session. For example, in Spotter embed, you can use the `searchQuery` property to set a pre-defined search (including filters) at load. @@ -197,7 +197,7 @@ If the column already has a Liveboard filter and the user applies cross filters, Whenever any user action affects a cross filter, a link:https://developers.thoughtspot.com/docs/Enumeration_EmbedEvent#_crossfilterchanged[EmbedEvent.CrossFilterChanged] fires, which can then be used to trigger a specific action. == Updating filters using host events in Visual Embed SDK -#To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To adjust the values after the Liveboard is rendered, use the following events.# +To set Liveboard filter values at load, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. To adjust the values after the Liveboard is rendered, use the following events. === OpenFilter event If you have hidden the Liveboard header, you can trigger the action of opening a filter modal dialog using link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_openfilter[HostEvent.OpenFilter]: diff --git a/modules/ROOT/pages/liveboard-overrides.adoc b/modules/ROOT/pages/liveboard-overrides.adoc index 2c3886ce7..261771b33 100644 --- a/modules/ROOT/pages/liveboard-overrides.adoc +++ b/modules/ROOT/pages/liveboard-overrides.adoc @@ -88,7 +88,7 @@ Overrides work on the Liveboard's filter and parameter chips instead. They repla |Yes |===== -#To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` replaces the runtime filter for any column you specify with the new value, filters on columns you don't specify are preserved.# +To change values after the Liveboard loads, use host events. `UpdateFilters` and `UpdateParameters` update the chips and fetch data again. `UpdateRuntimeFilters` replaces the runtime filter for any column you specify with the new value, filters on columns you don't specify are preserved. Use overrides when users should see and adjust the values in the Liveboard's own chips. @@ -377,7 +377,7 @@ https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter={filter overrides}&p === URL examples -#Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region=West, East+`.# +Add these to the end of the Liveboard's URL, for example `+https://{ThoughtSpot-Host}/#/pinboard/{liveboard-id}?filter=Region=West, East+`. [width="100%", cols="3,5"] [options='header'] @@ -410,7 +410,7 @@ A filter override has this form: {Column name}{operator}{value}[, {value}...] ---- -* #*Column name*: the name of the filter. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes.# +* *Column name*: the name of the filter. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. * *Operators*: `=`, `!=`, `<`, `+<=+`, `>`, `>=`. Which operators you can use depends on the column type, as shown in the tables below. * *Lists*: separate values with commas. Spaces inside a value are kept, so `Store Name=New York Downtown, San Francisco Bay` is a list of two values. * *Keywords*: keywords such as `between`, `last` and `today` are case-insensitive. @@ -536,7 +536,7 @@ A parameter override has this form: {Parameter name}={value} ---- -* #*Parameter name*: the parameter's name. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes.# +* *Parameter name*: the parameter's name. It is case-insensitive, but it must match the whole name. Partial and fuzzy matches are not supported. Multi-word names need no quotes. * *Value*: exactly one value, written for the parameter's data type. [width="100%", cols="2,5a"] @@ -612,7 +612,7 @@ A single colon needs no escaping. For example, `Region=sales: eu` is read as one When no model, tab, or group is given, an override updates every chip with a matching name across all models and all levels (Liveboard, tab, and group). For example, `Region=West` updates the Region chip on both Retail Sales and Returns. -#To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>:# +To narrow an override, prefix it with names separated by `::` in a URL, or set `dataSourceIdentifier`, `tabName`, and `groupName` in the SDK. Chip numbers refer to the <<_example_liveboard,example Liveboard>>: [width="100%", cols="4,3,4"] [options='header'] @@ -632,11 +632,11 @@ How prefixes are matched in a URL: * Names are matched against the display names of models, tabs, and groups. Matching is case-insensitive. * A model can also be given by its GUID. Tabs and groups are matched by name only. -* #Prefixes always go in the order model > tab > group, and you can leave any of them out:# -** #With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type=Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab.# -** #With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name=Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group.# -** #With three prefixes, they are read as model, tab, and group.# -* #Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK.# +* Prefixes always go in the order model > tab > group, and you can leave any of them out: +** With one prefix, the name is looked up as a model, then a tab, then a group. For example, in `Regional Detail::Product Type=Shoes`, `Regional Detail` doesn't match a model, so it is read as a tab. +** With two prefixes, the first is looked up as a model, then a tab, and the second must come after it in that order. For example, in `Regional Detail::Top Stores::Store Name=Downtown`, `Regional Detail` is read as a tab, so `Top Stores` must be a group. +** With three prefixes, they are read as model, tab, and group. +* Because models are looked up first, a name shared by a model and a tab is read as the model. To target the tab in that case, use the `tabName` property in the SDK. * An override with more than three prefixes is ignored. * An override whose prefix doesn't match a model, tab, or group on the Liveboard is ignored. @@ -735,7 +735,7 @@ a| |One override is not applied a| * A chip exists for that column or parameter, at the scope you targeted. -* #The name matches the filter or parameter name in full.# +* The name matches the filter or parameter name in full. * The value format matches the tables above: ISO dates, one value for parameters, a value inside the parameter's list or range. * Any prefix matches a model, tab, or group name. diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 9934f5b19..7d75f7ced 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -30,7 +30,7 @@ When applied, runtime parameters override the default or saved Parameter values [NOTE] ==== -Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. #Liveboard overrides can also target a parameter chip on a specific tab or group, which runtime parameter overrides can't. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group].# +Runtime parameter overrides hide the parameter chip. To set a Liveboard parameter's value and keep its chip visible, use xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. Liveboard overrides can also target a parameter chip on a specific tab or group, which runtime parameter overrides can't. For more information, see xref:liveboard-overrides.adoc#scoping[Target a model, tab, or group]. ==== === Supported data types diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 05b76805f..5481d3d22 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -38,13 +38,13 @@ a| a| [discrete] -==== #Liveboard filter and parameter overrides# [earlyAccess eaBackground]#Early Access# -#You can now set the values of a Liveboard's filter and parameter chips when the Liveboard loads. Two ways are available:# +==== Liveboard filter and parameter overrides [earlyAccess eaBackground]#Early Access# +You can now set the values of a Liveboard's filter and parameter chips when the Liveboard loads. Two ways are available: -* #The new `liveboardOverride` property in `LiveboardViewConfig`, for embedded Liveboards.# -* #The `filter` and `parameter` query parameters in a Liveboard URL.# +* The new `liveboardOverride` property in `LiveboardViewConfig`, for embedded Liveboards. +* The `filter` and `parameter` query parameters in a Liveboard URL. -#Unlike runtime filters, overrides update the chips the user sees. They support rolling dates, and they can target a specific model, tab, or group. The Liveboard fetches its data once, with the values already applied. To enable this feature, ask your administrator to turn on *Filtered Liveboard URLs* in the Admin portal. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides].# +Unlike runtime filters, overrides update the chips the user sees. They support rolling dates, and they can target a specific model, tab, or group. The Liveboard fetches its data once, with the values already applied. To enable this feature, ask your administrator to turn on *Filtered Liveboard URLs* in the Admin portal. For more information, see xref:liveboard-overrides.adoc[Liveboard filter and parameter overrides]. ==== New Spotter experience in embedded apps ThoughtSpot introduces the new Spotter experience, including Spotter on Liveboards. Spotter opens in a side panel on a Liveboard and uses the entire board, its charts, tabs, and applied filters, as conversation context. Conversations are saved with the Liveboard so users can return to them later. From 67988f3a633ce08ee86271d2ac904dfe500369c2 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Tue, 3 Nov 2026 16:11:47 +0530 Subject: [PATCH 24/48] SCAL-349346 - MCP tools --- modules/ROOT/pages/mcp-integration.adoc | 3 + modules/ROOT/pages/mcp-server-changelog.adoc | 51 ++ modules/ROOT/pages/mcp-server-spotter3.adoc | 17 +- .../pages/mcp-tool-reference-spotter3.adoc | 803 ++++++++++++++++-- 4 files changed, 817 insertions(+), 57 deletions(-) diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 942542efe..8101392f4 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -14,8 +14,11 @@ ThoughtSpot Spotter MCP Server exposes ThoughtSpot analytics as tools and resour * Automatic discovery of ThoughtSpot MCP tools * Natural language queries and responses * Programmatic creation of Liveboards and visualizations +* Changing existing dashboards, such as rearranging, restyling, and adding charts, text, groups, and tabs * Generating embeddable visualizations * Searching for existing ThoughtSpot content by name, author, tag, or type +* Reading the data behind existing Answers and Liveboards +* Building and editing data models through conversation === Supported integrations ThoughtSpot Spotter MCP Server supports two primary integration options: diff --git a/modules/ROOT/pages/mcp-server-changelog.adoc b/modules/ROOT/pages/mcp-server-changelog.adoc index 5c01d63ef..b16f6d773 100644 --- a/modules/ROOT/pages/mcp-server-changelog.adoc +++ b/modules/ROOT/pages/mcp-server-changelog.adoc @@ -24,6 +24,57 @@ This changelog lists the new features, enhancements, and other changes introduce // *Affects:* Developers, Administrators, End Users // ============================================================ +== October 2026 +// TODO: verify with engineering. Confirm the upgrade behavior of unpinned URLs. +*API version string:* `?api-version=latest` + +*Upgrade notes*: Existing integrations using `?api-version=latest` receive these changes automatically. The `create_dashboard` changes may break integrations that read its response. See xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. + +[.cl-table, cols="1,4", frame=none, grid=none] +|==== +a| +[.cl-label] + +*October 2026* + +a| + +[discrete] +==== `create_dashboard` MCP tool [.version-badge.breaking]#Breaking# +The `create_dashboard` tool is now powered by SpotterViz. It can create a dashboard from completed analysis or from a description. SpotterViz shares its plan and chosen data source first, and nothing is built until the user approves. + +* The response is a status object. The tool can return `completed`, `in_progress`, `needs_input`, or `failed`. +* The `note_tile` parameter is removed. +* The `answers` parameter is now optional. +* The `instructions`, `task_id`, and `data_source_id` parameters are added. + +For more information, see xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. + +--- + +[discrete] +==== `modify_dashboard` MCP tool +The new `modify_dashboard` MCP tool changes an existing dashboard. It can rearrange and restyle content, add charts and explanatory text, and organize charts into groups and tabs. For more information, see xref:mcp-tool-reference-spotter3.adoc#modify_dashboard[modify_dashboard]. + +--- + +[discrete] +==== `get_dashboard_status` MCP tool +The new `get_dashboard_status` MCP tool polls a dashboard task that `create_dashboard` or `modify_dashboard` left in progress. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_dashboard_status[get_dashboard_status]. + +--- + +[discrete] +==== `get_data` MCP tool +The new `get_data` MCP tool fetches the columns and rows of a saved Answer or Liveboard. Use it with `search_objects` to answer questions from content that your organization already trusts. The tool is available only to users who have the privilege to download data. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_data[get_data]. + +--- + +[discrete] +==== Model builder MCP tools +The new model builder MCP tools let agents build a data model from warehouse tables, or edit an existing model, through conversation. The tools are `create_model_session`, `send_model_message`, `get_model_updates`, and `finalize_model`. The builder proposes a plan for approval, and the model is saved only after the user confirms. The tools are available only to users who can create or edit data models. For more information, see xref:mcp-tool-reference-spotter3.adoc#model-builder-tools[Model builder tools]. + +|==== + == August 2026 *API version string:* `?api-version=2026-05-01` + *Upgrade notes*: Existing integrations using `?api-version=2026-05-01` or `?api-version=latest` will be automatically upgraded. diff --git a/modules/ROOT/pages/mcp-server-spotter3.adoc b/modules/ROOT/pages/mcp-server-spotter3.adoc index fe03bf9c8..c5543109f 100644 --- a/modules/ROOT/pages/mcp-server-spotter3.adoc +++ b/modules/ROOT/pages/mcp-server-spotter3.adoc @@ -83,9 +83,8 @@ ThoughtSpot returns the following update types: //// 5. *User generates a dashboard with the results (optional)* + -The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. + -ThoughtSpot creates a dashboard and returns a `dashboard_id` and a -`dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. +The user can choose to save answers from the conversation as a ThoughtSpot dashboard. For this workflow, the agent extracts the `answer_id` and `answer_title` from each `answer` type update collected during polling and calls `create_dashboard`. The agent passes each `answer_title` as the `title` of the answer, and can add `instructions` for layout and style. + +SpotterViz, the ThoughtSpot dashboard designer, organizes and styles the charts and saves them as a dashboard. If the dashboard is not ready, `create_dashboard` returns `status: "in_progress"` and a `task_id`, and the agent polls `get_dashboard_status` until the status changes. When the status is `completed`, the response contains the `dashboard_id` and the `dashboard_url`, a direct link to the dashboard in the ThoughtSpot UI. For more information, see xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. The other optional tool calls include: @@ -98,6 +97,18 @@ If the user belongs to more than one Org and connects over OAuth, the agent call * *Agent searches for existing content (optional)* + If the user refers to content that already exists, for example, "open the regional sales Liveboard", the agent calls `search_objects` with a search term and optional filters such as object type, author, tag, or verified status. `search_objects` returns a ranked list of matching objects with their metadata and deep links. +* *Agent reads the data behind existing content (optional)* + +After `search_objects` returns an Answer or Liveboard, the agent can call `get_data` with the `object_id` from the result, and the result's `type` as `object_type`, to fetch the columns and rows that the object shows. For a single visualization on a Liveboard, the agent passes the `visualization_id` in `visualization_ids`. The agent answers from the returned rows, which reflect the latest data. `get_data` is available only to users who have the privilege to download data. For more information, see xref:mcp-tool-reference-spotter3.adoc#get_data[get_data]. + +* *User asks for a dashboard from a description (optional)* + +If the user asks for a dashboard before any analysis, or wants one recreated from another tool, the agent calls `create_dashboard` with `instructions` and no `answers`. SpotterViz returns `status: "needs_input"` with the data source it chose and its plan. The agent shows the plan to the user. After the user confirms or asks for changes, the agent calls `create_dashboard` again with the same `task_id` and the user's reply in `instructions`. + +* *User changes an existing dashboard (optional)* + +The agent finds the dashboard GUID with `search_objects`, and calls `modify_dashboard` with the `dashboard_id` and the user's change in `instructions`. If SpotterViz asks a question, the agent shows it to the user and calls `modify_dashboard` again with the same `dashboard_id` and `task_id`. For more information, see xref:mcp-tool-reference-spotter3.adoc#modify_dashboard[modify_dashboard]. + +* *User builds or edits a data model (optional)* + +The agent calls `create_model_session` with a connection GUID for a new model, or a model GUID to edit one. The agent sends instructions with `send_model_message` and polls `get_model_updates` until `is_done` is `true`. The builder proposes a plan first, and the agent shows it to the user and waits for approval. To save, the agent calls `finalize_model` for a summary, and then calls it again with `confirm: true` after the user approves. The model builder tools are available only to users who can create or edit data models. For more information, see xref:mcp-tool-reference-spotter3.adoc#model-builder-tools[Model builder tools]. + == Additional resources * For information about MCP, see the link:https://modelcontextprotocol.io[Model Context Protocol specification, window=_blank]. * For implementation details, see the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repository, window=_blank]. diff --git a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc index d2f2e6822..0b1a334d8 100644 --- a/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc +++ b/modules/ROOT/pages/mcp-tool-reference-spotter3.adoc @@ -1,3 +1,4 @@ + = MCP tool reference (Spotter 3) :toc: true :toclevels: 3 @@ -6,7 +7,8 @@ :page-pageid: mcp-tool-reference-spotter3 :page-description: Refer to this guide to learn which MCP tools are supported, input parameters used for tool calls, and the response format. -The ThoughtSpot Spotter Model Context Protocol (MCP) Server integration exposes tools for running natural language analytics queries and searching existing ThoughtSpot content. The core analytics pattern is: **create a session** → **send a message** → **poll for updates**. The `search_objects` tool is independent of this workflow and can be called at any time. +Analysis, dashboard creation, and model building each follow the same pattern, **start the work** → **poll for updates** until it finishes. +The analysis workflow is **create a session** → **send a message** → **poll for updates**. The `search_objects` and `get_data` tools are independent of these workflows and can be called at any time. * <> + Start an analytical session. @@ -15,9 +17,23 @@ Send a natural language question or follow-up. * <> + Poll for streamed responses. * <> + -Create a dashboard from session answers. +Create a dashboard from session answers or from a description. +* <> + +Change an existing dashboard. +* <> + +Poll a dashboard task that is still running. * <> + Search for existing ThoughtSpot content by name or description. +* <> + +Fetch the columns and rows of a saved Answer or Liveboard. +* <> + +Start a session to build or edit a data model. +* <> + +Send an instruction to the model builder or answer one of its questions. +* <> + +Poll for the model builder's progress. +* <> + +Review and save the model. * <> + List the Orgs your account can access. (OAuth connections on Org-enabled instances only) * <> + @@ -25,6 +41,14 @@ Switch your active Org for the current session. (OAuth connections on Org-enable * <> + Verify that the MCP Server is reachable. +[NOTE] +==== +* The new and updated tools are available only on the MCP server endpoint `?api-version=latest`. Integrations that are pinned to a specific API version do not receive them. +* The server lists `get_data` only for users who have the privilege to download data. +* The server lists the model builder tools only for users who have the data management privilege and the privilege to create or edit data models. +==== + + [#create_analysis_session] == create_analysis_session Start an analytical session with ThoughtSpot's analytics agent. This is the required first step before sending any questions. @@ -32,7 +56,9 @@ Start an analytical session with ThoughtSpot's analytics agent. This is the requ Sessions are conversational. Once created, you can send multiple follow-up questions to the same session without calling `create_analysis_session` again. === Input parameter -The `data_source_id` is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. +The `data_source_id` is optional. Provide this when the user has specified or confirmed a data source, or when context makes a particular source obvious. Omit to let ThoughtSpot automatically select the most relevant source based on the question. If the instance does not support automatic selection, the tool returns an error that asks for a data source. Find the GUID with xref:mcp-tool-reference-spotter3.adoc#search_objects[search_objects], using `types: ["WORKSHEET"]`. If you have only the data source name, you can pass it in the `additional_context` field of `send_session_message` instead. + +The `data_source_id` must be a GUID in the format `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`. === Example call @@ -92,7 +118,7 @@ __Optional__|Can be used to provide external information relating to the questio [source,javascript] ---- const sendMessage = await callMCPTool("send_session_message", { - analytical_session_id: "sess_abc123", // Session ID from create_analysis_session. + analytical_session_id: "session-guid-abc123", // Session ID from create_analysis_session. message: "What were total sales by region last quarter?", // User's natural language question. additional_context: "The user's fiscal year starts in April. " + "Focus on underperforming regions only." // Optional. External information to influence the analysis. @@ -104,10 +130,10 @@ const sendMessage = await callMCPTool("send_session_message", { call_mcp_tool( "send_session_message", { - "analytical_session_id": "sess_abc123", # Session ID from create_analysis_session. + "analytical_session_id": "session-guid-abc123", # Session ID from create_analysis_session. "message": "What were total sales by region last quarter?", # User's natural language question. "additional_context": ( # Optional. External information - "The user's fiscal year starts in April." + "The user's fiscal year starts in April. " "Focus on underperforming regions only." # to influence the analysis. ), }, @@ -131,6 +157,7 @@ call_mcp_tool( * After a successful send, immediately begin polling with `get_session_updates`. * Do not send a second message until `get_session_updates` returns `is_done: true`. The agent processes one message at a time per session. * To ask a follow-up question, reuse the same `analytical_session_id`. There is no need to create a new session. +* Do not send a dashboard request through this tool. To create a dashboard, use xref:mcp-tool-reference-spotter3.adoc#create_dashboard[create_dashboard]. ==== [#get_session_updates] @@ -146,7 +173,7 @@ Send the `analytical_session_id` to specify the session to retrieve updates for. [div tabbed-code] -- -[source,typescript] +[source,javascript] ---- const updates = await callMCPTool("get_session_updates", { analytical_session_id: "session-guid-abc123" // Session ID from the `create_analysis_session` call. @@ -157,7 +184,7 @@ const updates = await callMCPTool("get_session_updates", { ---- call_mcp_tool( "get_session_updates", - {"analytical_session_id": "sess_abc123"}, # Session ID from create_analysis_session. + {"analytical_session_id": "session-guid-abc123"}, # Session ID from create_analysis_session. ) ---- -- @@ -180,9 +207,9 @@ Render these immediately so the user sees progress in real time. |A fragment of Spotter's narration. Concatenate chunks to form the complete narration string. When `is_thinking` is `false`, the chunk is part of the final answer narration, not an intermediate thinking step. -|`answer`|`false` +|`answer`|`true` or `false` |The analytical result. Contains a title, the ThoughtSpot search query used, an embeddable `iframe_url`, and an `answer_id` for creating dashboards. -Exactly one `answer` update is present per question. +The same answer can arrive twice in one response, once with `is_thinking: true` and once with `is_thinking: false`. Both updates carry the same `answer_id`. Render the answer once, and use the `answer_id` to remove duplicates. |==== Poll returning intermediate updates: @@ -223,6 +250,15 @@ Poll returning the final answer: "type": "text_chunk", "text": "Running the query against the sales data model..." }, + { + "is_thinking": true, + "type": "answer", + "answer_id": "{\"session_id\":\"1a3d...\",\"gen_no\":2}", + "answer_title": "Total sales by region", + "answer_data_source_id": "cd252e5c-...", + "answer_query": "[sales] [region]", + "iframe_url": "https://your-instance.thoughtspot.cloud/?tsmcp=true#/embed/conv-assist-answer?..." + }, { "is_thinking": false, "type": "text_chunk", @@ -255,8 +291,8 @@ A typical response sequence might look like: . Step headings: `step_notification` updates announcing each step Spotter is about to start. . Thinking narration: `text_chunk` updates with `is_thinking: true` describing what Spotter is doing. -. Clarifications or caveats: `text_chunk` updates with `is_thinking: false` explaining assumptions, filters applied, or potential ambiguities in the question. -. The final answer: one or more `answer` updates containing the visualization title, the underlying query, and the embeddable iframe URL. +. The answer: an `answer` update containing the visualization title, the underlying query, the `answer_id`, and the embeddable iframe URL. The same answer can arrive again with `is_thinking: false`. +. Final narration: `text_chunk` updates with `is_thinking: false`. This text can explain assumptions, filters applied, or ambiguities in the question, and can include a Markdown summary of the results, such as key takeaways. It can arrive before and after the `answer` update, so the `answer` is not always the last update. This means a complete response might span 5–20+ `get_session_updates` calls and contain many `session_update` objects before `is_done` becomes `true`. All of this content, the thinking, the narration, and the final answer, should be accumulated and presented together to give the user the full picture. @@ -265,7 +301,7 @@ Includes three types, `step_notification`, `text_chunk`, `answer`. Flat, fixed k [source,json] ---- -{"is_thinking":true,"type":"step_notification","text":"Searching for Datasets"} +{"is_thinking":true,"type":"step_notification","text":"Searching data models"} {"is_thinking":true,"type":"text_chunk","text":" to find the most relevant dataset..."} {"is_thinking":false,"type":"answer", "answer_id":"{\"session_id\":\"1a3d...\",\"gen_no\":2}", @@ -286,6 +322,8 @@ Each item in the `session_updates` list is a `session_update` object. The `type` |`"step_notification"`|A short heading announcing the step Spotter is about to start, such as `Searching data models` or `Running query`. |`"text_chunk"` | A streaming fragment of Spotter's narration. Concatenate all chunks to reconstruct the full text. |`"answer"`|Populates `answer_title`, `answer_query`, `answer_data_source_id`, `iframe_url` fields. A data visualization result with a title, the underlying query, and an embeddable URL. +|`is_thinking`|__Boolean__|`true` for intermediate reasoning (`step_notification` updates and thinking `text_chunk` updates). `false` for the final narration and the answer. +|`answer_id`|__String__|Identifier of the answer. Present only when `type` is `"answer"`. Pass it as is to `create_dashboard`. |`text`|__String__|The text content of the message. Present only when `type` is `"step_notification"` or `"text_chunk"`. For `"text_chunk"` updates, concatenate all chunks to form the complete message. |`answer_title`|__String__|A human-readable title describing what the answer shows. Present only when `type` is `"answer"`. |`answer_data_source_id`|__String__|GUID of the data source used to generate the answer. Present only when `type` is `"answer"`. @@ -328,48 +366,70 @@ The full response does not include a preconstructed `iframe_url`. You must build For the complete event schema, see the xref:spotter-agent-apis.adoc#_api_response_2[Spotter Agent API, window=_blank]. + [#create_dashboard] == create_dashboard -Create a ThoughtSpot dashboard from answers generated in an analysis session. -* Call this only after `get_session_updates` returns `is_done: true`, because you need the `answer_id` values from completed answer updates. -* Collect all updates where type is answer across every poll of `get_session_updates`. Each one produces an `answer_id` you can include in the dashboard. -* The `note_tile` should summarize the full analysis. It is the first thing a viewer sees on the dashboard. -* Multiple answers from the same session or across multiple sessions can be combined into a single dashboard. +Create a ThoughtSpot dashboard and save it, so that users can revisit or share the results. SpotterViz, the ThoughtSpot dashboard designer, builds the dashboard. Use this tool when a user asks for a dashboard or Liveboard, asks to save analysis results, or wants to recreate a dashboard from another tool. + +You can call the tool in two ways: + +. *From completed analysis*: Pass `answers` collected from `get_session_updates`, with optional `instructions` for layout and style. SpotterViz organizes, styles, and saves the charts. Call this only after `get_session_updates` returns `is_done: true`, because you need the answer ID values from completed answer updates. +. *From a description*: Pass `instructions` that describe the dashboard. Use this when the user asks for a dashboard before any analysis, or wants one recreated from a specification. In this case, do not run the analysis first. SpotterViz replies with `needs_input`, which contains the data source it chose and its plan. Nothing is built until the user confirms the plan. + +Dashboard creation can take a few minutes, so the call can return `in_progress` before the dashboard is ready. === Input parameters +Pass `answers`, `instructions`, or both. [cols="2,4", options="header"] |==== |Field|Description -|`title` |Required. Title of the dashboard to be created. -|`answers`|Required. List of answer objects to add to the dashboard. Each answer requires an `answer_id` (from `get_session_updates` where `type` is `answer`) and a `title`. -|`note_tile`| Required. An HTML summary of the analysis and answers, rendered as a styled tile on the dashboard. Must be a single line with no line breaks. Use `
` for spacing within the HTML. Include emojis, colors, and a `"Generated on