diff --git a/modules/ROOT/pages/developer-playground.adoc b/modules/ROOT/pages/developer-playground.adoc index b02bfdd71..3394c7bd4 100644 --- a/modules/ROOT/pages/developer-playground.adoc +++ b/modules/ROOT/pages/developer-playground.adoc @@ -17,7 +17,6 @@ You can explore the following SDK components in the Playground. * xref:developer-playground.adoc#playground-visualization[Visualizations] * xref:developer-playground.adoc#playground-fullapp[Full application] - [#playground-search] == Search To explore the Search embed function: @@ -215,6 +214,10 @@ searchOptions: { } ---- +a|**Set runtime filters and parameters** + + +include::{path}/set-runtime-overrides.adoc[] + a|**Modify available actions** + include::{path}/modify-available-actions.adoc[] @@ -234,7 +237,6 @@ For more information about CSS variables, styles, and customizations options, se | |==== - [#playground-visualization] == Visualization To explore the visualization embedding function: diff --git a/modules/ROOT/pages/embed-ai-analytics.adoc b/modules/ROOT/pages/embed-ai-analytics.adoc index 6765aeae0..91109f804 100644 --- a/modules/ROOT/pages/embed-ai-analytics.adoc +++ b/modules/ROOT/pages/embed-ai-analytics.adoc @@ -6,21 +6,21 @@ :page-pageid: embed-ai-search-analytics :page-description: To embed ThoughtSpot Spotter and conversational analytics experience in your app, you can use the `SpotterEmbed` or `SpotterAgentEmbed` SDK library. -ThoughtSpot Spotter provides an interactive AI-powered Search and conversation analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis. +ThoughtSpot Spotter provides an interactive AI-powered Search and conversational analytics experience for its application users. With ThoughtSpot Spotter, users can query data in plain language, ask follow-up questions, and get insights directly from their data. ThoughtSpot also provides an agentic version of Spotter for a more advanced experience with context-based conversations and responses for deeper analysis. == Embed components -For embedding applications, ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in their app: +ThoughtSpot provides two distinct SDK libraries to embed Spotter capabilities in your app: * xref:embed-spotter.adoc[`SpotterEmbed`] + -To embed the full Spotter interface with a conversation panel that allows natural language text strings, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component. +To embed the full Spotter interface with a conversation panel that allows natural language queries, data source selection, and interactions with AI-generated Answers, use the `SpotterEmbed` component. For more information, see xref:embed-spotter.adoc[Embed Spotter]. * xref:embed-spotter-agent.adoc[`SpotterAgentEmbed`] + -The Spotter Agent embedding, also known as `bodyless` embed, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over the look and feel and workflow of the embedded analytics experience. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations. +The Spotter Agent embedding, also known as `bodyless` embedding, allows you to integrate natural language data search and analysis into your own applications or chatbot. Unlike the standard Spotter embed, which provides a ready-made search bar and interface, the `SpotterAgentEmbed` component is designed for deeper customization, allowing full control over user experience and workflow of embedded analytics. It allows you to build your own UI or agent experience, route user questions to ThoughtSpot, and receive structured answers and visualizations. [NOTE] ==== * The `ConversationEmbed` and `BodylessConversation` components are deprecated and replaced with `SpotterEmbed` and `SpotterAgentEmbed` respectively in Visual Embed SDK v1.38.0 and later. -* If you are embedding full ThoughtSpot experience in your app via `AppEmbed`, you must enable new home page experience and set the home page search bar mode to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding]. +* If you are embedding the full ThoughtSpot experience in your app via `AppEmbed`, you must set the search bar mode on the home page to `aiAnswer` to view Spotter components. For more information, see xref:full-app-customize.adoc#_include_spotter_interface[Customize full application embedding]. ==== == Spotter embed and Spotted Agent embed comparison @@ -58,11 +58,11 @@ a| * Supported data object is Model == Customization options in the SDK -Visual Embed SDK provides several view configuration settings and customization options for customizing Spotter embeds: +Visual Embed SDK provides several configuration settings and controls for customizing Spotter embed view: -* Configuration properties to enable or disable features. +* Configuration properties that enable or disable features. For more information, see xref:_spotterembedviewconfig.adoc[SpotterEmbedViewConfig] and xref:SpotterAgentEmbedViewConfig.adoc[SpotterAgentEmbedConfig] -* Action customization framework to show or hide actions in the embedded view + +* The action customization framework to show or hide actions in the embedded view + For more information, see xref:Action.adoc[Action] and xref:embed-action-ref.adoc[Action IDs in the SDK] * Event handlers for host and embed app interaction + For more information, see xref:EmbedEvent.adoc[Embed events], xref:HostEvent.adoc[Host events], and xref:embed-events.adoc[Events and app interactions] diff --git a/modules/ROOT/pages/mcp-integration.adoc b/modules/ROOT/pages/mcp-integration.adoc index 52642aa44..af40cd213 100644 --- a/modules/ROOT/pages/mcp-integration.adoc +++ b/modules/ROOT/pages/mcp-integration.adoc @@ -1,4 +1,4 @@ -= Agentic MCP server integration += MCP server integration :toc: true :toclevels: 3 @@ -6,7 +6,7 @@ :page-pageid: mcp-integration :page-description: Learn how to use the ThoughtSpot Model Context Protocol (MCP) server to interact with ThoughtSpot data via MCP tools and AI APIs and get relevant questions and answers for a given query and create Liveboards at runtime. -ThoughtSpot’s Agentic Multi-Client Protocol (MCP) Server allows integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools to interact with ThoughtSpot’s data and its analytics capabilities programmatically. +ThoughtSpot’s Agentic Multi-Client Protocol (MCP) Server enables integrating ThoughtSpot analytics directly into any AI agent, custom chatbot, or LLM-based systems and platforms that support MCP. It acts as a connector between the ThoughtSpot instance and external AI client, and provides a set of tools for interacting with ThoughtSpot’s data and its analytics capabilities programmatically. The MCP tools of the Agentic MCP Server support the following functions: @@ -17,40 +17,40 @@ The MCP tools of the Agentic MCP Server support the following functions: == Integration overview -The Agentic MCP server integration requires the following core components and authentication framework: +The Agentic MCP Server integration requires the following core components and authentication framework: -MCP server:: -The MCP server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP server can be hosted by ThoughtSpot or by customers in their own environment. +MCP Server:: +The MCP Server provides a tools wrapper with a discoverable interface for agentic analytics. It exposes a set of tools to external agents to interact with ThoughtSpot's resources, data, and analytical capabilities. The MCP Server includes an orchestration layer that determines which tools to invoke based on the incoming queries and user intent. The MCP Server can be hosted by ThoughtSpot or by customers in their own environment. MCP tools, resources, and AI APIs:: -MCP tools are the actions that the MCP server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP server supports the following tools: +MCP tools are the actions that the MCP Server exposes to the agent for interaction with ThoughtSpot. Currently, the MCP Server supports the following tools: * `ping` to test connection to ThoughtSpot * `getRelevantQuestions` to get relevant analytical questions + -The `getRelevantQuestions` tool calls `/api/rest/2.0/ai/relevant-questions/` API and gets relevant data questions for a given data context by breaking down a user's query. +The `getRelevantQuestions` tool calls xref:spotter-apis.adoc#_get_relevant_questions[/api/rest/2.0/ai/relevant-questions/] API and gets relevant data questions for a given data context by breaking down a user's query. * `getAnswer` to execute the queries and fetch data + -The `getAnswer` tool calls `/api/rest/2.0/ai/agent/converse/sse` API and generates answers and insights for a given data context. +The `getAnswer` tool calls xref:spotter-apis.adoc#_send_a_question_and_generate_streaming_responses[/api/rest/2.0/ai/agent/converse/sse] API and generates answers and insights for a given data context. * `createLiveboard` to create a Liveboard in ThoughtSpot + The `createLiveboard` tool calls the Liveboard creation workflow and creates a Liveboard with the answers generated from user's query. * `getDataSourceSuggestions` to get data source suggestions + -Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. +Based on the type of data that users want to fetch, `getDataSourceSuggestions` gets a list of data source recommendations. Currently, `getDataSourceSuggestions` is not exposed as an MCP tool and is available as an MCP `resource`. To get data source suggestions, the user or MCP client must have at least view access to ThoughtSpot data sources. MCP host/client:: -The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP server, and enables agentic workflows. +The external system or application environment with AI Agent, Claude, OpenAI, or a custom chatbot that acts as a user interface, orchestrates interaction with ThoughtSpot MCP Server, and enables agentic workflows. Configuration settings to enable the integration:: Integration requires configuration, typically via a config file, to specify server addresses, credentials, and other connection details. Authentication and security settings:: * Access to ThoughtSpot instance: + -For MCP server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + +For MCP Server connection, users require access to a ThoughtSpot instance. ThoughtSpot administrators can use the SSO framework with SAML or OAuth token-based authentication methods to authenticate and sign in the users. + To get answers to their data queries, your application users require at least view access to ThoughtSpot data sources. To generate an Answer or to create Liveboard, users * CSP and CORS settings: + -To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. +To secure communication between the MCP client and the ThoughtSpot instance, administrators must add the MCP Server URL to CSP (Content Security Policy) and CORS (Cross-Origin Resource Sharing) allowlists in ThoughtSpot. * SAML redirect settings: + For SAML SSO users, the SAML redirect domain configuration is required to ensure that users are redirected to an allowed and trusted domain after they are authenticated. * Client connection configuration: + -MCP server integration also requires configuration on the client side, typically via a config file, to include the MCP server addresses, credentials, and other details. +MCP Server integration also requires configuration on the client side, typically via a config file, to include the MCP Server addresses, credentials, and other details. === How it works @@ -59,46 +59,46 @@ When the MCP Server integration is enabled, your host app connects to ThoughtSpo . User initiates a request. + The user sends a query to get data from a specific ThoughtSpot data model or context. . AI agent receives the request and discovers the MCP tools + -The agent discovers MCP tools available in its environment and processes the request to the MCP server, specifying the data model or context and the user's query. -. MCP server receives the request and executes actions via tools + -The MCP server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. -. The MCP server sends the response to the MCP host. +The agent discovers MCP tools available in its environment and processes the request to the MCP Server, specifying the data model or context and the user's query. +. MCP Server receives the request and executes actions via tools + +The MCP Server executes tools and triggers API requests to ThoughtSpot to break down the user's query into relevant questions, get information for the specified data context, or create an artifact. +. The MCP Server sends the response to the MCP host. . The agent receives the response and constructs the output + -The agent receives the response from the MCP host and presents it to the user +The agent receives the response from the MCP host, constructs the output, and presents it to the user. . User receives the response + The user can refine the analysis or choose a direction for further exploration. + For example, after receiving relevant questions and answer, the user can send follow-up questions or send a Liveboard creation request. -The following figure illustrates the sequence of workflows in a typical MCP server integration setup: +The following figure illustrates the sequence of workflows in a typical MCP Server integration setup: [.widthAuto] image::./images/mcp-integration.png[MCP integration] -== Get started with the integration -To get started with the integration, complete the steps described in the following sections. In this article, we'll integrate ThoughtSpot MCP server with Claude and enable agentic interaction and workflows. +== Get started +To get started with the integration, complete the steps described in the following sections. In this article, we'll integrate ThoughtSpot MCP Server with Claude and enable agentic interaction and workflows. === Before you begin Before you begin, verify if your application setup has the following: -* Node.js version 22 or later is installed on your system. +* Node.js version 22 or later is installed. * A ThoughtSpot instance with 10.11.0.cl or later release version. You'll need administrator credentials to configure security settings or set up token-based authentication for your application users. -* Your application users require at least view access to the data source objects to query data and get answers. +* Your application users have at least view access to the data source objects to query data and get answers. * Row-level and column-level security rules are configured for data security and access control. === Configure security settings on ThoughtSpot -To allow the secure communication between the MCP server and your ThoughtSpot instance, configure the following settings: +To allow the secure communication between the MCP Server and your ThoughtSpot instance, configure the following settings: . On your ThoughtSpot instance, navigate to *Develop* > *Customizations* > *Security Settings*. -. Add the MCP server domain to CSP and CORS allowlists. -. If your setup uses SAML SSO logins, add the MCP server domain to the SAML redirect domain allowlist. +. Add the MCP Server domain to CSP and CORS allowlists. +. If your setup uses SAML SSO logins, add the MCP Server domain to the SAML redirect domain allowlist. -=== Add MCP server to the MCP client's config +=== Add MCP Server to the MCP client's config -If your MCP client supports remote MCP servers, add the MCP server URL to the client's config file. +If your MCP client supports remote MCP Servers, add the MCP Server URL to the client's config file. -MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP servers. In such a case, add the URL with arguments shown in this example: +MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote MCP Servers. In such a case, add the URL with arguments shown in this example: [source,JSON] ---- @@ -118,10 +118,10 @@ MCP clients such as Claude Desktop, Windsurf, and Cursor do not support remote M After updating the config file: -. Connect to ThoughtSpot instance and complete authentication. +. When prompted to connect your ThoughtSpot instance, add the URL of your application instance and complete authentication. . Restart your MCP client to load the new configuration. + -If the connection is successful, you'll see an option to add data context from ThoughtSpot. + +If the connection is successful, you'll see an option to connect to ThoughtSpot and choose the data context. + For example, the Claude Desktop shows the *Add to ThoughtSpot* as shown in the following figure: + [.bordered] @@ -140,7 +140,7 @@ You can adjust tool access, resources, instructions to data models, object permi === Verify the query and response workflow -* Select a datasource to set the context of your query. + +* Select a data source to set the context of your query. + For example, on Claude Desktop, click the `+` icon and select a data source. + @@ -170,18 +170,18 @@ image::./images/create-lb-claude.png[Liveboard creation] == Configuration considerations and best practices -* Users must have access to the data source. If not, it will lead to empty results. +* Users must have at least view access to the data source. Otherwise, it may lead to empty results. * Ensure that data is modeled. Large or complex data sources may impact response time. -* Streaming responses require client support for real-time updates. Ensure that the system is available. +* Streaming responses require client support for real-time updates. Ensure that your system is available to receive and process data. * Each conversation is session-based. Ensure that session IDs are managed correctly in your integration. == Additional resources * Check the link:https://github.com/thoughtspot/mcp-server[MCP Server GitHub repo, window=_blank] for implementation instructions. -* Check your MCP client's documentation for instructions on how to connect to MCP servers. +* Check your MCP client's documentation for instructions on how to connect to MCP Servers. * To understand ThoughtSpot agentic analytics capabilities and AI APIs, refer to the following documentation: ** link:https://docs.thoughtspot.com/cloud/latest/spotter[Spotter Documentation] ** link:https://docs.thoughtspot.com/cloud/latest/spotter-agent[Spotter Agent Documentation] ** xref:spotter-apis.adoc[Spotter AI APIs] -* In case of issues with connection or authentication, check the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^] \ No newline at end of file +* In case of issues with connection or authentication, refer to the link:https://github.com/thoughtspot/mcp-server?tab=readme-ov-file#troubleshooting[troubleshooting steps^]. \ No newline at end of file diff --git a/modules/ROOT/pages/runtime-filters.adoc b/modules/ROOT/pages/runtime-filters.adoc index 9711498ff..81cec2c87 100644 --- a/modules/ROOT/pages/runtime-filters.adoc +++ b/modules/ROOT/pages/runtime-filters.adoc @@ -6,25 +6,44 @@ :page-pageid: runtime-filters :page-description: Apply filters to visualizations at runtime and pass them as URL parameters -Runtime filters provide the ability to apply filters to a Liveboard or Answer by passing filter properties as query parameters in a Liveboard or visualization URL. You can also apply runtime filters in REST API requests when querying data from a Liveboard, Answer, or a visualization object. On embedded instances, you can use the Visual Embed SDK to apply filters to an embedded Liveboard or Answer object, and also update filters using events. +Runtime filters allow you to apply filters on a Liveboard, Answer, visualization, or conversation session with Spotter. These filters are not persistent filters saved in the object, but are applied dynamically at runtime. You can use runtime filters to pre-filter content for your application users based on context and embedding app's requirements. -== How runtime filters work +== Overview -The runtime filters can be specified in the ThoughtSpot object URL as query parameters. When you apply a runtime filter to a Liveboard, ThoughtSpot will try to find a matching column in the Liveboard visualizations to filter data. The runtime filter requires the following attribute-value pairs. +Runtime filters can be applied using one of the following options: + +* Via Visual Embed SDK + +Use the `runtimeFilters` property in the Visual Embed SDK for embedded objects. + +The SDK also provides host events to update filters. +* Via REST APIs +Use REST API requests to apply runtime overrides on Liveboard, Answer, or visualization data. +* Via URL query parameters + +Pass filter properties as query parameters in the URL. + +[IMPORTANT] +==== +* The runtime filters operation returns an error if the URL exceeds 2000 characters. +* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. +==== + +=== Runtime filter properties + +A runtime filter consists of the following attributes: column name:: -__String__. Name of the column to filter by. For example, `item type` or `product`. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, and as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. +__String__. Name of the column to filter on. For example, `item type` or `product`. This attribute is defined as `col1`, `col2`, `col3` in the object URLs and REST API requests, and as `columnName` in the `runtimeFilters` array in the Visual Embed SDK. operator:: __String__. The xref:runtime-filters.adoc#rtOperator[runtime filter operator]. For example, `EQ` or `IN`. In the Visual Embed SDK, operators are specified as xref:runtime-filters.adoc#runtimeFilterOp[`operator`] in the `runtimeFilters` array, whereas in the object URLs and REST API requests, you can define the operator as `op1`, `op2`, and `op3`. values:: -__String, Integer, or Boolean__. The list of operands. For example, if the column name is defined as `State`, the value can be the name of the state like `Michigan`. +__String, Integer, or Boolean__. The values to filter by. For example, if the column name is defined as `State`, the value can be the name of the state like `Michigan`. + This attribute is defined as `val1`, `val2`, `val3` in the object URLs and REST API requests, and as `values` in the `runtimeFilters` array in the Visual Embed SDK. + Some operators like `EQ` and `LE` accept a single operand, whereas `BW_INC_MAX`, `BW_INC_MIN`, `BW_INC`, `BW`, and `IN` accept multiple operands. + === Supported data types You can apply filters on these data types: @@ -118,44 +137,56 @@ new Date('2020-05-22').getTime() / 1000 |multiple |=== -== Apply runtime filters on embedded objects - -If you are xref:embed-without-sdk.adoc[embedding a Liveboard or visualization without using the Visual Embed SDK], you can append the filters in the embedded object URL as shown in these examples: - ----- -https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}/{visualization_id} ----- - ----- -https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan&col2=product&op2=BEGINS_WITH&val2=Travel#/embed/viz/{Liveboard_id}/{visualization_id} ----- -=== Runtime filters in Visual Embed SDK +== Runtime filters in Visual Embed SDK -If you are embedding Spotter, Liveboard, visualization or the full application using xref:VisualEmbedSdk.adoc[Visual Embed SDK], you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. +If you are embedding Spotter, Liveboard, visualization or the full application using Visual Embed SDK, you can apply filters using the `runtimeFilters` property. In the full app embed mode, ThoughtSpot applies runtime filters on all Liveboard, visualization, and Answer objects in the embedded app. The following example shows how to apply runtime filters on an embedded visualization in the SDK. Here, the runtime filter is operating on the `Revenue` column to filter the data matching `100000`. +[source,JavaScript] ---- -liveboardEmbed.render({ +const liveboardEmbed = new LiveboardEmbed('#tsEmbed', { + ... // other embed view config liveboardId: '133e6c5f-e522-41a0-b0ad-b9c3b066e276', vizId: '28b73b4a-1341-4535-ab71-f76b6fe7bf92', - runtimeFilters: [{ - columnName: 'Revenue', - operator: RuntimeFilterOp.EQ, - values: ['100000' ] - }] - }); + runtimeFilters: [{ + columnName: 'Revenue', + operator: RuntimeFilterOp.EQ, + values: ['100000'] + }] +}); ---- -==== Apply multiple runtime filters in the SDK +In the following example, runtime filters are applied on a Spotter conversation session with a pre-defined search query string: + +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#tsEmbed', { + ... // other embed view config + worksheetId: "cd252e5c-b552-49a8-821d-3eadaa049cca", + searchOptions: { + searchQuery: 'sales data for west coast', + }, + runtimeFilters: [{ + columnName: 'Item type', + operator: RuntimeFilterOp.EQ, + values: ['jackets'] + }] +}); +---- + +Spotter applies the specified filters to the data and returns an answer for the initial query passed in the embed code. Unless the filters are explicitly overridden, runtime filters will continue to be applied to all answers generated for subsequent queries within the same conversation session. + +=== Applying multiple runtime filters The following examples show how to apply multiple runtime filters on Liveboard visualizations using the SDK: [#multiRuntimeFilters] [source,JavaScript] ---- -liveboardEmbed.render({ +const liveboardEmbed = new LiveboardEmbed('#tsEmbed', { + ... // other embed view config liveboardId: '543619d6-0015-4667-b257-eff547d13a12', runtimeFilters: [{ columnName: 'item type', // eg: color @@ -209,7 +240,6 @@ runtimeFilters: [{ ] ---- - [#runtimeFilterOp] === Runtime filter operator examples @@ -226,14 +256,11 @@ a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'state', - operator: RuntimeFilterOp.EQ, - values: ['california'] - }] -}); + runtimeFilters: [{ + columnName: 'state', + operator: RuntimeFilterOp.EQ, + values: ['california'] + }] ---- | `NE` + @@ -241,14 +268,11 @@ Not exactly or Not equal to + Number of values allowed: 1 a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'item type', - operator: RuntimeFilterOp.NE, - values: ['jackets'] - }] -}); + runtimeFilters: [{ + columnName: 'item type', + operator: RuntimeFilterOp.NE, + values: ['jackets'] + }] ---- | `LT` + @@ -258,14 +282,11 @@ Number of values allowed: 1 a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.LT, - values: ['1000000'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.LT, + values: ['1000000'] + }] ---- | `LE` + @@ -274,14 +295,11 @@ Number of values allowed: 1 a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.LE, - values: ['5000000'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.LE, + values: ['5000000'] + }] ---- | `GT` + @@ -290,14 +308,11 @@ Number of values allowed: 1 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.GT, - values: ['1000000'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.GT, + values: ['1000000'] + }] ---- | `GE` + greater than or equal to + @@ -305,14 +320,11 @@ Number of values allowed: 1 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.GE, - values: ['5000000'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.GE, + values: ['5000000'] + }] ---- | `CONTAINS` + @@ -321,14 +333,11 @@ Number of values allowed: 2 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'item type', - operator: RuntimeFilterOp.CONTAINS, - values: ['Bags'] - }] -}); + runtimeFilters: [{ + columnName: 'item type', + operator: RuntimeFilterOp.CONTAINS, + values: ['Bags'] + }] ---- See also, xref:runtime-filters.adoc#_and_and_or_conditions_in_filters[AND/OR conditions in filters], for information about the AND and OR condition for filters. @@ -339,15 +348,11 @@ Number of values allowed: 1 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'product', - operator: RuntimeFilterOp.BEGINS_WITH, - values: ['travel'] - }], - -}); + runtimeFilters: [{ + columnName: 'product', + operator: RuntimeFilterOp.BEGINS_WITH, + values: ['travel'] + }], ---- | `ENDS_WITH` + @@ -355,14 +360,11 @@ ends with + Number of values allowed: 1 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'item type', - operator: RuntimeFilterOp.ENDS_WITH, - values: ['shirts'] - }] -}); + runtimeFilters: [{ + columnName: 'item type', + operator: RuntimeFilterOp.ENDS_WITH, + values: ['shirts'] + }] ---- | `BW_INC_MAX` + @@ -370,14 +372,11 @@ between inclusive of the higher value + Number of values allowed: 2 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.BW_INC_MAX, - values: ['25','30'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.BW_INC_MAX, + values: ['25', '30'] + }] ---- | `BW_INC_MIN` + @@ -385,14 +384,11 @@ between inclusive of the lower value + Number of values allowed: 2 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'revenue', - operator: RuntimeFilterOp.BW_INC_MIN, - values: ['25','50'] - }] -}); + runtimeFilters: [{ + columnName: 'revenue', + operator: RuntimeFilterOp.BW_INC_MIN, + values: ['25', '50'] + }] ---- | `BW_INC` + @@ -401,14 +397,11 @@ Number of values allowed: 2 + a| [source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'sales', - operator: RuntimeFilterOp.BW_INC, - values: ['10','50'] - }] -}); + runtimeFilters: [{ + columnName: 'sales', + operator: RuntimeFilterOp.BW_INC, + values: ['10', '50'] + }] ---- | `BW` + @@ -416,14 +409,11 @@ between non-inclusive + Number of values allowed: 2 + a|[source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'sales', - operator: RuntimeFilterOp.BW, - values: ['25','50'] - }] -}); + runtimeFilters: [{ + columnName: 'sales', + operator: RuntimeFilterOp.BW, + values: ['25', '50'] + }] ---- |`IN` + @@ -431,33 +421,25 @@ is included in this list of values + Number of values allowed: multiple a|[source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'item type', - operator: RuntimeFilterOp.IN, - values: ['jackets', 'bags', 'shirts'] - }] -}); + runtimeFilters: [{ + columnName: 'item type', + operator: RuntimeFilterOp.IN, + values: ['jackets', 'bags', 'shirts'] + }] ---- |`NOT_IN` + is not included in this list of values a|[source,JavaScript] ---- -liveboardEmbed.render({ - liveboardId: '543619d6-0015-4667-b257-eff547d13a12', - runtimeFilters: [{ - columnName: 'item type', - operator: RuntimeFilterOp.NOT_IN, - values: ['skirts', 'bags'] - }] -}); + runtimeFilters: [{ + columnName: 'item type', + operator: RuntimeFilterOp.NOT_IN, + values: ['skirts', 'bags'] + }] ---- - - |===== -==== Example video +==== Example The following video shows how to apply multiple runtime filters on a Liveboard. @@ -472,21 +454,21 @@ video::./images/runtime-filters.mp4[width=100%,options="autoplay,loop"] -- === Adjust runtime filters using SDK events -Runtime filters can be set prior to the load within the link:https://developers.thoughtspot.com/docs/Interface_LiveboardViewConfig#_runtimefilters[configuration object] of the loaded embed component: +Runtime filters can be set prior to the load within the xref:LiveboardViewConfig.adoc#_runtimefilters[configuration object] of the loaded embed component: [source,JavaScript] ---- - const embed = new LiveboardEmbed('#embed-container', { + const liveboardEmbed = new LiveboardEmbed('#embed-container', { ... // other options runtimeFilters: [{ - columnName: 'value', + columnName: 'state', operator: RuntimeFilterOp.EQ, - values: ['string' | 123 | true], + values: ['california'], }, ], }) ---- -After loading the embedded object, runtime filters can be adjusted using the `HostEvent.UpdateRuntimeFilters` event: +After loading the embedded object, runtime filters can be adjusted using the xref:HostEvent.adoc#_updateruntimefilters[`HostEvent.UpdateRuntimeFilters`] event: [source,JavaScript] ---- @@ -505,75 +487,32 @@ liveboardEmbed.trigger(HostEvent.UpdateRuntimeFilters, [{ [NOTE] ==== -In Spotter embed, updating filters via host and embed events may not work. +Spotter embed does not support updating filters via host and embed events. ==== -For more information, see xref:HostEvent.adoc#_updateruntimefilters[UpdateRuntimeFilters] and xref:embed-events.adoc#_filters_in_embedded_ui[Filters in embedded UI]. +=== Apply runtime filters on embedded objects without the SDK -=== URL format when embedding without SDK +If you are xref:embed-without-sdk.adoc[embedding a Liveboard or visualization without using the Visual Embed SDK], you can append the filters in the embedded object URL as shown in these examples: -If embedding a ThoughtSpot Liveboard without the SDK, ensure that add the runtime filters before `#/path` in the URL as shown in the following example: ---- https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}/{visualization_id} ---- -For more information, see xref:embed-without-sdk.adoc[Embed without SDK]. - -== Apply runtime filters via REST APIs - -=== REST API v1 endpoints - -To apply runtime filters on a Liveboard object in a REST API request, add the runtime filters to the API request URL as shown here: - -.URL format ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id={Liveboard_id}&col1={column-name}&op1={operator}&val1={value} ----- - -.Example ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&col1=State&op1=EQ&val1=California ----- - -The following example shows how to apply a runtime filter on a visualization object of a Liveboard: - -.URL format ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id={Liveboard_id}&vizid={visualization_id}&col1={column-name}&op1={operator}&val1={value} ----- - -.Example ----- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=543619d6-0015-4667-b257-eff547d13a12&vizid=%5B%224ff5b939-453d-40ff-8fc2-a1d972047c86%22%5D&col1=State&op1=EQ&val1=California ----- - -The following is another example of a REST API request URL with a filter. Here the runtime filter is operating on the column `Category` and returning values that are equal to `mfgr%2324`. - ---- -https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata? -id=e36ee65e-64be-436b-a29a-22d8998c4fae&col1=Category -&op1=EQ&val1=mfgr%2324 +https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan&col2=product&op2=BEGINS_WITH&val2=Travel#/embed/viz/{Liveboard_id}/{visualization_id} ---- -==== Apply additional filters - -You can add additional filters by incrementing the number at the end of each parameter in the runtime filter for each filter you add, for example, col2, op2, val2, and so on. To add additional filters on a particular column, you can specify multiple values by separating them with an ampersand (&) as shown in the example here: +==== URL format when embedding without SDK +If embedding a ThoughtSpot Liveboard without the SDK, ensure that add the runtime filters before `#/path` in the URL as shown in the following example: ---- -val1=foo&val1=bar +https://{ThoughtSpot-Host}/?embedApp=true&col1=State&op1=EQ&val1=michigan#/embed/viz/{Liveboard_id}/{visualization_id} ---- -You can also use the `IN` operator for multiple values, as shown in this example: - ----- -col1=&op1=IN&val1=&val1= ----- +For more information, see xref:embed-without-sdk.adoc[Embed without SDK]. -The following example passes multiple variables to a single column as well as multiple columns. It shows that the data values are returned as epochs. ----- -col1=region&op1=IN&val1=midwest&val1=south&val1=northeast&col2=date&op2=BET&val2=&val2= ----- +== Runtime filters via REST APIs === REST API v2.0 endpoints @@ -719,6 +658,60 @@ curl -X POST \ }' ---- +=== REST API v1 endpoints + +To apply runtime filters on a Liveboard object in a REST API request, add the runtime filters to the API request URL as shown here: + +.URL format +---- +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id={Liveboard_id}&col1={column-name}&op1={operator}&val1={value} +---- + +.Example +---- +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&col1=State&op1=EQ&val1=California +---- + +The following example shows how to apply a runtime filter on a visualization object of a Liveboard: + +.URL format +---- +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id={Liveboard_id}&vizid={visualization_id}&col1={column-name}&op1={operator}&val1={value} +---- + +.Example +---- +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata?id=543619d6-0015-4667-b257-eff547d13a12&vizid=%5B%224ff5b939-453d-40ff-8fc2-a1d972047c86%22%5D&col1=State&op1=EQ&val1=California +---- + +The following is another example of a REST API request URL with a filter. Here the runtime filter is operating on the column `Category` and returning values that are equal to `mfgr%2324`. + +---- +https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/pinboarddata? +id=e36ee65e-64be-436b-a29a-22d8998c4fae&col1=Category +&op1=EQ&val1=mfgr%2324 +---- + +==== Apply additional filters + +You can add additional filters by incrementing the number at the end of each parameter in the runtime filter for each filter you add, for example, col2, op2, val2, and so on. To add additional filters on a particular column, you can specify multiple values by separating them with an ampersand (&) as shown in the example here: + +---- +val1=foo&val1=bar +---- + +You can also use the `IN` operator for multiple values, as shown in this example: + +---- +col1=&op1=IN&val1=&val1= +---- + +The following example passes multiple variables to a single column as well as multiple columns. It shows that the data values are returned as epochs. + +---- +col1=region&op1=IN&val1=midwest&val1=south&val1=northeast&col2=date&op2=BET&val2=&val2= +---- + == Apply runtime filters on a Liveboard or visualization URL The following examples show the runtime filter query string in a Liveboard URL: @@ -727,12 +720,12 @@ 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 ---- -You can apply multiple filters in the same URL as shown in this example: +You can apply multiple filters in the same URL, as shown in this example: ---- https://{ThoughtSpot-Host}/?col1=State&op1=EQ&val1=California&col2=product&op2=BEGINS_WITH&val2=Travel#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a ---- -You can also apply multiple filters with multiple values as shown in this example: +You can also apply multiple filters with multiple values, as shown in this example: ---- https:///?col1=State&op1=IN&val1=California&val1=Michigan&col2=item%20type&op2=EQ&val2=Jackets#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a ---- @@ -743,15 +736,6 @@ https://{ThoughtSpot-Host}/?col1=State&op1=EQ&val1=California&col2=product&op2=B ---- //// - -[IMPORTANT] -==== -* The runtime filters operation returns an error if the URL exceeds 2000 characters. -* Ensure that you add the runtime filter parameters in the URL before `#/` in the URL, so that the parameters persist. -* Attempting to override existing filter values with runtime filters while exporting a Liveboard will result in an error. -==== - - == Limitations of runtime filters * The `DATE` and `DATE_TIME` data types must be specified as EPOCH time (Unix or POSIX time) in runtime filters. diff --git a/modules/ROOT/pages/runtime-overrides.adoc b/modules/ROOT/pages/runtime-overrides.adoc index 5a55702a4..0be6ea207 100644 --- a/modules/ROOT/pages/runtime-overrides.adoc +++ b/modules/ROOT/pages/runtime-overrides.adoc @@ -10,28 +10,27 @@ You can apply filters and adjust Parameter values on ThoughtSpot Liveboards and === Runtime filters -The runtime filters layer allows setting filter rules on Liveboards and Answers prior to load. +xref:runtime-filters.adoc[Runtime filters] allows setting filter rules on embedded objects dynamically at runtime. Developers can set runtime filters in the Visual Embed SDK for the following embed components: -* link:https://developers.thoughtspot.com/docs/Interface_LiveboardViewConfig[LiveboardEmbed] -* link:https://developers.thoughtspot.com/docs/Interface_SearchViewConfig[SearchEmbed] -* link:https://developers.thoughtspot.com/docs/Interface_AppViewConfig[AppEmbed] +* xref:LiveboardViewConfig.adoc[LiveboardEmbed] +* xref:SpotterEmbedViewConfig.adoc[SpotterEmbed] +* xref:SearchViewConfig.adoc[SearchEmbed] +* xref:AppViewConfig.adoc[AppEmbed] -After the object loads, runtime filters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateruntimefilters[HostEvent.UpdateRuntimeFilters] event. - -For more information and examples, see xref:runtime-filters.adoc[Runtime filters]. +After the object loads, runtime filters can be xref:runtime-filters.adoc#_adjust_runtime_filters_using_sdk_events[adjusted using the SDK events]. == Runtime Parameters Parameters allow users to visualize data by running different scenarios with adjustable values. You can use Parameters within formulas when analyzing your data via Search, Liveboards, or Answers. -Like runtime filters, Parameters can be applied on ThoughtSpot Liveboards and Answers prior to load. Developers can set runtime Parameters in the Visual Embed SDK for the following embed components: +Like runtime filters, xref:runtime-parameters.adoc[Parameters] can be applied on ThoughtSpot objects at runtime. Developers can set runtime Parameters in the Visual Embed SDK for the following embed components: -* link:https://developers.thoughtspot.com/docs/Interface_LiveboardViewConfig[LiveboardEmbed] -* link:https://developers.thoughtspot.com/docs/Interface_SearchViewConfig[SearchEmbed] -* link:https://developers.thoughtspot.com/docs/Interface_AppViewConfig[AppEmbed] +* xref:LiveboardViewConfig.adoc[LiveboardEmbed] +* xref:SpotterEmbedViewConfig.adoc[SpotterEmbed] +* xref:SearchViewConfig.adoc[SearchEmbed] +* xref:AppViewConfig.adoc[AppEmbed] -After the object loads, Parameter values can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event. +After the object loads, Parameter values can be link:runtime-parameters.adoc#_adjust_parameter_values_using_sdk_events[adjusted using the SDK events]. -For more information and examples, see xref:runtime-parameters.adoc[Runtime Parameters]. diff --git a/modules/ROOT/pages/runtime-parameters.adoc b/modules/ROOT/pages/runtime-parameters.adoc index 326be6db7..08b47f4eb 100644 --- a/modules/ROOT/pages/runtime-parameters.adoc +++ b/modules/ROOT/pages/runtime-parameters.adoc @@ -6,25 +6,26 @@ :page-pageid: runtime-params :page-description: Use Parameters to run multiple scenarios with adjustable values, without changing your answer. -ThoughtSpot lets you create Parameters in a Model and integrate them into formulas, filters, data queries, and Liveboards. +Parameters in ThoughtSpot are typically used for "what-if" analysis, scenario planning, or to personalize data views without modifying the underlying data object. You can link:https://docs.thoughtspot.com/cloud/latest/parameters-create[create Parameters^] in a Model and integrate them into formulas, filters, data queries, and Liveboards. You can also link:https://docs.thoughtspot.com/cloud/latest/parameters-use[use Parameters^] within formulas when querying your data via Search, Liveboards, Answers, or Spotter sessions. -== About Parameters -Parameters are useful for "what-if" analysis, financial planning, cohort analysis, and so on. Parameters allow users to visualize data by running different scenarios with adjustable values. With Parameters, business users can use a single report and adjust the values dynamically to fit the scenario they want to analyze. +== Overview +Runtime parameters in ThoughtSpot are dynamic values that can be set or overridden at the time of accessing a Liveboard, Answer, visualization, or Spotter session. -You can use Parameters within formulas when querying your data via Search, Liveboards, or Answers. For more information about creating and using Parameters, see the following articles in ThoughtSpot product documentation. +Runtime parameters can be applied using one of the following options: -* link:https://docs.thoughtspot.com/cloud/latest/parameters-use[Using Parameters, window=_blank] -* link:https://docs.thoughtspot.com/cloud/latest/parameters-create[Creating Parameters, window=_blank] +* Via Visual Embed SDK + +Use the `runtimeParameters` property in the Visual Embed SDK for embedded objects. + +The SDK also provides host events to update Parameters. +* Via RETS APIs + +Use REST API requests to apply runtime overrides on Liveboard, Answer, or visualization data. +* Via URL query parameters + +Pass Parameter name and values as query parameters in the URL. - -[NOTE] -==== -Applying Parameter overrides on a Liveboard or Answer via URL, Visual Embed SDK, or REST API hides the filter chips on the Liveboard or Answer page. However, the overrides will be applied to charts and tables. -==== +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. === Supported data types -You can apply runtime Parameters on these data types: +You can apply runtime Parameters on the following data types: * VARCHAR * BIGINT @@ -49,13 +50,14 @@ new Date('2020-05-22').getTime() / 1000 == Apply Parameter overrides in Visual Embed SDK -The Visual Embed SDK v1.25.0 and later support Parameter overrides on embedded Liveboards and Answers. Before applying a Parameter override on an Answer or Liveboard object, make sure the Parameters and associated formulas are configured in the Model used for generating charts and tables. +The Visual Embed SDK supports runtime Parameter overrides on embedded Liveboards, Answers, and Spotter-generated answers. Before applying a Parameter override on any object, make sure the Parameters and associated formulas are configured in the data Model used for generating charts and tables. -The following example shows how to apply multiple runtime filters on a Liveboard embedded using the SDK: +The following examples show how to apply multiple runtime filters in the embed code: [source,JavaScript] ---- -liveboardEmbed.render({ +const liveboardEmbed = new LiveboardEmbed('#tsEmbed', { + ... // other embed view config liveboardId: '543619d6-0015-4667-b257-eff547d13a12', runtimeParameters:[{ name: "Date List Param", @@ -68,6 +70,35 @@ liveboardEmbed.render({ }); ---- +[source,JavaScript] +---- +const spotterEmbed = new SpotterEmbed('#tsEmbed', { + ... // other embed view config + worksheetId: "cd252e5c-b552-49a8-821d-3eadaa049cca", + searchOptions: { + searchQuery: 'sales data for west coast', + }, + runtimeParameters: [{ + name: "Date List Param", + value: 1662361200 + }, + { + name: "Integer Range Param", + value: 5 + } + ] +}); +---- + +Note the following behavior in Spotter embedding: + +* Saving or pinning an answer does not retain the Parameter. Instead, only the Parameter value is stored. +* In future releases, saved chats will also not retain the Parameter. +* Users can see the Parameter value in formulas in edit mode, but only the value set for them will be visible. +* Parameter values cannot be changed during a conversation session and may result in unintended effects. +* If a user adds a Parameter to an answer through the edit flow, Spotter may drop this Parameter and any formulas using it in follow-up interactions. This means Parameters added in this way are not guaranteed to persist in subsequent conversational steps. + +=== Adjust Parameter values using SDK events After loading the embedded object, Parameters can be adjusted using the link:https://developers.thoughtspot.com/docs/Enumeration_HostEvent#_updateparameters[HostEvent.UpdateParameters] event: [source,JavaScript] @@ -82,118 +113,39 @@ liveboardEmbed.trigger(HostEvent.UpdateParameters, [{ } ]) ---- -=== Runtime Parameters in Spotter Embed - -* Saving or pinning an answer does not retain the parameter itself; only the parameter value is stored. In future releases, saved chats will also not retain the parameter, just the value. -* Users can see the parameter value in formulas, but only the value set for them is visible. Parameter values cannot be changed in the middle of a conversation session and may result in unintended effects. -* If a user adds a parameter to an answer through the edit flow, Spotter may drop this parameter and any formulas using it in follow-up interactions. This means parameters added in this way are not guaranteed to persist in subsequent conversational steps. [NOTE] ==== In Spotter embed, updating Parameters via host and embed events may not work. ==== -== Runtime parameters in object URLs - -You can apply overrides to Parameter values at runtime and visualize data with the adjusted values. Like runtime filters, you can append the Parameter attribute to the object URLs and modify the resulting output. - -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: +=== Show or hide Parameter chips in embedded sessions +Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from ThoughtSpot's UI, while in other cases you may want to show the chips. -.Liveboard ----- -https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a ----- +==== Hide Parameter chips +To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page by using one of the following methods: -.Saved Answer ----- -https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/saved-answer/3e84d95c-986e-4154-8362-3807906dad50 ----- +* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK (Recommended) +* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) -.Search data ----- -https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/answer/ ----- +To update the parameter's value once the page is loaded, use `HostEvent.UpdateParameters`. The Parameter chip will remain hidden, however its value in ThoughtSpot's visualizations will be updated accordingly. +==== Show Parameter chip in ThoughtSpot UI +To show the parameter chip from ThoughtSpot's user interface, update the Parameter's value with `HostEvent.UpdateParameters` after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. -[IMPORTANT] -==== -ThoughtSpot returns an error if an object URL with Parameter attributes exceeds 2000 characters. -==== +[width="100%" cols="5,5,8"] +[options='header'] +|===== +|Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` +|Hidden|Yes| Possible +|Shown| No| Possible +|===== == Apply Parameter overrides via REST API You can apply Parameter overrides to a Liveboard or Answer using REST v1 and v2 API endpoints. Before applying a Parameter override on a Liveboard or Answer object, ensure that the Parameters are configured in the source Model. -=== REST API v1 -You can apply runtime Parameters when sending an API request to the following v1 Data API endpoints: - -* `/tspublic/v1/pinboarddata` (Liveboard data API) -* `/tspublic/v1/searchdata` (Search data API) - -==== Liveboard data - -To apply overrides to a Liveboard via REST API, add Parameters to the xref:pinboarddata.adoc[Liveboard data API] request URL as shown in the example here: - ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=86bedf72-c718-49cc-9f49-6e8870233f35&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=Double%20list%20param¶mVal1=0 ----- - -If the API request is valid, overrides are applied to the Liveboard data, and ThoughtSpot returns the requested data in the API response. - -[source,JSON] ----- -{ - "adfaa348-755b-4b95-94ff-220c94c0c8b6": { - "columnNames": [ - "Ship Mode", - "Total Tax", - "Adjusted Tax" - ], - "data": [ - [ - "fob", - 7, - 0.0 - ], - [ - "mail", - 2, - 0.0 - ] - ], - "samplingRatio": 1.0, - "totalRowCount": 2, - "rowCount": 2, - "pageSize": 100000, - "offset": 0, - "name": "Parameters Answer" - } -} ----- - -==== Search data - -To apply overrides on an Answer obtained from a new search query, append the Parameter attributes to the xref:search-data-api.adoc[search data API] request URL as shown here: - ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?query_string=%20%5BTax%5D%5BShip%20Mode%5D&data_source_guid=540c4503-5bc7-4727-897b-f7f4d78dd2ff&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=Double%20list%20param¶mVal1=0 ----- - -==== Add additional Parameters - -You can add additional Parameters in the URL by incrementing the number for each Parameter attribute; for example, param1, param2, paramVal1, paramVal2, and so on. To add additional overrides, specify the values by separating them with an ampersand (&) as shown in the examples here: - -.URL ----- -https://{ThoughtSpot-host}/?param1=double%20list%20param¶mVal1=0¶m2=double%20param¶mVal2=0#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a ----- - -.REST API request ----- -https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=double%20list%20param¶mVal1=0¶m2=double%20param¶mVal2=0 ----- - === REST API v2 You can apply runtime Parameters when sending an API request to the following v2 API endpoints: @@ -311,27 +263,100 @@ curl -X POST \ }' ---- -== Show or hide Parameter chips in embedded sessions -Parameter values can be set or overridden using multiple methods. In some use cases, you may want to hide the Parameter chips from ThoughtSpot's UI, while in other cases you may want to show the chips. +=== REST API v1 +You can apply runtime Parameters when sending an API request to the following v1 Data API endpoints: -=== Hide Parameter chips -To hide the parameter chip in ThoughtSpot's UI, initialize a Parameter override before loading ThoughtSpot's page by using one of the following methods: +* `/tspublic/v1/pinboarddata` (Liveboard data API) +* `/tspublic/v1/searchdata` (Search data API) -* Use the `runtimeParameters` option in ThoughtSpot's Visual Embed SDK (Recommended) -* Apply a Parameter override directly in the URL (if you are not using Visual Embed SDK) +==== Liveboard data -To update the parameter's value once the page is loaded, use `HostEvent.UpdateParameters`. The Parameter chip will remain hidden, however its value in ThoughtSpot's visualizations will be updated accordingly. +To apply overrides to a Liveboard via REST API, add Parameters to the xref:pinboarddata.adoc[Liveboard data API] request URL as shown in the example here: -== Show Parameter chip in ThoughtSpot UI -To show the parameter chip from ThoughtSpot's user interface, update the Parameter's value with `HostEvent.UpdateParameters` after the page has loaded. The Parameter chip will then be shown and updated with each new value passed via the event. +---- +https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=86bedf72-c718-49cc-9f49-6e8870233f35&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=Double%20list%20param¶mVal1=0 +---- -[width="100%" cols="5,5,8"] -[options='header'] -|===== -|Parameter chip|Initialized via `runtimeParameters` or URL parameter? |Update via `HostEvent.UpdateParameters` -|Hidden|Yes| Possible -|Shown| No| Possible -|===== +If the API request is valid, overrides are applied to the Liveboard data, and ThoughtSpot returns the requested data in the API response. + +[source,JSON] +---- +{ + "adfaa348-755b-4b95-94ff-220c94c0c8b6": { + "columnNames": [ + "Ship Mode", + "Total Tax", + "Adjusted Tax" + ], + "data": [ + [ + "fob", + 7, + 0.0 + ], + [ + "mail", + 2, + 0.0 + ] + ], + "samplingRatio": 1.0, + "totalRowCount": 2, + "rowCount": 2, + "pageSize": 100000, + "offset": 0, + "name": "Parameters Answer" + } +} +---- + +==== Search data + +To apply overrides on an Answer obtained from a new search query, append the Parameter attributes to the xref:search-data-api.adoc[search data API] request URL as shown here: + +---- +https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/searchdata?query_string=%20%5BTax%5D%5BShip%20Mode%5D&data_source_guid=540c4503-5bc7-4727-897b-f7f4d78dd2ff&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=Double%20list%20param¶mVal1=0 +---- + +==== Add additional Parameters + +You can add additional Parameters in the URL by incrementing the number for each Parameter attribute; for example, param1, param2, paramVal1, paramVal2, and so on. To add additional overrides, specify the values by separating them with an ampersand (&) as shown in the examples here: + +.URL +---- +https://{ThoughtSpot-host}/?param1=double%20list%20param¶mVal1=0¶m2=double%20param¶mVal2=0#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a +---- + +.REST API request +---- +https://{ThoughtSpot-host}/callosum/v1/tspublic/v1/pinboarddata?id=e36ee65e-64be-436b-a29a-22d8998c4fae&batchsize=-1&pagenumber=-1&offset=-1&formattype=COMPACT¶m1=double%20list%20param¶mVal1=0¶m2=double%20param¶mVal2=0 +---- + +== Apply runtime overrides via URL query parameters + +You can apply overrides to Parameter values at runtime and visualize data with the adjusted values. Like runtime filters, you can append the Parameter attribute to the object URLs and modify the resulting output. + +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: + +.Liveboard +---- +https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/pinboard/d084c256-e284-4fc4-b80c-111cb606449a +---- + +.Saved Answer +---- +https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/saved-answer/3e84d95c-986e-4154-8362-3807906dad50 +---- + +.Search data +---- +https://{ThoughtSpot-host}/?param1=Discount¶mVal1=0.25#/answer/ +---- + +[IMPORTANT] +==== +ThoughtSpot returns an error if an object URL with Parameter attributes exceeds 2000 characters. +==== == Parameters and JWT tokens Parameters work differently when used in JWT tokens to secure values for users. @@ -356,3 +381,5 @@ User interactions with the filter chip will be ignored due to Parameter value de |===== + + diff --git a/modules/ROOT/pages/spotter-apis.adoc b/modules/ROOT/pages/spotter-apis.adoc index 0efe06fdb..622bc2a10 100644 --- a/modules/ROOT/pages/spotter-apis.adoc +++ b/modules/ROOT/pages/spotter-apis.adoc @@ -966,4 +966,4 @@ Reason provided by the LLM to explain why each data source was recommended. == Additional resources * See REST API v2 Playground to verify the request and response workflows -* For information MCP tools, see xref:_mcp_server_integration[MCP server integration] \ No newline at end of file +* For information MCP tools, see xref:mcp-integration.adoc[MCP server integration] \ No newline at end of file diff --git a/modules/ROOT/pages/theme-builder.adoc b/modules/ROOT/pages/theme-builder.adoc index 3572283ec..82231f07a 100644 --- a/modules/ROOT/pages/theme-builder.adoc +++ b/modules/ROOT/pages/theme-builder.adoc @@ -1,4 +1,4 @@ -= Theme builder += Theme builder [beta betaBackground]^Beta^ :toc: true :toclevels: 2 @@ -6,17 +6,18 @@ :page-pageid: theme-builder-doc :page-description: Understanding how to use the theme builder -Theme Builder[beta betaBackground]^Beta^ provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. +Theme Builder provides a graphical interface to explore the CSS customization options that are currently available for various ThoughtSpot components. You can try out these style customization options and get a preview of the desired look and feel before applying these changes to the ThoughtSpot components in your application environment. -In the current version, Theme Builder supports style customization options for embed components such as Liveboard, visualization, Search data page, and full ThoughtSpot app experience. The Theme Builder playground also provides an option to download and upload CSS variables with custom values in JSON format. +In the current version, Theme Builder supports style customization options for embed components such as Liveboard, visualization, Search data page, Spotter and full ThoughtSpot app experience. The Theme Builder playground also provides an option to import and export CSS variables with custom values in JSON format. -To access Theme Builder, click *Live Playgrounds* > *Theme Builder* [beta betaBackground]^Beta^ on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. +//To access Theme Builder, go to *Develop* tab > *Customisations* and click *Theme Builder*. +Click *Live Playgrounds* > *Theme Builder* on this documentation site, or go to link:https://developers.thoughtspot.com/docs/theme-builder[https://developers.thoughtspot.com/docs/theme-builder, window=_blank]. == Try out styles and load changes To try out the customization options: -. Go to link:https://developers.thoughtspot.com/docs/theme-builder[Theme Builder]. +. Go to link:https://developers.thoughtspot.com/docs/theme-builder[*Theme Builder*, window=_blank]. . Choose the desired embed component from the dropdown on the left panel. + [.bordered] @@ -25,37 +26,37 @@ image::./images/tb-embed.png[Embed components menu] . Select the UI element or property to customize. For instance, if you want to edit the background color of the context menu, then click the dropdown for the *Context Menu*. Click on the text box for *Background* and select your desired color. + +If you want to the exact variable name of the element as in ThoughtSpot, hover over the name of the element in the left panel. ++ [.bordered] [.widthAuto] image::./images/tb-style-menu.png[Style components menu] -. To view the style customizations you just applied, click *Load Changes* in the top-right corner. + -Alternatively, you can also choose *Realtime loading* checkbox in the top-right corner. If you choose this, -the iframe refreshes automatically on each customization with your selected input. +. You will see the style customizations you just applied in real time, as the iframe refreshes automatically on each customization with your selected input. -== Download CSS variables in JSON format +== Export CSS variables in JSON format To download a copy of the CSS variables in JSON: -. In the Theme Builder Playground, click *Save JSON*. + +. In the Theme Builder Playground, click *Export JSON*. + . To copy the CSS variables, click *Copy JSON*. -. To download the JSON to your local directory, click *Download*. +. To download the JSON to your local directory, click *Export*. -The CSS variables in the JSON have default values. You can edit the JSON to add custom specifications as per your Organization's branding guidelines and upload the customized JSON to review the changes. +You can use this exported JSON to implement the style in your embedded ThoughtSpot instance. -== Upload CSS variables with custom specifications +== Import CSS variables with custom specifications To upload CSS variables JSON: -. In the Theme Builder Playground, click *Upload JSON* on the bottom of the left panel. +. In the Theme Builder Playground, click *Import JSON* on the bottom of the left panel. + -The Upload JSON modal opens. +The Import JSON modal opens. + [.bordered] [.widthAuto] -image::./images/json.png[JSON button] -. Paste the JSON with your custom specifications. -. Click *Submit*. + +image::./images/json.png[Import JSON button] +. Paste the JSON with your custom specifications. Currently, the Theme builder supports only the JSON styling variables. +. Click *Import*. + If there are no errors, a success message appears at the bottom left and the iframe refreshes with the applied JSON. == Additional resources diff --git a/modules/ROOT/pages/whats-new.adoc b/modules/ROOT/pages/whats-new.adoc index 32350c5d8..36e4fb5d5 100644 --- a/modules/ROOT/pages/whats-new.adoc +++ b/modules/ROOT/pages/whats-new.adoc @@ -34,10 +34,13 @@ With the introduction of these APIs, the following legacy API endpoints will be The above-listed AI endpoints will be available in the Playground until further notice. However, we recommend using the new APIs for better context management, extensibility, and integration options. //// -//// === Support for runtime overrides in Spotter embed -The Visual Embed SDK now supports runtime filters and Parameters. For more information, see xref:runtime-filters.adoc#_runtime_filters_in_visual_embed_sdk[Runtime filters] and xref:runtime-parameters.adoc#_apply_parameter_overrides_in_visual_embed_sdk[Runtime Parameters]. -//// +You can apply runtime filters and parameter overrides to Spotter sessions and interactions using the Visual Embed SDK. When these overrides are configured in the SDK, they are applied to the data used for Spotter queries, and the generated answers in these sessions will reflect the applied overrides. + +The Visual Embed SDK Playground for Spotter embedding includes an option to set runtime overrides. You can test and preview the results before updating your embed code. + +For more information, see xref:runtime-filters.adoc[Runtime filters] and xref:runtime-parameters.adoc[Runtime Parameters]. + === Full application embed experience * The new experience with a sliding navigation panel and modular home page is now available as an Early Access feature for ThoughtSpot embedded application users. diff --git a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx b/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx index 0adf04417..7fa3847f8 100644 --- a/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx +++ b/src/components/DevDocTemplate/playGround/ThemeBuilder.tsx @@ -2,7 +2,7 @@ import * as React from 'react'; import BackButton from '../../BackButton'; export const ThemeBuilder: React.FC = (props) => { - const playgroundUrl = 'https://thoughtspot-theme-builder-five.vercel.app/'; + const playgroundUrl = 'https://theme-builder-embed-prod.vercel.app/'; return (
diff --git a/static/doc-images/images/json.png b/static/doc-images/images/json.png index 4d9c9303d..fb10d001a 100644 Binary files a/static/doc-images/images/json.png and b/static/doc-images/images/json.png differ diff --git a/static/doc-images/images/mcp-integration.png b/static/doc-images/images/mcp-integration.png index 2d4b1e079..2dacbe322 100644 Binary files a/static/doc-images/images/mcp-integration.png and b/static/doc-images/images/mcp-integration.png differ diff --git a/static/doc-images/images/tb-embed.png b/static/doc-images/images/tb-embed.png index 9293632be..00791b88d 100644 Binary files a/static/doc-images/images/tb-embed.png and b/static/doc-images/images/tb-embed.png differ diff --git a/static/doc-images/images/tb-style-menu.png b/static/doc-images/images/tb-style-menu.png index e5c787465..26097bc09 100644 Binary files a/static/doc-images/images/tb-style-menu.png and b/static/doc-images/images/tb-style-menu.png differ