diff --git a/_data/shared_chrome.json b/_data/shared_chrome.json index c808ef3768..80ea191710 100644 --- a/_data/shared_chrome.json +++ b/_data/shared_chrome.json @@ -1,7 +1,7 @@ { "$schema": "https://www.metabase.com/shared/chrome.schema.json", "version": 1, - "generated_at": "2026-07-30T23:19:10+00:00", + "generated_at": "2026-07-31T22:12:10+00:00", "origin": "https://www.metabase.com", "stylesheets": [ { diff --git a/_docs/latest/configuring-metabase/config-template.md b/_docs/latest/configuring-metabase/config-template.md index 36e0b00ed8..bbb003039d 100644 --- a/_docs/latest/configuring-metabase/config-template.md +++ b/_docs/latest/configuring-metabase/config-template.md @@ -79,7 +79,6 @@ config: admin-email: null aggregated-query-row-limit: null ai-features-enabled: true - ai-usage-max-retention-days: null allowed-iframe-hosts: |- youtube.com, youtu.be, @@ -114,7 +113,6 @@ config: application-name: Metabase attachment-row-limit: null attachment-table-row-limit: 20 - audit-max-retention-days: null bcc-enabled: true breakout-bin-width: 10.0 breakout-bins-num: 8 @@ -179,7 +177,6 @@ config: http-channel-host-strategy: external-only humanization-strategy: simple index-update-thread-count: 2 - install-analytics-database: true jdbc-data-warehouse-connection-pool-checkout-timeout-ms: 0 jdbc-data-warehouse-connection-pool-max-pending-checkouts: 0 jdbc-data-warehouse-max-connection-pool-size: 15 @@ -239,7 +236,6 @@ config: llm-rate-limit-per-ip: 100 llm-rate-limit-per-user: 20 llm-request-timeout-ms: 60000 - load-analytics-content: true loading-message: doing-science login-page-illustration: default login-page-illustration-custom: null @@ -261,7 +257,6 @@ config: not-behind-proxy: false notification-link-base-url: null notification-system-event-thread-pool-size: 5 - notification-temp-file-size-max-bytes: 10485760 notification-thread-pool-size: 3 oidc-allowed-networks: allow-all oidc-providers: [] @@ -313,7 +308,6 @@ config: sdk-encryption-validation-key: null search-language: null search-typeahead-enabled: true - send-email-on-first-login-from-new-device: true send-new-sso-user-admin-email: null session-cookie-samesite: lax session-cookies: null @@ -321,7 +315,6 @@ config: setup-embedding-autoenabled: false setup-license-active-at-setup: false show-database-syncing-modal: null - show-google-sheets-integration: null show-homepage-data: true show-homepage-xrays: true show-metabase-links: true diff --git a/_docs/latest/configuring-metabase/environment-variables.md b/_docs/latest/configuring-metabase/environment-variables.md index 3446114f83..98e02a74f6 100644 --- a/_docs/latest/configuring-metabase/environment-variables.md +++ b/_docs/latest/configuring-metabase/environment-variables.md @@ -94,7 +94,7 @@ Whether AI features are enabled. - Type: integer - Default: `null` - [Exported as](../installation-and-operation/serialization): `ai-usage-max-retention-days`. -- [Configuration file name](./config-file): `ai-usage-max-retention-days` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely. @@ -303,6 +303,7 @@ Range: 1-100. To limit the total number of rows included in the file attachment - Type: string - Default: `null` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Number of days to retain data in audit-related tables. Minimum value is 30; set to 0 to retain data indefinitely. @@ -912,6 +913,7 @@ Number of threads to use for batched index updates, including embedding requests - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not we should install the Metabase analytics database on startup. Defaults to true, but can be disabled via environmment variable. @@ -1460,6 +1462,7 @@ Socket timeout in milliseconds for LLM API requests. - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not we should load Metabase analytics content on startup. Defaults to match `install-analytics-database`, which defaults to true, but can be disabled via environment variable. @@ -1662,6 +1665,7 @@ The size of the thread pool used to send system event notifications. - Type: integer - Default: `10485760` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). The maximum file size that will be created when storing notification query results on disk. Note this is in BYTES. Default value is 10485760 which is `10 * 1024 * 1024`. To disable this size limit set the @@ -2133,6 +2137,7 @@ Enable typeahead search in the Metabase navbar? - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Should we send users a notification email the first time they log in from a new device? (Default: true). This is currently only configurable via environment variable so users who gain access to an admin's credentials cannot @@ -2213,7 +2218,7 @@ Whether an introductory modal should be shown after the next database connection - Type: boolean - Default: `null` -- [Configuration file name](./config-file): `show-google-sheets-integration` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not to show the user a button that sets up Google Sheets integration. diff --git a/_docs/latest/embedding/chart.md b/_docs/latest/embedding/chart.md new file mode 100644 index 0000000000..44083e02f5 --- /dev/null +++ b/_docs/latest/embedding/chart.md @@ -0,0 +1,361 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: Embed a chart +source_url: 'https://github.com/metabase/metabase/blob/master/docs/embedding/chart.md' +layout: new-docs +summary: >- + Embed a single Metabase chart in your app, either view-only or interactive, + with a web component or using the React SDK. +redirect_from: + - /docs/latest/embedding/sdk/questions + - /docs/latest/embedding/question +latest: true +--- + +# Embed a chart + +There are two ways you can embed a chart (called a question, in Metabase parlance): + +- [View-only chart](#embed-a-view-only-chart): people see the results, filter them, and that's it. +- [Interactive chart](#embed-an-interactive-chart): people can drill through the chart and change the query behind it. + +To let people build questions from scratch instead, check out [Embed the query builder](./query-builder). To embed an AI chat component, check out [AI chat](./sdk/ai-chat). + +## Embed a view-only chart + +![Static question](./images/static-question.png) + +A view-only (a.k.a. "static") chart displays results without letting people explore the data. Nobody can drill through it, change the query behind it, or run a new one. You can, however, add editable filters that people can change to update the query results. + +View-only isn't tied to one kind of embed. You can make a chart view-only in any embedding type: + +- **[Guest embeds](./introduction#guest-embedding)**: always view-only. Nobody logs in to a guest embed, so Metabase has no account to check permissions against, and no way to tell whether a new query is one that person should be allowed to run. The published question is the only thing Metabase can safely run, which is why there's no drill-through or ad-hoc querying to turn off. +- **[SSO embeds](./introduction#sso-embeds)**: interactive out of the box. To make one view-only, turn off drill-through with `drills="false"` (web component) or `drills={false}` (SDK), and turn off saving with `is-save-enabled="false"` or `isSaveEnabled={false}`. You can also manage what people can do through [data permissions](../permissions/data) and [collection permissions](../permissions/collections). + +So pick your authentication based on what your app needs---plans, permissions, whether Metabase should know who's viewing---not on whether you want a view-only chart. Check out [SSO or guest embeds](./introduction#comparison-between-sso-and-guest-embeds). + +This section covers setting up a view-only chart with guest authentication. + +- [Web components](#view-only-charts-with-guest-authentication-using-a-web-component) +- [React SDK](#view-only-charts-using-the-react-sdk) + +### View-only charts with guest authentication using a web component + +You can use the in-app wizard to set up a view-only chart using web components. + +![In-app embedding wizard](./images/in-app-embedding-wizard.png) + +Before you start, an admin needs to [turn on guest embedding](./guest-embedding#turning-on-guest-embedding-in-metabase). + +Three things need to happen: you publish the embed in Metabase, you paste the chart code into your app, and your server signs a JWT. The wizard writes most of the code for you, so the list below is longer than the work. + +1. Visit the question in your Metabase. +2. Click the **Share** icon in the upper right. +3. Select **Embed** to open the embedding wizard. +4. For authentication, choose **Guest**, so your app won't need to log anyone in to your Metabase. +5. Click the **Publish** button. Publishing only applies to guest embeds. (There's nothing to publish for an SSO embed, because in that case people can explore the data based on their data and collection permissions.) +6. Under behavior, Metabase gives you several options for customizing how the embed works. See [web component attributes](./question-reference#metabase-question-web-component-attributes) for what each one does. If you'd picked SSO in step 4, this is where you'd make the embed view-only by turning off drill-through. +7. If you're embedding a SQL question with a variable, set the parameter to **Editable** or **Locked**. Parameters are **Disabled** by default, which hides them and prevents your server from setting them. See [Configuring parameters](./guest-embedding#configuring-parameters). +8. Customize the [appearance](./appearance). +9. Click the **Get code** button. You'll get both the frontend and backend code based on the selections you made in the wizard. +10. Copy the client code and paste it in your app. +11. Remove the hardcoded JWT tokens in your HTML. Fetch the token from your backend and pass the token to the component programmatically. + +To keep an embed alive after its token expires, configure a token endpoint with [`guestEmbedProviderUri`](./guest-embedding#refreshing-or-initializing-the-jwt-from-your-server). + +#### View-only chart example with web components + +Say you have a question written in SQL, with a field filter to filter orders by `customer_id`: + +```sql +{% raw %} +SELECT + * +FROM + orders +WHERE + {{customer_id}} +{% endraw %} +``` + +Now say you want to embed this question on each customer's account page in your app, showing only that customer's orders. Here's the frontend code. + +```html + + + + + + + + +``` + +The `theme` key sets the chart's appearance. For the full theme object with all the options, check out [Appearance](./appearance). + +On your app's server, set the value for the locked parameter in the token. Whoever's looking at the page can't see or change that value, so an embed on customer 13's account page returns only customer 13's orders. + +```js +// you will need to install via 'npm install jsonwebtoken' or in your package.json + +const jwt = require("jsonwebtoken"); + +// Get your key from your Metabase at +// /admin/embedding/guest -> Embedding secret key +const METABASE_SECRET_KEY = "YOUR_SECRET_KEY"; + +// Here we lock a customer_id parameter to 13 +const payload = { + resource: { question: 40956 }, + params: { + customer_id: [ + 13, // set this programmatically, based on whose account page your app is rendering + ], + }, + exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration +}; +const token = jwt.sign(payload, METABASE_SECRET_KEY); +``` + +To get this code from the in-app wizard, set the `customer_id` parameter to **Locked** and publish the question. See [Locked parameters](./guest-embedding#locked-parameters). + +For all modular embeds, you can also set a `locale` in your page-level configuration to [translate embedded content](./translations). + +For the full list of attributes, see [web component attributes](./question-reference#metabase-question-web-component-attributes). + +### View-only charts using the React SDK + +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} + +To embed a view-only chart with the [SDK](./sdk/introduction), use the `StaticQuestion` component. Wrap the component in the `MetabaseProvider` component with your auth config. + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/static-question.tsx" %} +``` + +The component has a default height, which you can change with the `height` prop. To inherit the height from the parent container, pass `100%`. + +For the full list of props, see [`StaticQuestion` props](./question-reference#staticquestion-props). + +## Embed an interactive chart + +{% include plans-blockquote.html feature="Interactive charts" convert_pro_link_to_embedding=true is_plural=true %} + +An interactive chart lets people explore their data: they can drill through the chart, filter results, summarize and group them, change visualization settings, and optionally save their changes. + +Interactive charts require SSO, which you can set up with either web components or the React SDK. + +- [Web components](#interactive-charts-using-a-web-component) +- [React SDK](#interactive-charts-using-the-react-sdk) + +### Interactive charts using a web component + +Reference an existing question by ID. [Drill-through](../questions/visualizations/drill-through) is on by default: + +```html + +``` + +You can pass a sequential ID like `1`, but an [entity ID](../installation-and-operation/serialization#entity-ids-work-with-embedding) is the better bet: entity IDs stay the same when you move content between instances, like from staging to production. + +To control what people can do with the chart, check out [web component attributes](./question-reference#metabase-question-web-component-attributes). For example, you can show or hide download buttons, the question's title, or the chart type selector. + +### Interactive charts using the React SDK + +Use `InteractiveQuestion` when you want people to explore their data and customize the layout. + +![Interactive question](./images/interactive-question.png) + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question.tsx" %} +``` + +For the full list of props, see [`InteractiveQuestion` props](./question-reference#interactivequestion-props). + +#### Customize the layout of an interactive chart + +`InteractiveQuestion` comes with a default layout that lets people view the question, apply filters and aggregations, and use the query builder. You can also build your own layout out of namespaced components like ``. For examples of both, see [Customizing an interactive chart's layout](./question-reference#customize-the-layout-of-an-interactive-chart), and the full list of [`InteractiveQuestion` components](./question-reference#interactivequestion-components). + +### Let people save their changes + +If you're using embeds with SSO, you can let people save their work. + +### Saving with web components + +With a web component, turn saving on with `is-save-enabled="true"`, and set the collection that saved questions land in with `target-collection`: + +```html + +``` + +### Saving with the React SDK + +With the SDK, you get four props to control saving questions: + +- `isSaveEnabled` shows or hides the save button. +- `onBeforeSave` runs before a save (it can be async). +- `onSave` runs after a successful save. It receives the updated question and a context object with `isNewQuestion`. +- `targetCollection` pre-selects the collection to save to and hides the collection picker. + +To prevent people from saving changes (or saving as a new question), set `isSaveEnabled={false}`: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/disable-question-save.tsx" %} +``` + +In the embedding wizard, this corresponds to the **Allow people to save new questions** option. + +## Customize what happens when someone clicks on a chart + +Customizing click behavior is only available in the [Modular embedding SDK](./sdk/introduction) for now. + +When people click a data point in an interactive chart, Metabase shows a menu of actions. The [`mapQuestionClickActions`](./sdk/plugins) plugin lets you customize this: open the default menu, add custom actions, or perform an immediate action without a menu. + +Use it globally on `MetabaseProvider`, or on individual `InteractiveQuestion` components: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question-click-actions.tsx" snippet="example" %} +``` + +You can also customize how custom actions look in the menu: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question-plugins.tsx" snippet="example" %} +``` + +## Embed the query builder or SQL editor + +To let people build questions from scratch, check out [Embed the query builder](./query-builder). + +## Control parameters from your app + +Say you want to show each customer only their own orders. How you filter the results depends on how you authenticate the embed. + +### Lock a parameter on a guest embed + +Embeds with **Guest** authentication can [lock a parameter](./guest-embedding#locked-parameters). Your app sets the parameter's value in the signed token on your server, so the filter is controlled by your app rather than by whoever's clicking around the page. They can't see the value, and they can't change it. An embed on a customer's account page returns that account's rows, whether or not Metabase has any idea who's looking at it. + +Locked parameters need a question written in SQL, with a [field filter or variable](../questions/native-editor/sql-parameters) to lock onto. Query builder questions have no parameters to lock, so segregate their data with permissions instead. + +```javascript +const payload = { + resource: { question: 5 }, + params: { + category: ["Gadget"], // Locked. Set by your app, not by whoever's viewing. + }, + exp: Math.round(Date.now() / 1000) + 10 * 60, +}; + +const token = jwt.sign(payload, METABASE_SECRET_KEY); +``` + +### Use permissions on an SSO embed + +Embeds with **SSO** don't need to lock parameters. Since Metabase knows who's viewing, you can apply [data permissions](../permissions/embedding) and let Metabase filter the rows, instead of locking parameters by hand. This works for query builder questions and SQL questions alike. + +### Set parameter values from your app + +You can also pass values to a question's [SQL parameters](../questions/native-editor/sql-parameters) in the format `{parameter_name: parameter_value}`, and keep your app in sync as people change them. Set the values once on load, or hold the values in your app and get a callback whenever they change. + +For both the SDK props (`initialSqlParameters`, `sqlParameters`, and `onSqlParametersChange`) and the web component equivalents, see [Modular embedding parameters](./parameters). + +### Hide a parameter + +To hide a parameter from the question's UI, use the [`hidden-parameters`](./question-reference#metabase-question-web-component-attributes) attribute (web component) or the `hiddenParameters` prop (SDK). Both require a Pro or Enterprise plan and an SSO embed; `hidden-parameters` has no effect on a guest embed. To hide a parameter on a guest embed, set the parameter to **Locked** or leave it **Disabled** in the question's embed settings. + +## Let people set up alerts on a question + +You can let people set up [alerts](../questions/alerts) on a saved question with the [`with-alerts`](./question-reference#metabase-question-web-component-attributes) attribute on the web component: + +```html + +``` + +Or by passing `withAlerts` to `StaticQuestion` or `InteractiveQuestion` in the SDK: + +```tsx + + + +``` + +Metabase only shows the alerts button when all of these are true: + +- Your Metabase has [email set up](../configuring-metabase/email). +- The embed is an authenticated (SSO) embed. +- The person viewing the embed is in a group with the [Subscriptions and alerts](../permissions/application#subscriptions-and-alerts) application permission. Metabase grants this permission to the All Users group by default, so admins have to set it to **No** to take it away. +- The person viewing the embed has [collection permissions](../permissions/collections) for the collection that holds the question. + +Alerts created in an embedded context only send to whoever's logged in, and they exclude links to Metabase items. + +## Customize chart appearance + +You can theme an embedded question and toggle parts of its UI. For the full set of theming options, see [Appearance](./appearance). For every attribute and prop, see the [Question component reference](./question-reference). + +- **Title**: show or hide the question title with `with-title` (web component) or `title` (SDK). +- **Downloads**: show or hide download buttons with `with-downloads` / `withDownloads`. Defaults to `true` on OSS/Starter and `false` on Pro/Enterprise. Disabling downloads requires a [Pro](/product/pro) or [Enterprise](/product/enterprise) plan. +- **Chart type selector**: show or hide it with `withChartTypeSelector` (SDK). +- **Theme**: set a light or dark preset, or (on Pro/Enterprise) customize colors and fonts. The `question` component in the theme has its own overrides: + +```js +{ + components: { + question: { + // Background color for all questions + backgroundColor: "#2E353B", + + // Toolbar of the default interactive question layout + toolbar: { + backgroundColor: "#F3F5F7", + }, + }, + }, +} +``` + +Colors set in a question's visualization settings override theme colors. + +### The "Powered by Metabase" banner + +Metabase adds a "Powered by Metabase" banner to guest embeds (both charts and dashboards) on the OSS and Starter plans. To remove the banner, upgrade to a [Pro](/product/pro) or [Enterprise](/product/enterprise) plan. + +## Further reading + +- [Question component reference](./question-reference) +- [Embed the query builder](./query-builder) +- [Appearance](./appearance) +- [Modular embedding parameters](./parameters) +- [Translating embeds](./translations) +- [Guest embeds](./guest-embedding) +- [Authentication](./authentication) +- [Modular embedding SDK](./sdk/introduction) +- [AI chat](./sdk/ai-chat) diff --git a/_docs/latest/embedding/components.md b/_docs/latest/embedding/components.md index c49ce9e2b8..f26eded6d9 100644 --- a/_docs/latest/embedding/components.md +++ b/_docs/latest/embedding/components.md @@ -56,26 +56,9 @@ If you surround your attribute value with double quotes, make sure to use single ## Question -To render a question (chart): - -```html - -``` - -You can also use the question component to create new questions: - -- `question-id="new"` — opens the visual query builder. -- `question-id="new-native"` — opens the SQL editor. - -For example, to embed the SQL editor: - -```html - -``` - -### Attributes - -{% include_file "{{ dirname }}/eajs/snippets/MetabaseQuestionAttributes.md" snippet="properties" %} +- [Embed a chart](./chart) +- [Embed a query editor](./query-builder) +- [Question component reference](./question-reference), for `` attributes and SDK props ## Browser diff --git a/_docs/latest/embedding/images/embedded-query-builder.png b/_docs/latest/embedding/images/embedded-query-builder.png new file mode 100644 index 0000000000..6e95764dda Binary files /dev/null and b/_docs/latest/embedding/images/embedded-query-builder.png differ diff --git a/_docs/latest/embedding/images/embedded-sql-editor.png b/_docs/latest/embedding/images/embedded-sql-editor.png new file mode 100644 index 0000000000..5a8675a3e2 Binary files /dev/null and b/_docs/latest/embedding/images/embedded-sql-editor.png differ diff --git a/_docs/latest/embedding/images/in-app-embedding-wizard.png b/_docs/latest/embedding/images/in-app-embedding-wizard.png new file mode 100644 index 0000000000..319f03bec1 Binary files /dev/null and b/_docs/latest/embedding/images/in-app-embedding-wizard.png differ diff --git a/_docs/latest/embedding/introduction.md b/_docs/latest/embedding/introduction.md index 039f5953b5..851853bdf3 100644 --- a/_docs/latest/embedding/introduction.md +++ b/_docs/latest/embedding/introduction.md @@ -18,11 +18,16 @@ latest: true # Embedding introduction -You can embed Metabase tables, charts, and dashboards—even Metabase's query builder—in your website or application. Here are the different ways you can embed Metabase: +You can embed Metabase tables, charts, dashboards, AI chat---even Metabase's query builder---in your website or application. -- [Modular embedding](#modular-embedding) -- [Full app embedding](#full-app-embedding) -- [Public links](#public-links-and-embeds) +There are two ways to embed Metabase. + +- **[Modular embedding](#modular-embedding)**: embed individual Metabase components, like questions, dashboards, and AI chat, so they seamlessly integrate with your app. +- **[Full app embedding](#full-app-embedding)**: embed the full Metabase app in an iframe, styled like your branding. + +Most people go with modular embedding, so you can integrate Metabase components into your app. + +If you just want to share a chart or dashboard with anyone who has the link, and you don't need any authentication, take a look at [public links and embeds](#public-links-and-embeds). ## Modular embedding @@ -30,21 +35,9 @@ With [modular embedding](./modular-embedding), you can embed individual Metabase You can use two different ways to authenticate modular embeds: -- [SSO](#modular-embedding) +- [SSO](#sso-embeds) - [Guest](#guest-embedding) -Here's a basic breakdown of what each auth type enables: - -| Component | SSO | Guest | -| ----------------------------------------------------- | --- | ----- | -| Chart | ✅ | ✅ | -| Chart with drill-through | ✅ | ❌ | -| Dashboard | ✅ | ✅ | -| Dashboard with drill-through | ✅ | ❌ | -| [Query builder](../questions/query-builder/editor) | ✅ | ❌ | -| Browser to navigate collections | ✅ | ❌ | -| Metabot AI chat | ✅ | ❌ | - ### SSO embeds With SSO, Metabase can know who's viewing what, which unlocks a lot of power. You can automatically apply [data permissions](../permissions/embedding), which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they're allowed to. @@ -53,52 +46,61 @@ With SSO, Metabase can know who's viewing what, which unlocks a lot of power. Yo If you're building a SaaS product with embedded analytics for multiple customers, you can keep customer data isolated with [Tenants](./tenants). +Accounts for these embedded users in your Metabase count toward the [accounts billed in your Metabase plan](/docs/latest/cloud/how-billing-works). But by letting your customers self-serve their data, you save time on developing bespoke charts. And you can charge _more_ for a premium analytics experience. If you plan on giving a lot of your customers self-service access to their data, you should consider an enterprise plan, with custom pricing that scales with your business. + ### Guest embedding [Guest embeds](./guest-embedding) are a secure way to embed charts and dashboards. Guest embedding works on all Metabase plans, including OSS and Starter. **When to use guest embeds**: simple embedding use cases where you don't want to offer ad-hoc querying or chart drill-through. To filter data relevant to the viewer, you can use guest embeds with [locked parameters](./guest-embedding#locked-parameters). -## Public links and embeds +### Set up modular embeds with web components or React -If you'd like to share your data with the good people of the internet, admins can create a [public link](./public-links) or embed a question or dashboard directly in your website. +Whichever way you authenticate, you can set up modular embeds two ways. -**When to use public links and embeds**: One-off charts and dashboards. Admins can use public links when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don't care who sees the data; you want to make the item available to everyone. +- **Web components**: a script tag plus HTML elements like ``. Web components have no build step and no framework requirement, so they work in plain HTML, Vue, Svelte, Rails, React, or any framework you like. Metabase's [in-app wizard](./modular-embedding) writes the code for you. +- **React SDK**: React components that you import and compose yourself. The [SDK](./sdk/introduction) gives you more control: you can build custom layouts and [customize behavior with plugins](./sdk/plugins). -## Full app embedding +If your app runs on React and you want that extra control, go with the SDK. Otherwise start with web components. You can always move to the SDK later. -[Full app embedding](./full-app-embedding) allows you to embed the entire Metabase app in an iframe, and integrate Metabase SSO with your app's authentication. +## Comparison between SSO and guest embeds + +All SSO options require a Pro or Enterprise plan. -## Comparison of embedding types - -| Action | [Modular SDK](./sdk/introduction) | [Modular SSO](./modular-embedding) | [Modular Guest](./guest-embedding) | [Full app](./full-app-embedding) | [Public](../embedding/public-links) | -| ------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------- | ------------------------------------- | ----------------------------------- | -------------------------------------- | -| Charts and dashboards | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Filter widgets](/glossary/filter-widget) | ✅ | ✅ | ✅ | ✅ | ✅ | -| Export results\* | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Locked filters](./static-embedding-parameters#restricting-data-in-a-static-embed-with-locked-parameters) | ❌ | ❌ | ✅ | ❌ | ❌ | -| [Data segregation](../permissions/embedding) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Drill-through menu](../questions/visualizations/drill-through) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Query builder](../questions/query-builder/editor) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Basic appearance customization](../configuring-metabase/appearance)\*\* | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Advanced theming](./appearance) | ✅ | ✅ | ❌ | ❌ | ❌ | -| [Usage analytics](../usage-and-performance-tools/usage-analytics) | ✅ | ✅ | ❌ | ✅ | ❌ | -| Embed individual Metabase components | ✅ | ✅ | ❌ | ❌ | ❌ | -| Manage access and interactivity per component | ✅ | ✅ | ❌ | ❌ | ❌ | -| Custom layouts | ✅ | ❌ | ❌ | ❌ | ❌ | -| Customize behavior with [plugins](./sdk/plugins) | ✅ | ❌ | ❌ | ❌ | ❌ | -| [Custom visualizations](../questions/visualizations/custom) | ✅ | ❌ | ❌ | ❌ | ❌ | -| AI chat | ✅ | ✅ | ❌ | ✅ | ❌ | +| Feature | SSO | Guest | +| ----------------------------------------------------------------------------------------- | --- | ----- | +| Charts | ✅ | ✅ | +| Dashboards | ✅ | ✅ | +| [Filter widgets](/glossary/filter-widget) | ✅ | ✅ | +| Export results\* | ✅ | ✅ | +| [Basic appearance customization](../configuring-metabase/appearance)\*\* | ✅ | ✅ | +| Row-level data segregation | ✅ | ✅ | +| [Drill-through menus](../questions/visualizations/drill-through) | ✅ | ❌ | +| [Query builder](../questions/query-builder/editor) | ✅ | ❌ | +| [SQL editor](../questions/native-editor/writing-sql) | ✅ | ❌ | +| [AI chat](./sdk/ai-chat) | ✅ | ❌ | +| [Collection browser](./sdk/collections) | ✅ | ❌ | +| Advanced [Tenant](./tenants) and [permissions](../permissions/embedding) management | ✅ | ❌ | +| [Advanced theming](./appearance) | ✅ | ❌ | +| [Usage analytics](../usage-and-performance-tools/usage-analytics) | ✅ | ❌ | +| Customize layouts and behavior with [plugins](./sdk/plugins) | ✅ | ❌ | +| [Locked filters](./guest-embedding#locked-parameters)\*\*\* | ❌ | ✅ | \* Each embedding type allows data downloads by default, but only [Pro and Enterprise](/pricing/) plans can disable data downloads. \*\* Requires a [Pro and Enterprise](/pricing/) plan for any embedding type. -### Should you use the Modular embedding SDK? +\*\*\* SSO embeds don't need locked filters. Since Metabase knows who's viewing an SSO embed, you can segregate data with [permissions](../permissions/embedding) instead. There's a little more set up, but much less long-term overhead. + +## Full app embedding + +[Full app embedding](./full-app-embedding) allows you to embed the entire Metabase app in an iframe, and integrate Metabase SSO with your app's authentication. + +## Public links and embeds -If your app uses React, you can go with the modular embedding SDK, but you don't need to. +If you'd like to share your data with the good people of the internet, admins can create a [public link](./public-links) or embed a question or dashboard directly in your website. A public link is a URL you can hand to anyone. A public embed is an iframe snippet you drop into one of your pages. Neither one is really an embedding setup — there's no authentication, and anyone with the link can see the data. -The modular embeds that you can set up in the [in-app wizard](./modular-embedding) are built on top of the Modular embedding SDK. Using the SDK just gives you slightly more customization (see the table above), but your app has to use React. You can always start with modular embedding, then move to the SDK if you really need that extra customization. Both support SSO and Guest embeds. +**When to use public links and embeds**: one-off charts and dashboards. Admins can use public links when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don't care who sees the data; you want to make the item available to everyone. ## Resources for AI agents diff --git a/_docs/latest/embedding/modular-embedding.md b/_docs/latest/embedding/modular-embedding.md index 1408e216eb..7aea3c6549 100644 --- a/_docs/latest/embedding/modular-embedding.md +++ b/_docs/latest/embedding/modular-embedding.md @@ -62,7 +62,7 @@ You can also go to **Admin > Embedding > Modular embedding** and click **New emb {% include plans-blockquote.html feature="Authenticated modular embedding" convert_pro_link_to_embedding=true %} -With SSO, Metabase can know who is viewing the embed, and it can unlock all of its bells and whistles (see this [comparison between SSO and guest embeds](./introduction#comparison-of-embedding-types)). +With SSO, Metabase can know who is viewing the embed, and it can unlock all of its bells and whistles (see this [comparison between SSO and guest embeds](./introduction#comparison-between-sso-and-guest-embeds)). This page covers the [SSO setup for your Metabase](./authentication). If you don't need to set up SSO, check out the [guest embed docs](./guest-embedding). diff --git a/_docs/latest/embedding/parameters.md b/_docs/latest/embedding/parameters.md index eab02026bb..6c3e495c93 100644 --- a/_docs/latest/embedding/parameters.md +++ b/_docs/latest/embedding/parameters.md @@ -17,6 +17,8 @@ latest: true This page covers how to pass parameter values to embedded dashboards and SQL questions. +The props and attributes here set values that whoever's viewing the embed can still change. To set a value your app controls and nobody can see or change, use a [locked parameter](./guest-embedding#locked-parameters) on a guest embed, or [data permissions](../permissions/embedding) on an SSO embed. See [Control parameters from your app](./chart#control-parameters-from-your-app). + ## Modular embedding SDK (React) ### Pass parameter values to a dashboard diff --git a/_docs/latest/embedding/query-builder.md b/_docs/latest/embedding/query-builder.md new file mode 100644 index 0000000000..08a1e5f655 --- /dev/null +++ b/_docs/latest/embedding/query-builder.md @@ -0,0 +1,103 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: Embed the query builder +source_url: >- + https://github.com/metabase/metabase/blob/master/docs/embedding/query-builder.md +layout: new-docs +summary: >- + Embed Metabase's visual query builder or SQL editor in your app, so people can + build and save their own questions. +latest: true +--- + +# Embed the query builder + +{% include plans-blockquote.html feature="Embedding the query builder" convert_pro_link_to_embedding=true %} + +You can embed one of Metabase's query editors so people can build questions from scratch. + +- [Visual query builder](#embed-the-visual-query-builder) +- [SQL editor](#embed-the-sql-editor) + +Both query editors need a logged-in Metabase account: to run a new query, Metabase has to know who's asking, so it can work out which data they're allowed to see. In an embed, [SSO](./introduction#sso-embeds) is how you provide that account, so neither editor works in a [guest embed](./introduction#guest-embedding). Check out [SSO or guest embeds](./introduction#comparison-between-sso-and-guest-embeds). + +And because everyone queries through their own Metabase account, people can only build questions on databases their groups have permission to query. See [data permissions](../permissions/data). + +Both query editors use the same `` element as an embedded chart, so they take the same attributes and props. See the [Question component reference](./question-reference). + +To embed an existing chart instead, check out [Embed a chart](./chart). + +## Embed the visual query builder + +To let people build new questions with the visual query builder, use `new` as the question ID. + +![Query builder](./images/embedded-query-builder.png) + +As a web component: + +```html + +``` + +With the SDK: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/new-question.tsx" %} +``` + +To narrow down what people can start from, list the entity types you want in the data picker with the `entity-types` attribute (web component) or the `entityTypes` prop (SDK). For example, `entity-types="['table']"` limits the picker to raw tables. The attribute takes `"table"`, `"model"`, or both. + +## Embed the SQL editor + +![Embedded SQL editor](./images/embedded-sql-editor.png) + +To let people write native SQL, use `new-native` as the question ID. + +As a web component: + +```html + +``` + +With the SDK: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/new-native-question.tsx" %} +``` + +## Let people save questions + +### Saving with web components + +With a web component, turn saving on with `is-save-enabled="true"`. `target-collection` is optional, but it's worth setting: it picks the collection that new questions land in, so people's work doesn't scatter across your Metabase. + +```html + +``` + +### Saving with the React SDK + +With the SDK, saving is already on, so `targetCollection` is all you need. Setting `targetCollection` also hides the collection picker, so nobody has to decide where their question goes. + +For the `isSaveEnabled`, `onBeforeSave`, and `onSave` props, check out [Let people save their changes](./chart#let-people-save-their-changes). + +## Customize the query builder's layout + +With the SDK, you can build your own layout out of the namespaced components inside `InteractiveQuestion`, like ``. See [InteractiveQuestion components](./question-reference#interactivequestion-components). + +## Further reading + +- [Embed a chart](./chart) +- [Question component reference](./question-reference) +- [Modular embedding](./modular-embedding) +- [Modular embedding SDK](./sdk/introduction) +- [Modular embedding components](./components) +- [Appearance](./appearance) diff --git a/_docs/latest/embedding/question-reference.md b/_docs/latest/embedding/question-reference.md new file mode 100644 index 0000000000..1aea630235 --- /dev/null +++ b/_docs/latest/embedding/question-reference.md @@ -0,0 +1,96 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: Question component reference +source_url: >- + https://github.com/metabase/metabase/blob/master/docs/embedding/question-reference.md +layout: new-docs +summary: >- + Reference for the metabase-question web component attributes, the + StaticQuestion and InteractiveQuestion SDK props, and the InteractiveQuestion + layout components. +latest: true +--- + +# Question component reference + +Reference material for embedding a chart or a query editor: the attributes you can set on the `` web component, the props you can pass to the SDK's `StaticQuestion` and `InteractiveQuestion` components, and the namespaced components you can use to build your own layout. + +For how to set all this up, check out [Embed a chart](./chart) and [Embed the query builder](./query-builder). + +## `metabase-question` web component attributes + +These attributes apply to the `` web component. For the SDK, see [`StaticQuestion` props](#staticquestion-props) and [`InteractiveQuestion` props](#interactivequestion-props). + +{% include_file "{{ dirname }}/eajs/snippets/MetabaseQuestionAttributes.md" snippet="properties" %} + +## `StaticQuestion` props + +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} + +`StaticQuestion` embeds a [view-only chart](./chart#embed-a-view-only-chart). + +{% include_file "{{ dirname }}/sdk/api/snippets/StaticQuestionProps.md" snippet="properties" %} + +## `InteractiveQuestion` props + +{% include plans-blockquote.html feature="Interactive charts" convert_pro_link_to_embedding=true is_plural=true %} + +`InteractiveQuestion` embeds an [interactive chart](./chart#embed-an-interactive-chart) or [a query editor](./query-builder). + +{% include_file "{{ dirname }}/sdk/api/snippets/InteractiveQuestionProps.md" snippet="properties" %} + +## Customize the layout of an interactive chart + +By default, `InteractiveQuestion` comes with a layout that lets people view the question, apply filters and aggregations, and use the query builder: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/customize-interactive-question.tsx" snippet="example-default-interactive-question" %} +``` + +To build your own layout, use namespaced components inside `InteractiveQuestion` (like ``): + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/customize-interactive-question.tsx" snippet="example-customized-interactive-question" %} +``` + +## `InteractiveQuestion` components + +These components are available via the `InteractiveQuestion` namespace (like ``). Use them to [customize the layout](#customize-the-layout-of-an-interactive-chart) of an interactive question. + +- [InteractiveQuestion.AlertsButton](./sdk/api/InteractiveQuestion#alertsbutton) +- [InteractiveQuestion.Breakout](./sdk/api/InteractiveQuestion#breakout) +- [InteractiveQuestion.BreakoutDropdown](./sdk/api/InteractiveQuestion#breakoutdropdown) +- [InteractiveQuestion.ChartTypeDropdown](./sdk/api/InteractiveQuestion#charttypedropdown) +- [InteractiveQuestion.ChartTypeSelector](./sdk/api/InteractiveQuestion#charttypeselector) +- [InteractiveQuestion.DownloadWidget](./sdk/api/InteractiveQuestion#downloadwidget) +- [InteractiveQuestion.DownloadWidgetDropdown](./sdk/api/InteractiveQuestion#downloadwidgetdropdown) +- [InteractiveQuestion.Editor](./sdk/api/InteractiveQuestion#editor) +- [InteractiveQuestion.EditorButton](./sdk/api/InteractiveQuestion#editorbutton) +- [InteractiveQuestion.Filter](./sdk/api/InteractiveQuestion#filter) +- [InteractiveQuestion.FilterDropdown](./sdk/api/InteractiveQuestion#filterdropdown) +- [InteractiveQuestion.NavigationBackButton](./sdk/api/InteractiveQuestion#navigationbackbutton) +- [InteractiveQuestion.QuestionSettings](./sdk/api/InteractiveQuestion#questionsettings) +- [InteractiveQuestion.QuestionSettingsDropdown](./sdk/api/InteractiveQuestion#questionsettingsdropdown) +- [InteractiveQuestion.QuestionVisualization](./sdk/api/InteractiveQuestion#questionvisualization) +- [InteractiveQuestion.ResetButton](./sdk/api/InteractiveQuestion#resetbutton) +- [InteractiveQuestion.SaveButton](./sdk/api/InteractiveQuestion#savebutton) +- [InteractiveQuestion.SaveQuestionForm](./sdk/api/InteractiveQuestion#savequestionform) +- [InteractiveQuestion.SqlParametersList](./sdk/api/InteractiveQuestion#sqlparameterslist) +- [InteractiveQuestion.Summarize](./sdk/api/InteractiveQuestion#summarize) +- [InteractiveQuestion.SummarizeDropdown](./sdk/api/InteractiveQuestion#summarizedropdown) +- [InteractiveQuestion.Title](./sdk/api/InteractiveQuestion#title) +- [InteractiveQuestion.VisualizationButton](./sdk/api/InteractiveQuestion#visualizationbutton) + +[InteractiveQuestion.BackButton](./sdk/api/InteractiveQuestion#backbutton) is deprecated. Use `InteractiveQuestion.NavigationBackButton` instead. + +## Further reading + +- [Embed a chart](./chart) +- [Embed the query builder](./query-builder) +- [Modular embedding components](./components) +- [Modular embedding parameters](./parameters) +- [Appearance](./appearance) diff --git a/_docs/latest/embedding/sdk/ai-chat.md b/_docs/latest/embedding/sdk/ai-chat.md index c3e76de7d7..77dc99afaf 100644 --- a/_docs/latest/embedding/sdk/ai-chat.md +++ b/_docs/latest/embedding/sdk/ai-chat.md @@ -17,7 +17,7 @@ latest: true ![Embedded AI chat](../images/ai-chat.png) -{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true%} +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} You can embed an AI chat in your application similar to [Metabot](../modular-embedding) in Metabase. @@ -37,7 +37,7 @@ You can check out a [demo of the AI chat component](https://embedded-analytics-s {% include_file "{{ dirname }}/snippets/questions/ai-question.tsx" %} ``` -## Props +## `MetabotQuestion` props {% include_file "{{ dirname }}/api/snippets/MetabotQuestionProps.md" snippet="properties" %} diff --git a/_docs/latest/embedding/sdk/collections.md b/_docs/latest/embedding/sdk/collections.md index 26b37253d5..8fda1b7ce5 100644 --- a/_docs/latest/embedding/sdk/collections.md +++ b/_docs/latest/embedding/sdk/collections.md @@ -46,4 +46,4 @@ With static questions, you set a specific collection as the collection people ca 1. Set `isSaveEnabled` to true. 2. Set `targetCollection` to the collection ID you want people to save items to. -For more options, see [Question props](./questions). +For more options, see [Let people save their changes](../chart#let-people-save-their-changes). diff --git a/_docs/latest/embedding/sdk/dashboards.md b/_docs/latest/embedding/sdk/dashboards.md index 931264e175..202c1d722d 100644 --- a/_docs/latest/embedding/sdk/dashboards.md +++ b/_docs/latest/embedding/sdk/dashboards.md @@ -85,7 +85,7 @@ By default, dashboard components take full page height (100vh). You can override ## Customizing drill-through question layout -When drilling through or clicking on a question card in the dashboard, you will be taken to the question view. By default, the question is shown in the [default layout](./questions#customizing-interactive-questions) for interactive questions. +Drilling through or clicking on a question card in the dashboard will take you to the question view with the [default layout](../question-reference#customize-the-layout-of-an-interactive-chart) for interactive questions. To customize the question layout, pass a `renderDrillThroughQuestion` prop to the `InteractiveDashboard` component, with the custom view as the child component. @@ -95,7 +95,7 @@ To customize the question layout, pass a `renderDrillThroughQuestion` prop to th {% include_file "{{ dirname }}/snippets/dashboards/custom-drill-through-question-layout.tsx" snippet="example-2" %} ``` -The questionView prop accepts a React component that will be rendered in the question view, which you can build with namespaced components within the `InteractiveQuestion` component. See [customizing interactive questions](./questions#customizing-interactive-questions) for an example layout. +The `questionView` prop accepts a React component that will be rendered in the question view, which you can build with namespaced components within the `InteractiveQuestion` component. See [customize the layout](../question-reference#customize-the-layout-of-an-interactive-chart). ## Dashboard plugins @@ -147,7 +147,7 @@ If you want to replace the existing menu with your own component, you can do so ### `mapQuestionClickActions` -You can customize what happens when people click on a data point on a dashboard with the `mapQuestionClickActions` plugin. See [mapQuestionClickActions](./questions#mapquestionclickactions). +You can customize what happens when people click on a data point on a dashboard with the `mapQuestionClickActions` plugin. See [mapQuestionClickActions](../chart#customize-what-happens-when-someone-clicks-on-a-chart). ## Creating dashboards diff --git a/_docs/latest/embedding/sdk/introduction.md b/_docs/latest/embedding/sdk/introduction.md index 83ad9a770a..8912e9ff1b 100644 --- a/_docs/latest/embedding/sdk/introduction.md +++ b/_docs/latest/embedding/sdk/introduction.md @@ -113,7 +113,7 @@ Starting with Metabase 57, the SDK consists of two parts: Start with one of the quickstarts, then see these pages for more info on components, theming, and more. - [Authentication](../authentication) -- [Questions](./questions) +- [Embed a chart](../chart) - [AI chat](./ai-chat) - [Dashboards](./dashboards) - [Actions](./actions) diff --git a/_docs/latest/embedding/sdk/plugins.md b/_docs/latest/embedding/sdk/plugins.md index b3c4e56169..894245b72d 100644 --- a/_docs/latest/embedding/sdk/plugins.md +++ b/_docs/latest/embedding/sdk/plugins.md @@ -39,7 +39,7 @@ To use a plugin on a per-component basis, pass the plugin as a prop to the compo See docs for specific components: -- [Interactive question plugins](./questions#interactive-question-plugins) +- [Question plugins](../chart#customize-what-happens-when-someone-clicks-on-a-chart) - [Dashboard plugins](./dashboards#dashboard-plugins) ## Global plugins @@ -48,7 +48,7 @@ See docs for specific components: The plugin `mapQuestionClickActions` lets you customize what happens when people click on a data point on a dashboard or chart. `mapQuestionClickActions` can be used globally, or on component level. -See [`mapQuestionClickActions` plugin](./questions#mapquestionclickactions) for more information and examples. +See [`mapQuestionClickActions` plugin](../chart#customize-what-happens-when-someone-clicks-on-a-chart) for more information and examples. ### `handleLink` @@ -78,5 +78,5 @@ The plugins `getNoDataIllustration` and `getNoObjectIllustration` can only be us ## Further reading -- [Interactive question plugins](./questions#interactive-question-plugins) +- [Question plugins](../chart#customize-what-happens-when-someone-clicks-on-a-chart) - [Dashboard plugins](./dashboards#dashboard-plugins) diff --git a/_docs/latest/embedding/sdk/questions.md b/_docs/latest/embedding/sdk/questions.md deleted file mode 100644 index da475f14eb..0000000000 --- a/_docs/latest/embedding/sdk/questions.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -version: v0.63 -has_magic_breadcrumbs: true -show_category_breadcrumb: true -show_title_breadcrumb: true -category: Embedding -title: Modular embedding SDK - questions -source_url: >- - https://github.com/metabase/metabase/blob/master/docs/embedding/sdk/questions.md -layout: new-docs -description: How to embed charts in your app with the Modular embedding SDK. -latest: true ---- - -# Modular embedding SDK - questions - -{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true%} - -There are different ways you can embed questions: - -- [Static question](#staticquestion). Embeds a chart. Clicking on the chart doesn't do anything. -- [Interactive question](#interactivequestion). Create new questions or edit existing ones with the visual query builder or SQL editor. Clicking on the chart gives you the drill-through menu. - -## Embedding a question - -You can embed a question using one of the question components: - -### `StaticQuestion` - -A lightweight question component. Use this component when you want to display results without letting people interact with the data. - -![Static question](../images/static-question.png) - -The component has a default height, which can be customized by using the `height` prop. To inherit the height from the parent container, you can pass `100%` to the height prop. - -#### API Reference - -- [Component](./api/StaticQuestion) -- [Props](./api/StaticQuestionProps) - -#### Example - -```typescript -{% include_file "{{ dirname }}/snippets/questions/static-question.tsx" %} -``` - -#### Props - -{% include_file "{{ dirname }}/api/snippets/StaticQuestionProps.md" snippet="properties" %} - -### `InteractiveQuestion` - -Use this component when you want to allow people to explore their data and customize question layout. - -![Interactive question](../images/interactive-question.png) - -#### API Reference - -- [Component](./api/InteractiveQuestion) -- [Props](./api/InteractiveQuestionProps) - -#### Example - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question.tsx" %} -``` - -#### Props - -{% include_file "{{ dirname }}/api/snippets/InteractiveQuestionProps.md" snippet="properties" %} - -## Pass parameters to SQL questions - -See [Modular embedding parameters](../parameters#pass-parameters-to-sql-questions). - -## Enable alerts on embedded questions - -You can let people set up [alerts](../../questions/alerts) on embedded questions by passing the `withAlerts` prop to `StaticQuestion` or `InteractiveQuestion`. Alerts require [email setup](../../configuring-metabase/email), and the question must be saved (not a new question). - -Alerts created in an embedded context only send to the logged-in user and exclude links to Metabase items. - -```tsx - -``` - -## Questions with natural language - -See [AI chat](./ai-chat). - -## Customizing interactive questions - -By default, the modular embedding SDK provides a default layout for interactive questions that allows you to view your questions, apply filters and aggregations, and access functionality within the query builder. - -Here's an example of using the `InteractiveQuestion` component with its default layout: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/customize-interactive-question.tsx" snippet="example-default-interactive-question" %} -``` - -To customize the layout, use namespaced components within the `InteractiveQuestion` component. For example: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/customize-interactive-question.tsx" snippet="example-customized-interactive-question" %} -``` - -### Interactive question components - -These components are available via the `InteractiveQuestion` namespace (e.g., ``). - -#### API Reference: - -- [InteractiveQuestion.BackButton](./api/InteractiveQuestion#backbutton) -- [InteractiveQuestion.Breakout](./api/InteractiveQuestion#breakout) -- [InteractiveQuestion.BreakoutDropdown](./api/InteractiveQuestion#breakoutdropdown) -- [InteractiveQuestion.ChartTypeDropdown](./api/InteractiveQuestion#charttypedropdown) -- [InteractiveQuestion.ChartTypeSelector](./api/InteractiveQuestion#charttypeselector) -- [InteractiveQuestion.Editor](./api/InteractiveQuestion#editor) -- [InteractiveQuestion.EditorButton](./api/InteractiveQuestion#editorbutton) -- [InteractiveQuestion.Filter](./api/InteractiveQuestion#filter) -- [InteractiveQuestion.FilterDropdown](./api/InteractiveQuestion#filterdropdown) -- [InteractiveQuestion.QuestionSettings](./api/InteractiveQuestion#questionsettings) -- [InteractiveQuestion.QuestionSettingsDropdown](./api/InteractiveQuestion#questionsettingsdropdown) -- [InteractiveQuestion.QuestionVisualization](./api/InteractiveQuestion#questionvisualization) -- [InteractiveQuestion.ResetButton](./api/InteractiveQuestion#resetbutton) -- [InteractiveQuestion.SaveButton](./api/InteractiveQuestion#savebutton) -- [InteractiveQuestion.SaveQuestionForm](./api/InteractiveQuestion#savequestionform) -- [InteractiveQuestion.Summarize](./api/InteractiveQuestion#summarize) -- [InteractiveQuestion.SummarizeDropdown](./api/InteractiveQuestion#summarizedropdown) -- [InteractiveQuestion.DownloadWidget](./api/InteractiveQuestion#downloadwidget) -- [InteractiveQuestion.DownloadWidgetDropdown](./api/InteractiveQuestion#downloadwidgetdropdown) -- [InteractiveQuestion.Title](./api/InteractiveQuestion#title) - -## Interactive question plugins - -You can use [plugins](./plugins) to add custom functionality to your questions. - -### `mapQuestionClickActions` - -When people click on a data point in the embedded interactive chart, Metabase shows them a menu of actions by default. The plugin `mapQuestionClickActions` allows you to customize this behavior. You can choose to: - -- Open the default Metabase menu. -- Add custom actions to that click-through menu. -- Perform immediate action without opening a menu. - -Use `mapQuestionClickActions` globally at the provider level, or on individual `InteractiveQuestion` or `InteractiveDashboard` components. For more on provider scope, see [Plugins](./plugins) - -The example below shows all the options for click action behavior. This example will: - -- Open a menu with custom actions when "Last Name" column is clicked. -- Perform an immediate action (show an alert) when the "Plan" column is clicked. -- Shows the default menu (available as `clickActions`) in all other cases. - -The behavior is determined by what `mapQuestionClickActions` returns: array of actions to open a menu, or a single action to trigger an immediate action. - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question-click-actions.tsx" snippet="example" %} -``` - -You can also customize the appearance of custom actions in the click menu. The example below shows an example of a click menu with default actions, a custom action, and a custom action with customized appearance: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question-plugins.tsx" snippet="example" %} -``` - -## Prevent people from saving changes to an `InteractiveQuestion` - -To prevent people from saving changes to an interactive question, or from saving changes as a new question, you can set `isSaveEnabled={false}`: - -```tsx -{% include_file "{{ dirname }}/snippets/questions/disable-question-save.tsx" %} -``` - -## Create and edit questions with the query builder - -![Query builder](../images/query-builder.png) - -The `InteractiveQuestion` component supports three modes: - -- `questionId="new"` — opens the visual query builder for creating new questions. -- `questionId="new-native"` — opens the SQL editor for creating new questions. -- A numeric `questionId` (e.g., `questionId={42}`) — embeds an existing question. People can click the edit button to modify it, which opens the appropriate editor (visual or SQL) based on the question type. - -### Embed the visual query builder - -To embed the query builder for creating new questions, pass `questionId="new"` to the `InteractiveQuestion` component. You can use the [`children` prop](#customizing-interactive-questions) to customize the layout. - -```tsx -{% include_file "{{ dirname }}/snippets/questions/new-question.tsx" %} -``` - -### Embed the SQL editor - -To embed the SQL editor for creating new questions, pass `questionId="new-native"` to the `InteractiveQuestion` component: - -```tsx -{% include_file "{{ dirname }}/snippets/questions/new-native-question.tsx" %} -``` - -To customize the question editor's layout, use the `InteractiveQuestion` component [directly with a custom `children` prop](#customizing-interactive-questions). diff --git a/_docs/latest/embedding/start.md b/_docs/latest/embedding/start.md index a445971023..b24d21bcb2 100644 --- a/_docs/latest/embedding/start.md +++ b/_docs/latest/embedding/start.md @@ -34,6 +34,18 @@ With the Modular embedding SDK, you can embed individual Metabase components wit Jump to a SDK quickstart with a sample React application. +### [Embed a chart](./chart) + +Embed a single chart, view-only or interactive, with web components or the React SDK. + +### [Embed the query builder](./query-builder) + +Embed Metabase's visual query builder or SQL editor, so people can build and save their own questions. + +### [Question component reference](./question-reference) + +Every `` attribute, the `StaticQuestion` and `InteractiveQuestion` props, and the components you can use to build your own question layout. + ### [Guest embedding](./guest-embedding) Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables. diff --git a/_docs/v0.63/configuring-metabase/config-template.md b/_docs/v0.63/configuring-metabase/config-template.md index 88228fa3d4..5fc4f07b66 100644 --- a/_docs/v0.63/configuring-metabase/config-template.md +++ b/_docs/v0.63/configuring-metabase/config-template.md @@ -77,7 +77,6 @@ config: admin-email: null aggregated-query-row-limit: null ai-features-enabled: true - ai-usage-max-retention-days: null allowed-iframe-hosts: |- youtube.com, youtu.be, @@ -112,7 +111,6 @@ config: application-name: Metabase attachment-row-limit: null attachment-table-row-limit: 20 - audit-max-retention-days: null bcc-enabled: true breakout-bin-width: 10.0 breakout-bins-num: 8 @@ -177,7 +175,6 @@ config: http-channel-host-strategy: external-only humanization-strategy: simple index-update-thread-count: 2 - install-analytics-database: true jdbc-data-warehouse-connection-pool-checkout-timeout-ms: 0 jdbc-data-warehouse-connection-pool-max-pending-checkouts: 0 jdbc-data-warehouse-max-connection-pool-size: 15 @@ -237,7 +234,6 @@ config: llm-rate-limit-per-ip: 100 llm-rate-limit-per-user: 20 llm-request-timeout-ms: 60000 - load-analytics-content: true loading-message: doing-science login-page-illustration: default login-page-illustration-custom: null @@ -259,7 +255,6 @@ config: not-behind-proxy: false notification-link-base-url: null notification-system-event-thread-pool-size: 5 - notification-temp-file-size-max-bytes: 10485760 notification-thread-pool-size: 3 oidc-allowed-networks: allow-all oidc-providers: [] @@ -311,7 +306,6 @@ config: sdk-encryption-validation-key: null search-language: null search-typeahead-enabled: true - send-email-on-first-login-from-new-device: true send-new-sso-user-admin-email: null session-cookie-samesite: lax session-cookies: null @@ -319,7 +313,6 @@ config: setup-embedding-autoenabled: false setup-license-active-at-setup: false show-database-syncing-modal: null - show-google-sheets-integration: null show-homepage-data: true show-homepage-xrays: true show-metabase-links: true diff --git a/_docs/v0.63/configuring-metabase/environment-variables.md b/_docs/v0.63/configuring-metabase/environment-variables.md index 64e26fdd58..5b33ac7556 100644 --- a/_docs/v0.63/configuring-metabase/environment-variables.md +++ b/_docs/v0.63/configuring-metabase/environment-variables.md @@ -92,7 +92,7 @@ Whether AI features are enabled. - Type: integer - Default: `null` - [Exported as](../installation-and-operation/serialization): `ai-usage-max-retention-days`. -- [Configuration file name](./config-file): `ai-usage-max-retention-days` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Number of days to retain rows in the ai_usage_log, metabot_conversation, and metabot_message tables. Minimum value is 30; set to 0 to retain data indefinitely. @@ -301,6 +301,7 @@ Range: 1-100. To limit the total number of rows included in the file attachment - Type: string - Default: `null` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Number of days to retain data in audit-related tables. Minimum value is 30; set to 0 to retain data indefinitely. @@ -910,6 +911,7 @@ Number of threads to use for batched index updates, including embedding requests - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not we should install the Metabase analytics database on startup. Defaults to true, but can be disabled via environmment variable. @@ -1458,6 +1460,7 @@ Socket timeout in milliseconds for LLM API requests. - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not we should load Metabase analytics content on startup. Defaults to match `install-analytics-database`, which defaults to true, but can be disabled via environment variable. @@ -1660,6 +1663,7 @@ The size of the thread pool used to send system event notifications. - Type: integer - Default: `10485760` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). The maximum file size that will be created when storing notification query results on disk. Note this is in BYTES. Default value is 10485760 which is `10 * 1024 * 1024`. To disable this size limit set the @@ -2131,6 +2135,7 @@ Enable typeahead search in the Metabase navbar? - Type: boolean - Default: `true` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Should we send users a notification email the first time they log in from a new device? (Default: true). This is currently only configurable via environment variable so users who gain access to an admin's credentials cannot @@ -2211,7 +2216,7 @@ Whether an introductory modal should be shown after the next database connection - Type: boolean - Default: `null` -- [Configuration file name](./config-file): `show-google-sheets-integration` +- Environment variable only: you can't set this in the Admin settings or in a [configuration file](./config-file). Whether or not to show the user a button that sets up Google Sheets integration. diff --git a/_docs/v0.63/embedding/chart.md b/_docs/v0.63/embedding/chart.md new file mode 100644 index 0000000000..ea884ed492 --- /dev/null +++ b/_docs/v0.63/embedding/chart.md @@ -0,0 +1,358 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: 'Embed a chart' +source_url: 'https://github.com/metabase/metabase/blob/master/docs/embedding/chart.md' +layout: new-docs +summary: 'Embed a single Metabase chart in your app, either view-only or interactive, with a web component or using the React SDK.' +redirect_from: + - /docs/v0.63/embedding/sdk/questions + - /docs/v0.63/embedding/question +--- + +# Embed a chart + +There are two ways you can embed a chart (called a question, in Metabase parlance): + +- [View-only chart](#embed-a-view-only-chart): people see the results, filter them, and that's it. +- [Interactive chart](#embed-an-interactive-chart): people can drill through the chart and change the query behind it. + +To let people build questions from scratch instead, check out [Embed the query builder](./query-builder). To embed an AI chat component, check out [AI chat](./sdk/ai-chat). + +## Embed a view-only chart + +![Static question](./images/static-question.png) + +A view-only (a.k.a. "static") chart displays results without letting people explore the data. Nobody can drill through it, change the query behind it, or run a new one. You can, however, add editable filters that people can change to update the query results. + +View-only isn't tied to one kind of embed. You can make a chart view-only in any embedding type: + +- **[Guest embeds](./introduction#guest-embedding)**: always view-only. Nobody logs in to a guest embed, so Metabase has no account to check permissions against, and no way to tell whether a new query is one that person should be allowed to run. The published question is the only thing Metabase can safely run, which is why there's no drill-through or ad-hoc querying to turn off. +- **[SSO embeds](./introduction#sso-embeds)**: interactive out of the box. To make one view-only, turn off drill-through with `drills="false"` (web component) or `drills={false}` (SDK), and turn off saving with `is-save-enabled="false"` or `isSaveEnabled={false}`. You can also manage what people can do through [data permissions](../permissions/data) and [collection permissions](../permissions/collections). + +So pick your authentication based on what your app needs---plans, permissions, whether Metabase should know who's viewing---not on whether you want a view-only chart. Check out [SSO or guest embeds](./introduction#comparison-between-sso-and-guest-embeds). + +This section covers setting up a view-only chart with guest authentication. + +- [Web components](#view-only-charts-with-guest-authentication-using-a-web-component) +- [React SDK](#view-only-charts-using-the-react-sdk) + +### View-only charts with guest authentication using a web component + +You can use the in-app wizard to set up a view-only chart using web components. + +![In-app embedding wizard](./images/in-app-embedding-wizard.png) + +Before you start, an admin needs to [turn on guest embedding](./guest-embedding#turning-on-guest-embedding-in-metabase). + +Three things need to happen: you publish the embed in Metabase, you paste the chart code into your app, and your server signs a JWT. The wizard writes most of the code for you, so the list below is longer than the work. + +1. Visit the question in your Metabase. +2. Click the **Share** icon in the upper right. +3. Select **Embed** to open the embedding wizard. +4. For authentication, choose **Guest**, so your app won't need to log anyone in to your Metabase. +5. Click the **Publish** button. Publishing only applies to guest embeds. (There's nothing to publish for an SSO embed, because in that case people can explore the data based on their data and collection permissions.) +6. Under behavior, Metabase gives you several options for customizing how the embed works. See [web component attributes](./question-reference#metabase-question-web-component-attributes) for what each one does. If you'd picked SSO in step 4, this is where you'd make the embed view-only by turning off drill-through. +7. If you're embedding a SQL question with a variable, set the parameter to **Editable** or **Locked**. Parameters are **Disabled** by default, which hides them and prevents your server from setting them. See [Configuring parameters](./guest-embedding#configuring-parameters). +8. Customize the [appearance](./appearance). +9. Click the **Get code** button. You'll get both the frontend and backend code based on the selections you made in the wizard. +10. Copy the client code and paste it in your app. +11. Remove the hardcoded JWT tokens in your HTML. Fetch the token from your backend and pass the token to the component programmatically. + +To keep an embed alive after its token expires, configure a token endpoint with [`guestEmbedProviderUri`](./guest-embedding#refreshing-or-initializing-the-jwt-from-your-server). + +#### View-only chart example with web components + +Say you have a question written in SQL, with a field filter to filter orders by `customer_id`: + +```sql +{% raw %} +SELECT + * +FROM + orders +WHERE + {{customer_id}} +{% endraw %} +``` + +Now say you want to embed this question on each customer's account page in your app, showing only that customer's orders. Here's the frontend code. + +```html + + + + + + + + +``` + +The `theme` key sets the chart's appearance. For the full theme object with all the options, check out [Appearance](./appearance). + +On your app's server, set the value for the locked parameter in the token. Whoever's looking at the page can't see or change that value, so an embed on customer 13's account page returns only customer 13's orders. + +```js +// you will need to install via 'npm install jsonwebtoken' or in your package.json + +const jwt = require("jsonwebtoken"); + +// Get your key from your Metabase at +// /admin/embedding/guest -> Embedding secret key +const METABASE_SECRET_KEY = "YOUR_SECRET_KEY"; + +// Here we lock a customer_id parameter to 13 +const payload = { + resource: { question: 40956 }, + params: { + customer_id: [ + 13, // set this programmatically, based on whose account page your app is rendering + ], + }, + exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration +}; +const token = jwt.sign(payload, METABASE_SECRET_KEY); +``` + +To get this code from the in-app wizard, set the `customer_id` parameter to **Locked** and publish the question. See [Locked parameters](./guest-embedding#locked-parameters). + +For all modular embeds, you can also set a `locale` in your page-level configuration to [translate embedded content](./translations). + +For the full list of attributes, see [web component attributes](./question-reference#metabase-question-web-component-attributes). + +### View-only charts using the React SDK + +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} + +To embed a view-only chart with the [SDK](./sdk/introduction), use the `StaticQuestion` component. Wrap the component in the `MetabaseProvider` component with your auth config. + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/static-question.tsx" %} +``` + +The component has a default height, which you can change with the `height` prop. To inherit the height from the parent container, pass `100%`. + +For the full list of props, see [`StaticQuestion` props](./question-reference#staticquestion-props). + +## Embed an interactive chart + +{% include plans-blockquote.html feature="Interactive charts" convert_pro_link_to_embedding=true is_plural=true %} + +An interactive chart lets people explore their data: they can drill through the chart, filter results, summarize and group them, change visualization settings, and optionally save their changes. + +Interactive charts require SSO, which you can set up with either web components or the React SDK. + +- [Web components](#interactive-charts-using-a-web-component) +- [React SDK](#interactive-charts-using-the-react-sdk) + +### Interactive charts using a web component + +Reference an existing question by ID. [Drill-through](../questions/visualizations/drill-through) is on by default: + +```html + +``` + +You can pass a sequential ID like `1`, but an [entity ID](../installation-and-operation/serialization#entity-ids-work-with-embedding) is the better bet: entity IDs stay the same when you move content between instances, like from staging to production. + +To control what people can do with the chart, check out [web component attributes](./question-reference#metabase-question-web-component-attributes). For example, you can show or hide download buttons, the question's title, or the chart type selector. + +### Interactive charts using the React SDK + +Use `InteractiveQuestion` when you want people to explore their data and customize the layout. + +![Interactive question](./images/interactive-question.png) + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question.tsx" %} +``` + +For the full list of props, see [`InteractiveQuestion` props](./question-reference#interactivequestion-props). + +#### Customize the layout of an interactive chart + +`InteractiveQuestion` comes with a default layout that lets people view the question, apply filters and aggregations, and use the query builder. You can also build your own layout out of namespaced components like ``. For examples of both, see [Customizing an interactive chart's layout](./question-reference#customize-the-layout-of-an-interactive-chart), and the full list of [`InteractiveQuestion` components](./question-reference#interactivequestion-components). + +### Let people save their changes + +If you're using embeds with SSO, you can let people save their work. + +### Saving with web components + +With a web component, turn saving on with `is-save-enabled="true"`, and set the collection that saved questions land in with `target-collection`: + +```html + +``` + +### Saving with the React SDK + +With the SDK, you get four props to control saving questions: + +- `isSaveEnabled` shows or hides the save button. +- `onBeforeSave` runs before a save (it can be async). +- `onSave` runs after a successful save. It receives the updated question and a context object with `isNewQuestion`. +- `targetCollection` pre-selects the collection to save to and hides the collection picker. + +To prevent people from saving changes (or saving as a new question), set `isSaveEnabled={false}`: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/disable-question-save.tsx" %} +``` + +In the embedding wizard, this corresponds to the **Allow people to save new questions** option. + +## Customize what happens when someone clicks on a chart + +Customizing click behavior is only available in the [Modular embedding SDK](./sdk/introduction) for now. + +When people click a data point in an interactive chart, Metabase shows a menu of actions. The [`mapQuestionClickActions`](./sdk/plugins) plugin lets you customize this: open the default menu, add custom actions, or perform an immediate action without a menu. + +Use it globally on `MetabaseProvider`, or on individual `InteractiveQuestion` components: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question-click-actions.tsx" snippet="example" %} +``` + +You can also customize how custom actions look in the menu: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/interactive-question-plugins.tsx" snippet="example" %} +``` + +## Embed the query builder or SQL editor + +To let people build questions from scratch, check out [Embed the query builder](./query-builder). + +## Control parameters from your app + +Say you want to show each customer only their own orders. How you filter the results depends on how you authenticate the embed. + +### Lock a parameter on a guest embed + +Embeds with **Guest** authentication can [lock a parameter](./guest-embedding#locked-parameters). Your app sets the parameter's value in the signed token on your server, so the filter is controlled by your app rather than by whoever's clicking around the page. They can't see the value, and they can't change it. An embed on a customer's account page returns that account's rows, whether or not Metabase has any idea who's looking at it. + +Locked parameters need a question written in SQL, with a [field filter or variable](../questions/native-editor/sql-parameters) to lock onto. Query builder questions have no parameters to lock, so segregate their data with permissions instead. + +```javascript +const payload = { + resource: { question: 5 }, + params: { + category: ["Gadget"], // Locked. Set by your app, not by whoever's viewing. + }, + exp: Math.round(Date.now() / 1000) + 10 * 60, +}; + +const token = jwt.sign(payload, METABASE_SECRET_KEY); +``` + +### Use permissions on an SSO embed + +Embeds with **SSO** don't need to lock parameters. Since Metabase knows who's viewing, you can apply [data permissions](../permissions/embedding) and let Metabase filter the rows, instead of locking parameters by hand. This works for query builder questions and SQL questions alike. + +### Set parameter values from your app + +You can also pass values to a question's [SQL parameters](../questions/native-editor/sql-parameters) in the format `{parameter_name: parameter_value}`, and keep your app in sync as people change them. Set the values once on load, or hold the values in your app and get a callback whenever they change. + +For both the SDK props (`initialSqlParameters`, `sqlParameters`, and `onSqlParametersChange`) and the web component equivalents, see [Modular embedding parameters](./parameters). + +### Hide a parameter + +To hide a parameter from the question's UI, use the [`hidden-parameters`](./question-reference#metabase-question-web-component-attributes) attribute (web component) or the `hiddenParameters` prop (SDK). Both require a Pro or Enterprise plan and an SSO embed; `hidden-parameters` has no effect on a guest embed. To hide a parameter on a guest embed, set the parameter to **Locked** or leave it **Disabled** in the question's embed settings. + +## Let people set up alerts on a question + +You can let people set up [alerts](../questions/alerts) on a saved question with the [`with-alerts`](./question-reference#metabase-question-web-component-attributes) attribute on the web component: + +```html + +``` + +Or by passing `withAlerts` to `StaticQuestion` or `InteractiveQuestion` in the SDK: + +```tsx + + + +``` + +Metabase only shows the alerts button when all of these are true: + +- Your Metabase has [email set up](../configuring-metabase/email). +- The embed is an authenticated (SSO) embed. +- The person viewing the embed is in a group with the [Subscriptions and alerts](../permissions/application#subscriptions-and-alerts) application permission. Metabase grants this permission to the All Users group by default, so admins have to set it to **No** to take it away. +- The person viewing the embed has [collection permissions](../permissions/collections) for the collection that holds the question. + +Alerts created in an embedded context only send to whoever's logged in, and they exclude links to Metabase items. + +## Customize chart appearance + +You can theme an embedded question and toggle parts of its UI. For the full set of theming options, see [Appearance](./appearance). For every attribute and prop, see the [Question component reference](./question-reference). + +- **Title**: show or hide the question title with `with-title` (web component) or `title` (SDK). +- **Downloads**: show or hide download buttons with `with-downloads` / `withDownloads`. Defaults to `true` on OSS/Starter and `false` on Pro/Enterprise. Disabling downloads requires a [Pro](/product/pro) or [Enterprise](/product/enterprise) plan. +- **Chart type selector**: show or hide it with `withChartTypeSelector` (SDK). +- **Theme**: set a light or dark preset, or (on Pro/Enterprise) customize colors and fonts. The `question` component in the theme has its own overrides: + +```js +{ + components: { + question: { + // Background color for all questions + backgroundColor: "#2E353B", + + // Toolbar of the default interactive question layout + toolbar: { + backgroundColor: "#F3F5F7", + }, + }, + }, +} +``` + +Colors set in a question's visualization settings override theme colors. + +### The "Powered by Metabase" banner + +Metabase adds a "Powered by Metabase" banner to guest embeds (both charts and dashboards) on the OSS and Starter plans. To remove the banner, upgrade to a [Pro](/product/pro) or [Enterprise](/product/enterprise) plan. + +## Further reading + +- [Question component reference](./question-reference) +- [Embed the query builder](./query-builder) +- [Appearance](./appearance) +- [Modular embedding parameters](./parameters) +- [Translating embeds](./translations) +- [Guest embeds](./guest-embedding) +- [Authentication](./authentication) +- [Modular embedding SDK](./sdk/introduction) +- [AI chat](./sdk/ai-chat) diff --git a/_docs/v0.63/embedding/components.md b/_docs/v0.63/embedding/components.md index 5b2d6b05b0..7281446092 100644 --- a/_docs/v0.63/embedding/components.md +++ b/_docs/v0.63/embedding/components.md @@ -55,26 +55,9 @@ If you surround your attribute value with double quotes, make sure to use single ## Question -To render a question (chart): - -```html - -``` - -You can also use the question component to create new questions: - -- `question-id="new"` — opens the visual query builder. -- `question-id="new-native"` — opens the SQL editor. - -For example, to embed the SQL editor: - -```html - -``` - -### Attributes - -{% include_file "{{ dirname }}/eajs/snippets/MetabaseQuestionAttributes.md" snippet="properties" %} +- [Embed a chart](./chart) +- [Embed a query editor](./query-builder) +- [Question component reference](./question-reference), for `` attributes and SDK props ## Browser diff --git a/_docs/v0.63/embedding/images/embedded-query-builder.png b/_docs/v0.63/embedding/images/embedded-query-builder.png new file mode 100644 index 0000000000..6e95764dda Binary files /dev/null and b/_docs/v0.63/embedding/images/embedded-query-builder.png differ diff --git a/_docs/v0.63/embedding/images/embedded-sql-editor.png b/_docs/v0.63/embedding/images/embedded-sql-editor.png new file mode 100644 index 0000000000..5a8675a3e2 Binary files /dev/null and b/_docs/v0.63/embedding/images/embedded-sql-editor.png differ diff --git a/_docs/v0.63/embedding/images/in-app-embedding-wizard.png b/_docs/v0.63/embedding/images/in-app-embedding-wizard.png new file mode 100644 index 0000000000..319f03bec1 Binary files /dev/null and b/_docs/v0.63/embedding/images/in-app-embedding-wizard.png differ diff --git a/_docs/v0.63/embedding/introduction.md b/_docs/v0.63/embedding/introduction.md index a140dd785e..7e61e3cf45 100644 --- a/_docs/v0.63/embedding/introduction.md +++ b/_docs/v0.63/embedding/introduction.md @@ -14,11 +14,16 @@ redirect_from: # Embedding introduction -You can embed Metabase tables, charts, and dashboards—even Metabase's query builder—in your website or application. Here are the different ways you can embed Metabase: +You can embed Metabase tables, charts, dashboards, AI chat---even Metabase's query builder---in your website or application. -- [Modular embedding](#modular-embedding) -- [Full app embedding](#full-app-embedding) -- [Public links](#public-links-and-embeds) +There are two ways to embed Metabase. + +- **[Modular embedding](#modular-embedding)**: embed individual Metabase components, like questions, dashboards, and AI chat, so they seamlessly integrate with your app. +- **[Full app embedding](#full-app-embedding)**: embed the full Metabase app in an iframe, styled like your branding. + +Most people go with modular embedding, so you can integrate Metabase components into your app. + +If you just want to share a chart or dashboard with anyone who has the link, and you don't need any authentication, take a look at [public links and embeds](#public-links-and-embeds). ## Modular embedding @@ -26,21 +31,9 @@ With [modular embedding](./modular-embedding), you can embed individual Metabase You can use two different ways to authenticate modular embeds: -- [SSO](#modular-embedding) +- [SSO](#sso-embeds) - [Guest](#guest-embedding) -Here's a basic breakdown of what each auth type enables: - -| Component | SSO | Guest | -| ----------------------------------------------------- | --- | ----- | -| Chart | ✅ | ✅ | -| Chart with drill-through | ✅ | ❌ | -| Dashboard | ✅ | ✅ | -| Dashboard with drill-through | ✅ | ❌ | -| [Query builder](../questions/query-builder/editor) | ✅ | ❌ | -| Browser to navigate collections | ✅ | ❌ | -| Metabot AI chat | ✅ | ❌ | - ### SSO embeds With SSO, Metabase can know who's viewing what, which unlocks a lot of power. You can automatically apply [data permissions](../permissions/embedding), which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they're allowed to. @@ -49,52 +42,61 @@ With SSO, Metabase can know who's viewing what, which unlocks a lot of power. Yo If you're building a SaaS product with embedded analytics for multiple customers, you can keep customer data isolated with [Tenants](./tenants). +Accounts for these embedded users in your Metabase count toward the [accounts billed in your Metabase plan](/docs/latest/cloud/how-billing-works). But by letting your customers self-serve their data, you save time on developing bespoke charts. And you can charge _more_ for a premium analytics experience. If you plan on giving a lot of your customers self-service access to their data, you should consider an enterprise plan, with custom pricing that scales with your business. + ### Guest embedding [Guest embeds](./guest-embedding) are a secure way to embed charts and dashboards. Guest embedding works on all Metabase plans, including OSS and Starter. **When to use guest embeds**: simple embedding use cases where you don't want to offer ad-hoc querying or chart drill-through. To filter data relevant to the viewer, you can use guest embeds with [locked parameters](./guest-embedding#locked-parameters). -## Public links and embeds +### Set up modular embeds with web components or React -If you'd like to share your data with the good people of the internet, admins can create a [public link](./public-links) or embed a question or dashboard directly in your website. +Whichever way you authenticate, you can set up modular embeds two ways. -**When to use public links and embeds**: One-off charts and dashboards. Admins can use public links when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don't care who sees the data; you want to make the item available to everyone. +- **Web components**: a script tag plus HTML elements like ``. Web components have no build step and no framework requirement, so they work in plain HTML, Vue, Svelte, Rails, React, or any framework you like. Metabase's [in-app wizard](./modular-embedding) writes the code for you. +- **React SDK**: React components that you import and compose yourself. The [SDK](./sdk/introduction) gives you more control: you can build custom layouts and [customize behavior with plugins](./sdk/plugins). -## Full app embedding +If your app runs on React and you want that extra control, go with the SDK. Otherwise start with web components. You can always move to the SDK later. -[Full app embedding](./full-app-embedding) allows you to embed the entire Metabase app in an iframe, and integrate Metabase SSO with your app's authentication. +## Comparison between SSO and guest embeds + +All SSO options require a Pro or Enterprise plan. -## Comparison of embedding types - -| Action | [Modular SDK](./sdk/introduction) | [Modular SSO](./modular-embedding) | [Modular Guest](./guest-embedding) | [Full app](./full-app-embedding) | [Public](../embedding/public-links) | -| ------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------------------- | ------------------------------------- | ----------------------------------- | -------------------------------------- | -| Charts and dashboards | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Filter widgets](/glossary/filter-widget) | ✅ | ✅ | ✅ | ✅ | ✅ | -| Export results\* | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Locked filters](./static-embedding-parameters#restricting-data-in-a-static-embed-with-locked-parameters) | ❌ | ❌ | ✅ | ❌ | ❌ | -| [Data segregation](../permissions/embedding) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Drill-through menu](../questions/visualizations/drill-through) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Query builder](../questions/query-builder/editor) | ✅ | ✅ | ❌ | ✅ | ❌ | -| [Basic appearance customization](../configuring-metabase/appearance)\*\* | ✅ | ✅ | ✅ | ✅ | ✅ | -| [Advanced theming](./appearance) | ✅ | ✅ | ❌ | ❌ | ❌ | -| [Usage analytics](../usage-and-performance-tools/usage-analytics) | ✅ | ✅ | ❌ | ✅ | ❌ | -| Embed individual Metabase components | ✅ | ✅ | ❌ | ❌ | ❌ | -| Manage access and interactivity per component | ✅ | ✅ | ❌ | ❌ | ❌ | -| Custom layouts | ✅ | ❌ | ❌ | ❌ | ❌ | -| Customize behavior with [plugins](./sdk/plugins) | ✅ | ❌ | ❌ | ❌ | ❌ | -| [Custom visualizations](../questions/visualizations/custom) | ✅ | ❌ | ❌ | ❌ | ❌ | -| AI chat | ✅ | ✅ | ❌ | ✅ | ❌ | +| Feature | SSO | Guest | +| ----------------------------------------------------------------------------------------- | --- | ----- | +| Charts | ✅ | ✅ | +| Dashboards | ✅ | ✅ | +| [Filter widgets](/glossary/filter-widget) | ✅ | ✅ | +| Export results\* | ✅ | ✅ | +| [Basic appearance customization](../configuring-metabase/appearance)\*\* | ✅ | ✅ | +| Row-level data segregation | ✅ | ✅ | +| [Drill-through menus](../questions/visualizations/drill-through) | ✅ | ❌ | +| [Query builder](../questions/query-builder/editor) | ✅ | ❌ | +| [SQL editor](../questions/native-editor/writing-sql) | ✅ | ❌ | +| [AI chat](./sdk/ai-chat) | ✅ | ❌ | +| [Collection browser](./sdk/collections) | ✅ | ❌ | +| Advanced [Tenant](./tenants) and [permissions](../permissions/embedding) management | ✅ | ❌ | +| [Advanced theming](./appearance) | ✅ | ❌ | +| [Usage analytics](../usage-and-performance-tools/usage-analytics) | ✅ | ❌ | +| Customize layouts and behavior with [plugins](./sdk/plugins) | ✅ | ❌ | +| [Locked filters](./guest-embedding#locked-parameters)\*\*\* | ❌ | ✅ | \* Each embedding type allows data downloads by default, but only [Pro and Enterprise](/pricing/) plans can disable data downloads. \*\* Requires a [Pro and Enterprise](/pricing/) plan for any embedding type. -### Should you use the Modular embedding SDK? +\*\*\* SSO embeds don't need locked filters. Since Metabase knows who's viewing an SSO embed, you can segregate data with [permissions](../permissions/embedding) instead. There's a little more set up, but much less long-term overhead. + +## Full app embedding + +[Full app embedding](./full-app-embedding) allows you to embed the entire Metabase app in an iframe, and integrate Metabase SSO with your app's authentication. + +## Public links and embeds -If your app uses React, you can go with the modular embedding SDK, but you don't need to. +If you'd like to share your data with the good people of the internet, admins can create a [public link](./public-links) or embed a question or dashboard directly in your website. A public link is a URL you can hand to anyone. A public embed is an iframe snippet you drop into one of your pages. Neither one is really an embedding setup — there's no authentication, and anyone with the link can see the data. -The modular embeds that you can set up in the [in-app wizard](./modular-embedding) are built on top of the Modular embedding SDK. Using the SDK just gives you slightly more customization (see the table above), but your app has to use React. You can always start with modular embedding, then move to the SDK if you really need that extra customization. Both support SSO and Guest embeds. +**When to use public links and embeds**: one-off charts and dashboards. Admins can use public links when you just need to show someone a chart or dashboard without giving people access to your Metabase. And you don't care who sees the data; you want to make the item available to everyone. ## Resources for AI agents diff --git a/_docs/v0.63/embedding/modular-embedding.md b/_docs/v0.63/embedding/modular-embedding.md index 891cef6b03..71b6d22d51 100644 --- a/_docs/v0.63/embedding/modular-embedding.md +++ b/_docs/v0.63/embedding/modular-embedding.md @@ -58,7 +58,7 @@ You can also go to **Admin > Embedding > Modular embedding** and click **New emb {% include plans-blockquote.html feature="Authenticated modular embedding" convert_pro_link_to_embedding=true %} -With SSO, Metabase can know who is viewing the embed, and it can unlock all of its bells and whistles (see this [comparison between SSO and guest embeds](./introduction#comparison-of-embedding-types)). +With SSO, Metabase can know who is viewing the embed, and it can unlock all of its bells and whistles (see this [comparison between SSO and guest embeds](./introduction#comparison-between-sso-and-guest-embeds)). This page covers the [SSO setup for your Metabase](./authentication). If you don't need to set up SSO, check out the [guest embed docs](./guest-embedding). diff --git a/_docs/v0.63/embedding/parameters.md b/_docs/v0.63/embedding/parameters.md index 46d8881844..a34306211f 100644 --- a/_docs/v0.63/embedding/parameters.md +++ b/_docs/v0.63/embedding/parameters.md @@ -14,6 +14,8 @@ summary: 'Pass parameter values to embedded dashboards and SQL questions in modu This page covers how to pass parameter values to embedded dashboards and SQL questions. +The props and attributes here set values that whoever's viewing the embed can still change. To set a value your app controls and nobody can see or change, use a [locked parameter](./guest-embedding#locked-parameters) on a guest embed, or [data permissions](../permissions/embedding) on an SSO embed. See [Control parameters from your app](./chart#control-parameters-from-your-app). + ## Modular embedding SDK (React) ### Pass parameter values to a dashboard diff --git a/_docs/v0.63/embedding/query-builder.md b/_docs/v0.63/embedding/query-builder.md new file mode 100644 index 0000000000..dbc192f034 --- /dev/null +++ b/_docs/v0.63/embedding/query-builder.md @@ -0,0 +1,99 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: 'Embed the query builder' +source_url: 'https://github.com/metabase/metabase/blob/master/docs/embedding/query-builder.md' +layout: new-docs +summary: 'Embed Metabase''s visual query builder or SQL editor in your app, so people can build and save their own questions.' +--- + +# Embed the query builder + +{% include plans-blockquote.html feature="Embedding the query builder" convert_pro_link_to_embedding=true %} + +You can embed one of Metabase's query editors so people can build questions from scratch. + +- [Visual query builder](#embed-the-visual-query-builder) +- [SQL editor](#embed-the-sql-editor) + +Both query editors need a logged-in Metabase account: to run a new query, Metabase has to know who's asking, so it can work out which data they're allowed to see. In an embed, [SSO](./introduction#sso-embeds) is how you provide that account, so neither editor works in a [guest embed](./introduction#guest-embedding). Check out [SSO or guest embeds](./introduction#comparison-between-sso-and-guest-embeds). + +And because everyone queries through their own Metabase account, people can only build questions on databases their groups have permission to query. See [data permissions](../permissions/data). + +Both query editors use the same `` element as an embedded chart, so they take the same attributes and props. See the [Question component reference](./question-reference). + +To embed an existing chart instead, check out [Embed a chart](./chart). + +## Embed the visual query builder + +To let people build new questions with the visual query builder, use `new` as the question ID. + +![Query builder](./images/embedded-query-builder.png) + +As a web component: + +```html + +``` + +With the SDK: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/new-question.tsx" %} +``` + +To narrow down what people can start from, list the entity types you want in the data picker with the `entity-types` attribute (web component) or the `entityTypes` prop (SDK). For example, `entity-types="['table']"` limits the picker to raw tables. The attribute takes `"table"`, `"model"`, or both. + +## Embed the SQL editor + +![Embedded SQL editor](./images/embedded-sql-editor.png) + +To let people write native SQL, use `new-native` as the question ID. + +As a web component: + +```html + +``` + +With the SDK: + +```tsx +{% include_file "{{ dirname }}/sdk/snippets/questions/new-native-question.tsx" %} +``` + +## Let people save questions + +### Saving with web components + +With a web component, turn saving on with `is-save-enabled="true"`. `target-collection` is optional, but it's worth setting: it picks the collection that new questions land in, so people's work doesn't scatter across your Metabase. + +```html + +``` + +### Saving with the React SDK + +With the SDK, saving is already on, so `targetCollection` is all you need. Setting `targetCollection` also hides the collection picker, so nobody has to decide where their question goes. + +For the `isSaveEnabled`, `onBeforeSave`, and `onSave` props, check out [Let people save their changes](./chart#let-people-save-their-changes). + +## Customize the query builder's layout + +With the SDK, you can build your own layout out of the namespaced components inside `InteractiveQuestion`, like ``. See [InteractiveQuestion components](./question-reference#interactivequestion-components). + +## Further reading + +- [Embed a chart](./chart) +- [Question component reference](./question-reference) +- [Modular embedding](./modular-embedding) +- [Modular embedding SDK](./sdk/introduction) +- [Modular embedding components](./components) +- [Appearance](./appearance) diff --git a/_docs/v0.63/embedding/question-reference.md b/_docs/v0.63/embedding/question-reference.md new file mode 100644 index 0000000000..e71bf19c5e --- /dev/null +++ b/_docs/v0.63/embedding/question-reference.md @@ -0,0 +1,91 @@ +--- +version: v0.63 +has_magic_breadcrumbs: true +show_category_breadcrumb: true +show_title_breadcrumb: true +category: Embedding +title: 'Question component reference' +source_url: 'https://github.com/metabase/metabase/blob/master/docs/embedding/question-reference.md' +layout: new-docs +summary: 'Reference for the metabase-question web component attributes, the StaticQuestion and InteractiveQuestion SDK props, and the InteractiveQuestion layout components.' +--- + +# Question component reference + +Reference material for embedding a chart or a query editor: the attributes you can set on the `` web component, the props you can pass to the SDK's `StaticQuestion` and `InteractiveQuestion` components, and the namespaced components you can use to build your own layout. + +For how to set all this up, check out [Embed a chart](./chart) and [Embed the query builder](./query-builder). + +## `metabase-question` web component attributes + +These attributes apply to the `` web component. For the SDK, see [`StaticQuestion` props](#staticquestion-props) and [`InteractiveQuestion` props](#interactivequestion-props). + +{% include_file "{{ dirname }}/eajs/snippets/MetabaseQuestionAttributes.md" snippet="properties" %} + +## `StaticQuestion` props + +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} + +`StaticQuestion` embeds a [view-only chart](./chart#embed-a-view-only-chart). + +{% include_file "{{ dirname }}/sdk/api/snippets/StaticQuestionProps.md" snippet="properties" %} + +## `InteractiveQuestion` props + +{% include plans-blockquote.html feature="Interactive charts" convert_pro_link_to_embedding=true is_plural=true %} + +`InteractiveQuestion` embeds an [interactive chart](./chart#embed-an-interactive-chart) or [a query editor](./query-builder). + +{% include_file "{{ dirname }}/sdk/api/snippets/InteractiveQuestionProps.md" snippet="properties" %} + +## Customize the layout of an interactive chart + +By default, `InteractiveQuestion` comes with a layout that lets people view the question, apply filters and aggregations, and use the query builder: + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/customize-interactive-question.tsx" snippet="example-default-interactive-question" %} +``` + +To build your own layout, use namespaced components inside `InteractiveQuestion` (like ``): + +```typescript +{% include_file "{{ dirname }}/sdk/snippets/questions/customize-interactive-question.tsx" snippet="example-customized-interactive-question" %} +``` + +## `InteractiveQuestion` components + +These components are available via the `InteractiveQuestion` namespace (like ``). Use them to [customize the layout](#customize-the-layout-of-an-interactive-chart) of an interactive question. + +- [InteractiveQuestion.AlertsButton](./sdk/api/InteractiveQuestion#alertsbutton) +- [InteractiveQuestion.Breakout](./sdk/api/InteractiveQuestion#breakout) +- [InteractiveQuestion.BreakoutDropdown](./sdk/api/InteractiveQuestion#breakoutdropdown) +- [InteractiveQuestion.ChartTypeDropdown](./sdk/api/InteractiveQuestion#charttypedropdown) +- [InteractiveQuestion.ChartTypeSelector](./sdk/api/InteractiveQuestion#charttypeselector) +- [InteractiveQuestion.DownloadWidget](./sdk/api/InteractiveQuestion#downloadwidget) +- [InteractiveQuestion.DownloadWidgetDropdown](./sdk/api/InteractiveQuestion#downloadwidgetdropdown) +- [InteractiveQuestion.Editor](./sdk/api/InteractiveQuestion#editor) +- [InteractiveQuestion.EditorButton](./sdk/api/InteractiveQuestion#editorbutton) +- [InteractiveQuestion.Filter](./sdk/api/InteractiveQuestion#filter) +- [InteractiveQuestion.FilterDropdown](./sdk/api/InteractiveQuestion#filterdropdown) +- [InteractiveQuestion.NavigationBackButton](./sdk/api/InteractiveQuestion#navigationbackbutton) +- [InteractiveQuestion.QuestionSettings](./sdk/api/InteractiveQuestion#questionsettings) +- [InteractiveQuestion.QuestionSettingsDropdown](./sdk/api/InteractiveQuestion#questionsettingsdropdown) +- [InteractiveQuestion.QuestionVisualization](./sdk/api/InteractiveQuestion#questionvisualization) +- [InteractiveQuestion.ResetButton](./sdk/api/InteractiveQuestion#resetbutton) +- [InteractiveQuestion.SaveButton](./sdk/api/InteractiveQuestion#savebutton) +- [InteractiveQuestion.SaveQuestionForm](./sdk/api/InteractiveQuestion#savequestionform) +- [InteractiveQuestion.SqlParametersList](./sdk/api/InteractiveQuestion#sqlparameterslist) +- [InteractiveQuestion.Summarize](./sdk/api/InteractiveQuestion#summarize) +- [InteractiveQuestion.SummarizeDropdown](./sdk/api/InteractiveQuestion#summarizedropdown) +- [InteractiveQuestion.Title](./sdk/api/InteractiveQuestion#title) +- [InteractiveQuestion.VisualizationButton](./sdk/api/InteractiveQuestion#visualizationbutton) + +[InteractiveQuestion.BackButton](./sdk/api/InteractiveQuestion#backbutton) is deprecated. Use `InteractiveQuestion.NavigationBackButton` instead. + +## Further reading + +- [Embed a chart](./chart) +- [Embed the query builder](./query-builder) +- [Modular embedding components](./components) +- [Modular embedding parameters](./parameters) +- [Appearance](./appearance) diff --git a/_docs/v0.63/embedding/sdk/ai-chat.md b/_docs/v0.63/embedding/sdk/ai-chat.md index 538db636c7..4e309eeff2 100644 --- a/_docs/v0.63/embedding/sdk/ai-chat.md +++ b/_docs/v0.63/embedding/sdk/ai-chat.md @@ -14,7 +14,7 @@ summary: 'Embed an AI chat component in your app that can create queries from na ![Embedded AI chat](../images/ai-chat.png) -{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true%} +{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true %} You can embed an AI chat in your application similar to [Metabot](../modular-embedding) in Metabase. @@ -34,7 +34,7 @@ You can check out a [demo of the AI chat component](https://embedded-analytics-s {% include_file "{{ dirname }}/snippets/questions/ai-question.tsx" %} ``` -## Props +## `MetabotQuestion` props {% include_file "{{ dirname }}/api/snippets/MetabotQuestionProps.md" snippet="properties" %} diff --git a/_docs/v0.63/embedding/sdk/collections.md b/_docs/v0.63/embedding/sdk/collections.md index fcc8c9ef5a..357cdf3d2e 100644 --- a/_docs/v0.63/embedding/sdk/collections.md +++ b/_docs/v0.63/embedding/sdk/collections.md @@ -42,4 +42,4 @@ With static questions, you set a specific collection as the collection people ca 1. Set `isSaveEnabled` to true. 2. Set `targetCollection` to the collection ID you want people to save items to. -For more options, see [Question props](./questions). +For more options, see [Let people save their changes](../chart#let-people-save-their-changes). diff --git a/_docs/v0.63/embedding/sdk/dashboards.md b/_docs/v0.63/embedding/sdk/dashboards.md index 89bd5d3c7d..2d09282a81 100644 --- a/_docs/v0.63/embedding/sdk/dashboards.md +++ b/_docs/v0.63/embedding/sdk/dashboards.md @@ -81,7 +81,7 @@ By default, dashboard components take full page height (100vh). You can override ## Customizing drill-through question layout -When drilling through or clicking on a question card in the dashboard, you will be taken to the question view. By default, the question is shown in the [default layout](./questions#customizing-interactive-questions) for interactive questions. +Drilling through or clicking on a question card in the dashboard will take you to the question view with the [default layout](../question-reference#customize-the-layout-of-an-interactive-chart) for interactive questions. To customize the question layout, pass a `renderDrillThroughQuestion` prop to the `InteractiveDashboard` component, with the custom view as the child component. @@ -91,7 +91,7 @@ To customize the question layout, pass a `renderDrillThroughQuestion` prop to th {% include_file "{{ dirname }}/snippets/dashboards/custom-drill-through-question-layout.tsx" snippet="example-2" %} ``` -The questionView prop accepts a React component that will be rendered in the question view, which you can build with namespaced components within the `InteractiveQuestion` component. See [customizing interactive questions](./questions#customizing-interactive-questions) for an example layout. +The `questionView` prop accepts a React component that will be rendered in the question view, which you can build with namespaced components within the `InteractiveQuestion` component. See [customize the layout](../question-reference#customize-the-layout-of-an-interactive-chart). ## Dashboard plugins @@ -143,7 +143,7 @@ If you want to replace the existing menu with your own component, you can do so ### `mapQuestionClickActions` -You can customize what happens when people click on a data point on a dashboard with the `mapQuestionClickActions` plugin. See [mapQuestionClickActions](./questions#mapquestionclickactions). +You can customize what happens when people click on a data point on a dashboard with the `mapQuestionClickActions` plugin. See [mapQuestionClickActions](../chart#customize-what-happens-when-someone-clicks-on-a-chart). ## Creating dashboards diff --git a/_docs/v0.63/embedding/sdk/introduction.md b/_docs/v0.63/embedding/sdk/introduction.md index 02ae0bc4c7..297dc61fa0 100644 --- a/_docs/v0.63/embedding/sdk/introduction.md +++ b/_docs/v0.63/embedding/sdk/introduction.md @@ -111,7 +111,7 @@ Starting with Metabase 57, the SDK consists of two parts: Start with one of the quickstarts, then see these pages for more info on components, theming, and more. - [Authentication](../authentication) -- [Questions](./questions) +- [Embed a chart](../chart) - [AI chat](./ai-chat) - [Dashboards](./dashboards) - [Actions](./actions) diff --git a/_docs/v0.63/embedding/sdk/plugins.md b/_docs/v0.63/embedding/sdk/plugins.md index f5323eafd5..cb51960706 100644 --- a/_docs/v0.63/embedding/sdk/plugins.md +++ b/_docs/v0.63/embedding/sdk/plugins.md @@ -36,7 +36,7 @@ To use a plugin on a per-component basis, pass the plugin as a prop to the compo See docs for specific components: -- [Interactive question plugins](./questions#interactive-question-plugins) +- [Question plugins](../chart#customize-what-happens-when-someone-clicks-on-a-chart) - [Dashboard plugins](./dashboards#dashboard-plugins) ## Global plugins @@ -45,7 +45,7 @@ See docs for specific components: The plugin `mapQuestionClickActions` lets you customize what happens when people click on a data point on a dashboard or chart. `mapQuestionClickActions` can be used globally, or on component level. -See [`mapQuestionClickActions` plugin](./questions#mapquestionclickactions) for more information and examples. +See [`mapQuestionClickActions` plugin](../chart#customize-what-happens-when-someone-clicks-on-a-chart) for more information and examples. ### `handleLink` @@ -75,5 +75,5 @@ The plugins `getNoDataIllustration` and `getNoObjectIllustration` can only be us ## Further reading -- [Interactive question plugins](./questions#interactive-question-plugins) +- [Question plugins](../chart#customize-what-happens-when-someone-clicks-on-a-chart) - [Dashboard plugins](./dashboards#dashboard-plugins) diff --git a/_docs/v0.63/embedding/sdk/questions.md b/_docs/v0.63/embedding/sdk/questions.md deleted file mode 100644 index ad808441ad..0000000000 --- a/_docs/v0.63/embedding/sdk/questions.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -version: v0.63 -has_magic_breadcrumbs: true -show_category_breadcrumb: true -show_title_breadcrumb: true -category: Embedding -title: 'Modular embedding SDK - questions' -source_url: 'https://github.com/metabase/metabase/blob/master/docs/embedding/sdk/questions.md' -layout: new-docs -description: 'How to embed charts in your app with the Modular embedding SDK.' ---- - -# Modular embedding SDK - questions - -{% include plans-blockquote.html feature="Modular embedding SDK" sdk=true convert_pro_link_to_embedding=true%} - -There are different ways you can embed questions: - -- [Static question](#staticquestion). Embeds a chart. Clicking on the chart doesn't do anything. -- [Interactive question](#interactivequestion). Create new questions or edit existing ones with the visual query builder or SQL editor. Clicking on the chart gives you the drill-through menu. - -## Embedding a question - -You can embed a question using one of the question components: - -### `StaticQuestion` - -A lightweight question component. Use this component when you want to display results without letting people interact with the data. - -![Static question](../images/static-question.png) - -The component has a default height, which can be customized by using the `height` prop. To inherit the height from the parent container, you can pass `100%` to the height prop. - -#### API Reference - -- [Component](./api/StaticQuestion) -- [Props](./api/StaticQuestionProps) - -#### Example - -```typescript -{% include_file "{{ dirname }}/snippets/questions/static-question.tsx" %} -``` - -#### Props - -{% include_file "{{ dirname }}/api/snippets/StaticQuestionProps.md" snippet="properties" %} - -### `InteractiveQuestion` - -Use this component when you want to allow people to explore their data and customize question layout. - -![Interactive question](../images/interactive-question.png) - -#### API Reference - -- [Component](./api/InteractiveQuestion) -- [Props](./api/InteractiveQuestionProps) - -#### Example - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question.tsx" %} -``` - -#### Props - -{% include_file "{{ dirname }}/api/snippets/InteractiveQuestionProps.md" snippet="properties" %} - -## Pass parameters to SQL questions - -See [Modular embedding parameters](../parameters#pass-parameters-to-sql-questions). - -## Enable alerts on embedded questions - -You can let people set up [alerts](../../questions/alerts) on embedded questions by passing the `withAlerts` prop to `StaticQuestion` or `InteractiveQuestion`. Alerts require [email setup](../../configuring-metabase/email), and the question must be saved (not a new question). - -Alerts created in an embedded context only send to the logged-in user and exclude links to Metabase items. - -```tsx - -``` - -## Questions with natural language - -See [AI chat](./ai-chat). - -## Customizing interactive questions - -By default, the modular embedding SDK provides a default layout for interactive questions that allows you to view your questions, apply filters and aggregations, and access functionality within the query builder. - -Here's an example of using the `InteractiveQuestion` component with its default layout: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/customize-interactive-question.tsx" snippet="example-default-interactive-question" %} -``` - -To customize the layout, use namespaced components within the `InteractiveQuestion` component. For example: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/customize-interactive-question.tsx" snippet="example-customized-interactive-question" %} -``` - -### Interactive question components - -These components are available via the `InteractiveQuestion` namespace (e.g., ``). - -#### API Reference: - -- [InteractiveQuestion.BackButton](./api/InteractiveQuestion#backbutton) -- [InteractiveQuestion.Breakout](./api/InteractiveQuestion#breakout) -- [InteractiveQuestion.BreakoutDropdown](./api/InteractiveQuestion#breakoutdropdown) -- [InteractiveQuestion.ChartTypeDropdown](./api/InteractiveQuestion#charttypedropdown) -- [InteractiveQuestion.ChartTypeSelector](./api/InteractiveQuestion#charttypeselector) -- [InteractiveQuestion.Editor](./api/InteractiveQuestion#editor) -- [InteractiveQuestion.EditorButton](./api/InteractiveQuestion#editorbutton) -- [InteractiveQuestion.Filter](./api/InteractiveQuestion#filter) -- [InteractiveQuestion.FilterDropdown](./api/InteractiveQuestion#filterdropdown) -- [InteractiveQuestion.QuestionSettings](./api/InteractiveQuestion#questionsettings) -- [InteractiveQuestion.QuestionSettingsDropdown](./api/InteractiveQuestion#questionsettingsdropdown) -- [InteractiveQuestion.QuestionVisualization](./api/InteractiveQuestion#questionvisualization) -- [InteractiveQuestion.ResetButton](./api/InteractiveQuestion#resetbutton) -- [InteractiveQuestion.SaveButton](./api/InteractiveQuestion#savebutton) -- [InteractiveQuestion.SaveQuestionForm](./api/InteractiveQuestion#savequestionform) -- [InteractiveQuestion.Summarize](./api/InteractiveQuestion#summarize) -- [InteractiveQuestion.SummarizeDropdown](./api/InteractiveQuestion#summarizedropdown) -- [InteractiveQuestion.DownloadWidget](./api/InteractiveQuestion#downloadwidget) -- [InteractiveQuestion.DownloadWidgetDropdown](./api/InteractiveQuestion#downloadwidgetdropdown) -- [InteractiveQuestion.Title](./api/InteractiveQuestion#title) - -## Interactive question plugins - -You can use [plugins](./plugins) to add custom functionality to your questions. - -### `mapQuestionClickActions` - -When people click on a data point in the embedded interactive chart, Metabase shows them a menu of actions by default. The plugin `mapQuestionClickActions` allows you to customize this behavior. You can choose to: - -- Open the default Metabase menu. -- Add custom actions to that click-through menu. -- Perform immediate action without opening a menu. - -Use `mapQuestionClickActions` globally at the provider level, or on individual `InteractiveQuestion` or `InteractiveDashboard` components. For more on provider scope, see [Plugins](./plugins) - -The example below shows all the options for click action behavior. This example will: - -- Open a menu with custom actions when "Last Name" column is clicked. -- Perform an immediate action (show an alert) when the "Plan" column is clicked. -- Shows the default menu (available as `clickActions`) in all other cases. - -The behavior is determined by what `mapQuestionClickActions` returns: array of actions to open a menu, or a single action to trigger an immediate action. - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question-click-actions.tsx" snippet="example" %} -``` - -You can also customize the appearance of custom actions in the click menu. The example below shows an example of a click menu with default actions, a custom action, and a custom action with customized appearance: - -```typescript -{% include_file "{{ dirname }}/snippets/questions/interactive-question-plugins.tsx" snippet="example" %} -``` - -## Prevent people from saving changes to an `InteractiveQuestion` - -To prevent people from saving changes to an interactive question, or from saving changes as a new question, you can set `isSaveEnabled={false}`: - -```tsx -{% include_file "{{ dirname }}/snippets/questions/disable-question-save.tsx" %} -``` - -## Create and edit questions with the query builder - -![Query builder](../images/query-builder.png) - -The `InteractiveQuestion` component supports three modes: - -- `questionId="new"` — opens the visual query builder for creating new questions. -- `questionId="new-native"` — opens the SQL editor for creating new questions. -- A numeric `questionId` (e.g., `questionId={42}`) — embeds an existing question. People can click the edit button to modify it, which opens the appropriate editor (visual or SQL) based on the question type. - -### Embed the visual query builder - -To embed the query builder for creating new questions, pass `questionId="new"` to the `InteractiveQuestion` component. You can use the [`children` prop](#customizing-interactive-questions) to customize the layout. - -```tsx -{% include_file "{{ dirname }}/snippets/questions/new-question.tsx" %} -``` - -### Embed the SQL editor - -To embed the SQL editor for creating new questions, pass `questionId="new-native"` to the `InteractiveQuestion` component: - -```tsx -{% include_file "{{ dirname }}/snippets/questions/new-native-question.tsx" %} -``` - -To customize the question editor's layout, use the `InteractiveQuestion` component [directly with a custom `children` prop](#customizing-interactive-questions). diff --git a/_docs/v0.63/embedding/start.md b/_docs/v0.63/embedding/start.md index d56ddb1efe..bde425d39b 100644 --- a/_docs/v0.63/embedding/start.md +++ b/_docs/v0.63/embedding/start.md @@ -33,6 +33,18 @@ With the Modular embedding SDK, you can embed individual Metabase components wit Jump to a SDK quickstart with a sample React application. +### [Embed a chart](./chart) + +Embed a single chart, view-only or interactive, with web components or the React SDK. + +### [Embed the query builder](./query-builder) + +Embed Metabase's visual query builder or SQL editor, so people can build and save their own questions. + +### [Question component reference](./question-reference) + +Every `` attribute, the `StaticQuestion` and `InteractiveQuestion` props, and the components you can use to build your own question layout. + ### [Guest embedding](./guest-embedding) Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables.