SCAL-314115 filters

visual-embed/update-filters-and-params/.env

@@ -0,0 +1,5 @@
+VITE_THOUGHTSPOT_HOST=https://training.thoughtspot.cloud
+VITE_THOUGHTSPOT_USERNAME=code-sandbox
+VITE_THOUGHTSPOT_PASSWORD="3mbed+#3xplz"
+VITE_THOUGHTSPOT_LIVEBOARD_ID=6dabda7b-5392-4d47-ba26-17e8244cbcaf
+VITE_THOUGHTSPOT_VIZ_ID=8d2e93ad-cae8-4c8e-a364-e7966a69a41e

visual-embed/update-filters-and-params/.gitignore

@@ -0,0 +1,25 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+!.env

visual-embed/update-filters-and-params/.stackblitzrc

@@ -0,0 +1,11 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm run dev",
+  "env": {
+    "VITE_THOUGHTSPOT_HOST": "https://training.thoughtspot.cloud",
+    "VITE_THOUGHTSPOT_USERNAME": "code-sandbox",
+    "VITE_THOUGHTSPOT_PASSWORD": "3mbed+#3xplz",
+    "VITE_THOUGHTSPOT_LIVEBOARD_ID": "6dabda7b-5392-4d47-ba26-17e8244cbcaf",
+    "VITE_THOUGHTSPOT_VIZ_ID": "8d2e93ad-cae8-4c8e-a364-e7966a69a41e"
+  }
+}

visual-embed/update-filters-and-params/README.md

@@ -0,0 +1,156 @@
+<!-- search-meta
+tags: [filters, parameters, runtime-filters, runtime-parameters, host-events, useHostEventsV2, subscribed-event, timing, UpdateFilters, UpdateRuntimeFilters, UpdateParameters, React, TypeScript]
+apis: [runtimeFilters, runtimeParameters, HostEvent, UpdateRuntimeFilters, UpdateFilters, UpdateParameters, RuntimeFilterOp, RuntimeParameter, subscribedEvent, useHostEventsV2, LiveboardEmbed, SearchEmbed, useEmbedRef, trigger, on]
+questions:
+  - How do I apply filters programmatically on an embedded Liveboard or Search?
+  - How do I update filters on a ThoughtSpot embed after it has loaded?
+  - How do I pass runtime parameters when embedding a Liveboard?
+  - How do I update runtime parameters on an embedded Liveboard from my app?
+  - What payload does HostEvent.UpdateParameters expect?
+  - Should I use runtimeFilters or HostEvent.UpdateFilters to set filters?
+  - What is the difference between UpdateRuntimeFilters and UpdateFilters?
+  - Why is HostEvent.UpdateFilters not firing or not working in my embed?
+  - When is it safe to trigger a host event after the embed loads?
+  - How do I use subscribedEvent to know a host event is ready?
+  - Do I need useHostEventsV2 for the Subscribed embed event to fire?
+  - How do I update runtime filters from a button in my app?
+-->
+
+# update-filters-and-params
+
+Working patterns and a decision guide for applying **filters and parameters** to embedded ThoughtSpot content programmatically — at init via `runtimeFilters` / `runtimeParameters`, and after load via the `UpdateRuntimeFilters`, `UpdateFilters`, and `UpdateParameters` host events, including the `subscribedEvent` readiness pattern (requires `useHostEventsV2: true`).
+
+## Which mechanism to use
+
+| Your situation | Use | Since |
+|---|---|---|
+| Filters/parameters are known when you render the embed | **`runtimeFilters`** / **`runtimeParameters`** view-config options — simplest, no events, no timing concerns | SDK 1.9.0 |
+| Filters change after load (button, external UI) | **`HostEvent.UpdateRuntimeFilters`** — array of `{ columnName, operator, values }` | SDK 1.9.0 / TS 8.1.0.cl |
+| Updating values of a filter that already exists on the Liveboard | **`HostEvent.UpdateFilters`** — `{ filters: [{ column, oper, values }] }` | SDK 1.23.0 / TS 9.4.0.cl |
+| Parameter values change after load | **`HostEvent.UpdateParameters`** — array of `{ name, value, isVisibleToUser? }` | SDK 1.29.0 / TS 10.1.0.cl |
+| You need the exact moment a host event is safe to trigger | **`embed.subscribedEvent(HostEvent.X)`** listener — **only fires when `useHostEventsV2: true` is set in the embed view config** | SDK 1.45.2+ / TS 26.3.0.cl+ |
+
+Good to know:
+
+- **`UpdateRuntimeFilters` resets the embedded object to its original state** before applying the new conditions — user changes such as drill-downs are cleared.
+- If multiple columns share a name, disambiguate with the `WORKSHEET_NAME::COLUMN_NAME` format in `UpdateFilters` (e.g. `"(Sample) Retail - Apparel::city"`).
+- **Common pitfall:** wiring the `Subscribed` readiness listener **without** enabling `useHostEventsV2` — the listener silently never fires. On clusters older than 26.3.0.cl, trigger from `EmbedEvent.Load`/`EmbedEvent.Data` instead, guarded so it runs once.
+
+## Key Usage
+
+```typescript
+import {
+  AuthType,
+  HostEvent,
+  RuntimeFilterOp,
+  init,
+  type EmbedEvent,
+} from "@thoughtspot/visual-embed-sdk";
+import { LiveboardEmbed, useEmbedRef } from "@thoughtspot/visual-embed-sdk/react";
+import { useEffect } from "react";
+
+// init() must run BEFORE any embed component mounts — call it at module scope.
+// (The useInit hook runs in a parent effect, which fires AFTER child effects,
+// so the embed can construct before init and fail with "Please provide a valid URL".)
+init({
+  thoughtSpotHost: "https://your-instance.thoughtspot.cloud",
+  authType: AuthType.None,
+});
+
+const App = () => {
+  const embedRef = useEmbedRef<typeof LiveboardEmbed>();
+
+  // AFTER LOAD — update runtime filters from your app's UI.
+  // Note: resets the object to its original state (drills are cleared) before applying.
+  const updateRuntimeFilters = () => {
+    embedRef.current?.trigger(HostEvent.UpdateRuntimeFilters, [
+      { columnName: "state", operator: RuntimeFilterOp.EQ, values: ["michigan"] },
+    ]);
+  };
+
+  // AFTER LOAD — update values of filters that already exist on the Liveboard.
+  // Disambiguate duplicate column names with "WORKSHEET_NAME::COLUMN_NAME".
+  const updateExistingFilters = () => {
+    embedRef.current?.trigger(HostEvent.UpdateFilters, {
+      filters: [{ column: "item type", oper: "IN", values: ["shoes", "boots"] }],
+    });
+  };
+
+  // AFTER LOAD — update Parameter values (SDK 1.29.0+ / TS 10.1.0.cl+).
+  const updateParameters = () => {
+    embedRef.current?.trigger(HostEvent.UpdateParameters, [
+      { name: "Discount", value: 0.25, isVisibleToUser: true },
+    ]);
+  };
+
+  // READINESS — fires the moment the embedded app has registered its handler for
+  // the host event, so triggering is guaranteed safe.
+  // REQUIRES useHostEventsV2: true on the embed (see props below) — without the
+  // flag this "<Event> Subscribed" signal NEVER fires.
+  useEffect(() => {
+    const embed = embedRef.current;
+    if (!embed) return;
+    const subscribed = embed.subscribedEvent(HostEvent.UpdateFilters) as EmbedEvent;
+    const onReady = () => {
+      embed.trigger(HostEvent.UpdateFilters, {
+        filters: [{ column: "date", oper: "EQ", values: ["JULY", "2023"], type: "MONTH_YEAR" }],
+      });
+    };
+    embed.on(subscribed, onReady);
+    return () => {
+      embed.off(subscribed, onReady);
+    };
+  }, []);
+
+  return (
+    <>
+      <button onClick={updateRuntimeFilters}>Update runtime filters</button>
+      <button onClick={updateExistingFilters}>Update existing filters</button>
+      <button onClick={updateParameters}>Update parameters</button>
+      <LiveboardEmbed
+        ref={embedRef}
+        liveboardId="your-liveboard-id"
+        // AT INIT — filters/parameters known upfront: pass them in the view config.
+        // Prefer this whenever possible; no events or timing involved.
+        runtimeFilters={[
+          { columnName: "state", operator: RuntimeFilterOp.EQ, values: ["california"] },
+        ]}
+        runtimeParameters={[{ name: "Discount", value: 0.1 }]}
+        // Required for the subscribedEvent readiness pattern (SDK 1.45.2+ / TS 26.3.0.cl+).
+        useHostEventsV2
+      />
+    </>
+  );
+};
+```
+
+## Documentation
+
+- [Runtime filters](https://developers.thoughtspot.com/docs/runtime-filters)
+- [Runtime parameters](https://developers.thoughtspot.com/docs/runtime-parameters)
+- [Filter types and application layers](https://developers.thoughtspot.com/docs/filters-overview)
+- [Using host events](https://developers.thoughtspot.com/docs/host-events)
+- [HostEvent reference](https://developers.thoughtspot.com/docs/Enumeration_HostEvent)
+
+## Demo
+
+Open in [StackBlitz](https://stackblitz.com/github/thoughtspot/developer-examples/tree/main/visual-embed/update-filters-and-params)
+
+## Run locally
+
+```
+$ git clone https://github.com/thoughtspot/developer-examples
+$ cd visual-embed/update-filters-and-params
+```
+```
+$ npm i
+```
+```
+$ npm run dev
+```
+
+### Technology labels
+
+- React
+- Typescript
+- Web

visual-embed/update-filters-and-params/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/ts-logo.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>ThoughtSpot React + Update filters and parameters</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>