From abc9190c0f5113f59e6533a87e926f67f2739a60 Mon Sep 17 00:00:00 2001 From: Mike Nitsenko Date: Sat, 15 Aug 2026 01:24:57 +0500 Subject: [PATCH 1/4] docs(dbt): explain per-model schema resolution and the dbt target setting (#11561) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(dbt): explain per-model schema resolution and the dbt target setting The dbt integration page described the schema as a single value you configure, which was never quite true and is actively misleading for projects whose models build into several schemas. Generated cubes take their schema per model, from whatever dbt resolved for that model. The troubleshooting entry for "a generated cube points at the wrong table or schema" was the worst of it: it told you to check that the schema field matches where your models land, which is the one thing that isn't the cause. - New "Models in several schemas" section: schemas resolve per model, plus a table of what `+schema: analytics` becomes under dbt's default `generate_schema_name` (`_analytics`) versus a production override (`analytics`). - Warning that a `{% if target.name == 'prod' %}` override REQUIRES setting the dbt target — otherwise the macro takes its fallback branch and every model collapses onto the target schema, which is exactly how a multi-schema project ends up with every cube pointing at one schema. - Connection fields: "dbt models schema" is now "dbt target schema", described as the default for models that don't declare their own, and the optional "dbt target" field is documented. - "What gets generated" now states that the schema segment of `sql_table` is per model. - Troubleshooting rewritten symptom-first: all cubes on one schema (set the target), all cubes prefixed (dbt's default, working as documented), one cube wrong (that model's own config). Matches the console-ui field labels and behavior. * docs(dbt): correct the dbt target description, drop a dangling anchor Review feedback on #11561. - **dbt target row was misleading.** It said the name matches "an output in your dbt project", which would send readers looking for a profiles.yml that Cube never reads: the pull generates its own profile in a sandbox (`/.profiles/profiles.yml`) with a single output named after this field, and `dev` is Cube's default when the field is blank — not the `target:` key from a committed profiles.yml. Reworded to say the name doesn't have to match anything in the repository, and that what it actually does is set `target.name` for `generate_schema_name`. - **Dropped the "No custom schemas anywhere" table row.** Its cell was "(n/a)", which contradicted the column asking what `+schema: analytics` resolves to. The point it carried is already in the paragraph above. - **Removed an anchor to an Accordion title.** Mintlify only generates heading slugs for ##/###, so the link was a no-op; the entry is now named in prose. My original anchor check matched accordion titles as if they were headings, which is exactly why this got through — re-verified with headings only, and all nine remaining in-page anchors resolve. --- docs-mintlify/docs/integrations/dbt.mdx | 83 ++++++++++++++++++++----- 1 file changed, 69 insertions(+), 14 deletions(-) diff --git a/docs-mintlify/docs/integrations/dbt.mdx b/docs-mintlify/docs/integrations/dbt.mdx index aa80e1796286f..252b5785db9b2 100644 --- a/docs-mintlify/docs/integrations/dbt.mdx +++ b/docs-mintlify/docs/integrations/dbt.mdx @@ -61,9 +61,11 @@ an opt-in option that reads real column types from your warehouse. - **Read access to that repository** — either a personal access token (PAT) for HTTPS, or the ability to register a read-only deploy key for SSH. - For the generated cubes to return data, the dbt models must already be **built into - your warehouse** (via your normal production `dbt run`) in the schema you configure - below. dbt pull generates cube definitions that point at `schema.`; it does - not create the underlying tables. + your warehouse** by your normal production `dbt run`. dbt pull generates cube + definitions that point at each model's relation; it does not create the underlying + tables. Models may live in **several schemas** — the schema is resolved per model + from your dbt project, not taken from a single setting (see + [Models in several schemas](#models-in-several-schemas)). ## Connect your dbt repository @@ -85,7 +87,8 @@ Expand the **dbt project** section. | **Repository URL** | The clone URL of the repo that contains your dbt project, e.g. `https://github.com/your-org/your-repo.git` or `git@github.com:your-org/your-repo.git`. | | **Project path** | The path to the dbt project inside the repository (the folder containing `dbt_project.yml`). Use `.` if the project is at the repository root. | | **Branch** | The branch of the dbt repository to sync. Defaults to the repository's default branch. | -| **dbt models schema** | The schema or dataset where your production dbt run builds its tables. Generated cubes will query the models in this schema. | +| **dbt target schema** | Your dbt **target schema** — the default for models that don't declare a schema of their own. Models that set a custom schema in dbt resolve to that schema instead; see [Models in several schemas](#models-in-several-schemas). | +| **dbt target** | *Optional.* The dbt target name the pull runs as. Defaults to `dev`. It doesn't have to match anything in your repository — Cube generates its own `profiles.yml` for the pull — but it is what your project's `generate_schema_name` macro sees as `target.name`. Set it if your project picks schemas per environment; see [Models in several schemas](#models-in-several-schemas). | @@ -132,6 +135,39 @@ Click **Save dbt settings**. Saving these settings does not restart your deployment. +## Models in several schemas + +Generated cubes take their schema **per model**, from what dbt resolved for that +model — so a project that builds into `analytics`, `reports` and `intermediate` +produces cubes pointing at all three. **dbt target schema** is not applied to every +model; it is the default for models that don't declare a schema of their own. + +dbt decides each model's schema at parse time by calling its `generate_schema_name` +macro, so what you get depends on which macro your project uses: + +| Your dbt project | A model with `+schema: analytics` resolves to | +| --- | --- | +| dbt's **default** `generate_schema_name` | `_analytics` — the custom name is **appended** to your target schema | +| A `generate_schema_name` override that returns the custom name in production | `analytics` | + +The first row is dbt's documented default and is often not what people expect; +the second is the common override +([dbt: custom schemas](https://docs.getdbt.com/docs/build/custom-schemas)). + + +If your project overrides `generate_schema_name` and keys it on the environment — +the widespread `{% if target.name == 'prod' %}` pattern — you **must** set **dbt +target** to that production target name. Otherwise the macro takes its fallback +branch and every model collapses onto the **dbt target schema** value, so every +generated cube points at one schema. + + +To see what a pull actually resolved, open any generated `.yml` and read its +`sql_table` — the schema in it is the one dbt picked for that model. If every cube +carries the same schema and your project expects several, that's the misconfigured +target described in the warning above. (Cube support can also see a per-model +declared-vs-resolved breakdown in the sync logs for a given pull.) + ## Configure pull settings Pull options are saved on the integration itself, so every pull — manual or @@ -403,12 +439,15 @@ For each dbt model in your project: `` with title `<model alias or name>`. - **`sql_table`** is set to the model's fully-qualified relation, `database.schema.model` (empty parts are dropped, so e.g. Postgres and Athena - yield `schema.model`). On Databricks, the first segment is the catalog: the + yield `schema.model`). The **`schema` is taken per model** from what dbt resolved + for it, so a project whose models build into several schemas produces cubes + pointing at several schemas — see [Models in several schemas](#models-in-several-schemas). + On Databricks, the first segment is the catalog: the value of the deployment's `CUBEJS_DB_DATABRICKS_CATALOG` environment variable, or `hive_metastore` if it isn't set. On ClickHouse, cubes also yield - `schema.model`: the **dbt models schema** you configure *is* the ClickHouse - database, so `CUBEJS_DB_NAME` doesn't affect the generated `sql_table` (it still - sets the connection's default database). + `schema.model`: on ClickHouse a schema *is* a database, so `CUBEJS_DB_NAME` + doesn't affect the generated `sql_table` (it still sets the connection's default + database). - **Each column becomes a dimension.** The dimension type is inferred from the column's `data_type` where available, then — if [Infer column types from dbt catalog](#infer-column-types-from-dbt-catalog) is @@ -711,9 +750,11 @@ Check that: <Accordion title="The pull succeeded but Playground returns no data"> -dbt pull generates cube definitions that point at `schema.<model>`, but it doesn't -build the tables. Make sure your production `dbt run` has materialized the models -into the **dbt models schema** you configured, and that the schema matches. +dbt pull generates cube definitions that point at each model's relation, but it +doesn't build the tables. Make sure your production `dbt run` has materialized the +models, and that the schema each generated cube names is where they actually landed. +Open a generated `.yml` and compare its `sql_table` against your warehouse — if the +schema is wrong, see *A generated cube points at the wrong table or schema* below. </Accordion> @@ -744,9 +785,23 @@ it. Enable **Also generate reverse joins** in the pull settings and re-run the p <Accordion title="A generated cube points at the wrong table or schema"> -The `sql_table` is derived from your dbt project and the **dbt models schema** -setting. Verify that **dbt models schema** matches where your models actually land, -and that any per-model schema/database overrides in dbt are what you expect. +The `sql_table` is whatever dbt resolved for that model, so start by asking which +schema dbt picked rather than which one you typed. + +**Every cube points at the same schema, and it's the value you put in dbt target +schema.** Your project almost certainly overrides `generate_schema_name` and keys it +on the environment (`{% if target.name == 'prod' %}`), while the pull ran under the +default `dev` target — so every model took the macro's fallback branch. Set **dbt +target** to your production target name and re-run the pull. See +[Models in several schemas](#models-in-several-schemas). + +**Every cube points at `<dbt target schema>_<something>`.** That's dbt's *default* +`generate_schema_name`, which appends a model's custom schema to the target schema. +It's working as dbt documents. If you want the bare custom names, override the macro +in your dbt project — Cube uses whatever your project resolves. + +**One cube is wrong, the rest are fine.** Check that model's own `+schema` / +`+database` config in dbt. On Databricks, the catalog segment comes from the deployment's `CUBEJS_DB_DATABRICKS_CATALOG` environment variable and defaults to From ec4c4f20b827e2152f7510ee3e2e4ec353c432f8 Mon Sep 17 00:00:00 2001 From: Gleb Sologub <mngr@users.noreply.github.com> Date: Fri, 14 Aug 2026 23:27:16 +0200 Subject: [PATCH 2/4] docs: multi-select and group move/delete of dashboard widgets (#11558) * docs: document multi-select and group move/delete of dashboard widgets * Update docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> * docs(dashboards): mark multi-select & group actions as preview (CUB-3818) --------- Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com> --- .../dashboards/widgets/index.mdx | 21 +++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx index 9d1dedfc8db1b..c703255b473c6 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx @@ -16,4 +16,25 @@ The dashboard builder supports the following widget types: In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, click **Add Text** or **Add AI Summary**, or add a **Filter** or **Time Granularity** control from the **Add Controls** group. +## Arranging widgets + +Drag any widget to move it, and use the handle in its bottom-right corner to resize it — the surrounding widgets shift to make room. + +<Warning> + +Selecting multiple widgets and moving or deleting them as a group is currently in preview, and the behavior may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate it for your account. + +</Warning> + +To work with several widgets at once, select them first: + +- **Click** a widget to select it. +- **Shift-click** to add widgets to, or remove them from, the selection. +- **Drag a marquee** — press on any empty part of the canvas and drag a rectangle over the widgets you want; every widget it touches is selected. + +With a selection in place: + +- **Move the group** — drag any selected widget and the whole selection moves together, keeping its relative arrangement. +- **Delete the group** — press **Delete** or **Backspace** to remove every selected widget at once. + [ref-workbooks]: /docs/explore-analyze/workbooks From e244c0064f043e61e09851d7502585a17bab42ed Mon Sep 17 00:00:00 2001 From: Gleb Sologub <mngr@users.noreply.github.com> Date: Fri, 14 Aug 2026 23:30:57 +0200 Subject: [PATCH 3/4] docs(dashboards): document Spacer & Divider layout widgets (#11557) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(dashboards): document Spacer & Divider layout widgets Add a Spacer & Divider page under dashboard Widgets covering the two non-data layout elements (CUB-3039): a resizable spacer that is invisible on published dashboards, and a fixed non-resizable divider line. Both follow the dashboard widget styling settings. Link the new page from the widgets index and add it to the nav. * docs(dashboards): address review — reconcile toolbar wording, tighten layout page - Update text.mdx and ai-summary.mdx to the consolidated 'Add Widgets' toolbar menu (CUB-3039 reorganized the per-type insert buttons), so they no longer contradict the widgets index. - Drop the duplicated 'invisible on the published dashboard' clause from the spacer styling bullet (already stated above). - Remove the vague removal instruction from the layout page. * docs(dashboards): mention layout elements in widgets intro + taxonomy Address non-blocking review nits: add layout elements (spacer/divider) to the widgets index frontmatter description and intro paragraph so they stay in sync with the widget list, and add a Layout entry to the widget taxonomy in docs-mintlify/CLAUDE.md. * docs(dashboards): mark Spacer & Divider as preview (CUB-3039) * Update filter widget and time grain terminology --- docs-mintlify/CLAUDE.md | 7 ++-- docs-mintlify/docs.json | 3 +- .../dashboards/widgets/ai-summary.mdx | 2 +- .../dashboards/widgets/index.mdx | 7 ++-- .../dashboards/widgets/layout.mdx | 35 +++++++++++++++++++ .../dashboards/widgets/text.mdx | 2 +- 6 files changed, 48 insertions(+), 8 deletions(-) create mode 100644 docs-mintlify/docs/explore-analyze/dashboards/widgets/layout.mdx diff --git a/docs-mintlify/CLAUDE.md b/docs-mintlify/CLAUDE.md index 645da7d6c3687..96d0a28b5bd3f 100644 --- a/docs-mintlify/CLAUDE.md +++ b/docs-mintlify/CLAUDE.md @@ -122,9 +122,12 @@ Make sure to use correct terms. On billing, pricing, and support pages, use **on - Charts - Text - Controls - - Filter widget - - Time grain switcher + - Filter + - Time granularity - AI summary + - Layout + - Spacer + - Divider - **Dashboard** - Scheduled refresh - **Semantic Model** diff --git a/docs-mintlify/docs.json b/docs-mintlify/docs.json index 5b6612efa2a71..0195b5120c9d9 100644 --- a/docs-mintlify/docs.json +++ b/docs-mintlify/docs.json @@ -114,7 +114,8 @@ "docs/explore-analyze/dashboards/widgets/charts", "docs/explore-analyze/dashboards/widgets/text", "docs/explore-analyze/dashboards/widgets/controls", - "docs/explore-analyze/dashboards/widgets/ai-summary" + "docs/explore-analyze/dashboards/widgets/ai-summary", + "docs/explore-analyze/dashboards/widgets/layout" ] }, "docs/explore-analyze/dashboards/styling", diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx index c540118c2dd66..01ad93e6edd85 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/ai-summary.mdx @@ -7,7 +7,7 @@ AI summary widgets generate a natural-language summary of the data shown on the ## Adding an AI summary -In the [dashboard builder][ref-workbooks], click **Add AI Summary** in the toolbar. The widget opens with a prompt editor — write your prompt and click **Generate Summary** to produce the first response. +In the [dashboard builder][ref-workbooks], add an AI summary from the **Add Widgets** menu in the toolbar. The widget opens with a prompt editor — write your prompt and click **Generate Summary** to produce the first response. ## Use cases diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx index c703255b473c6..d772f8919c95a 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx @@ -1,9 +1,9 @@ --- title: Widgets -description: Building blocks for dashboards — charts, text, controls, and AI summaries that you arrange on the canvas to tell your data story. +description: Building blocks for dashboards — charts, text, controls, AI summaries, and layout elements that you arrange on the canvas to tell your data story. --- -Widgets are the building blocks of a dashboard. Each tile placed on the canvas in the [dashboard builder][ref-workbooks] is a widget — a chart, a block of text, a control that viewers interact with, or an AI-generated summary. Combine them to assemble polished, interactive views of your data. +Widgets are the building blocks of a dashboard. Each tile placed on the canvas in the [dashboard builder][ref-workbooks] is a widget — a chart, a block of text, a control that viewers interact with, an AI-generated summary, or a layout element such as a spacer or divider. Combine them to assemble polished, interactive views of your data. ## Widget types @@ -13,8 +13,9 @@ The dashboard builder supports the following widget types: - [Text](/docs/explore-analyze/dashboards/widgets/text) — Add titles, descriptions, and rich formatting in Markdown - [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data or switch the time granularity - [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand +- [Spacer & Divider](/docs/explore-analyze/dashboards/widgets/layout) — Non-data layout elements for whitespace and section breaks (in preview) -In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, click **Add Text** or **Add AI Summary**, or add a **Filter** or **Time Granularity** control from the **Add Controls** group. +In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, use the **Add Widgets** menu for text, AI summaries, and layout elements, or add a **Filter** or **Time Granularity** control from the **Add Controls** group. ## Arranging widgets diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/layout.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/layout.mdx new file mode 100644 index 0000000000000..ccf61535a675b --- /dev/null +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/layout.mdx @@ -0,0 +1,35 @@ +--- +title: Spacer & Divider +description: Non-data layout elements — a spacer for whitespace and a divider line — that help you structure a dashboard. +--- + +<Warning> + +Spacer and divider widgets are currently in preview, and their behavior may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate them for your account. + +</Warning> + +Spacer and divider are non-data **layout** widgets. They carry no data of their own; you place them on the canvas alongside charts, text, and controls to add whitespace and visual structure to a dashboard. + +## Spacer + +A spacer is an empty, resizable box. Use it to add deliberate whitespace between widgets — for example, to separate a header row from the charts below it, or to push a widget into a particular column. + +A spacer is only visible while you are editing in the [dashboard builder][ref-workbooks]. On the published dashboard (including [embedded views](/embedding/iframe/dashboards)) it renders as empty space, so it never draws a card or border for viewers. + +## Divider + +A divider is a horizontal separator line that breaks up the layout flow — a lightweight way to signal the boundary between sections of a dashboard. Unlike other widgets, a divider is a fixed height and **cannot be resized** vertically. + +## Adding a layout widget + +In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Spacer** or **Divider**. The widget is added to the canvas, where you can drag it into place and (for a spacer) resize it. + +## Styling + +Both widgets follow the dashboard's [widget styling settings](/docs/explore-analyze/dashboards/styling): + +- The **divider** draws its line using the widget **border** width, style, and color. +- A **spacer** picks up the same border and background settings while you are editing, so its bounds are easy to see. + +[ref-workbooks]: /docs/explore-analyze/workbooks diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/text.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/text.mdx index 0133a12811c05..4da4d69b76da2 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/widgets/text.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/text.mdx @@ -7,7 +7,7 @@ Text widgets render Markdown content directly on the dashboard. Use them to add ## Adding a text widget -In the [dashboard builder][ref-workbooks], click **Add Text** in the toolbar. A new text widget is added to the canvas with an empty editor. +In the [dashboard builder][ref-workbooks], open the **Add Widgets** menu in the toolbar and choose **Text**. A new text widget is added to the canvas with an empty editor. ## Use cases From 748d522cf0ea76cf2f1b342cd6d26e50357c58b8 Mon Sep 17 00:00:00 2001 From: Gleb Sologub <mngr@users.noreply.github.com> Date: Fri, 14 Aug 2026 23:37:09 +0200 Subject: [PATCH 4/4] docs(dashboards): document drag-to-place for dashboard widgets (CUB-3179) (#11555) --- .../explore-analyze/dashboards/widgets/index.mdx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx index d772f8919c95a..c11b8126a0bb6 100644 --- a/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx +++ b/docs-mintlify/docs/explore-analyze/dashboards/widgets/index.mdx @@ -15,7 +15,20 @@ The dashboard builder supports the following widget types: - [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand - [Spacer & Divider](/docs/explore-analyze/dashboards/widgets/layout) — Non-data layout elements for whitespace and section breaks (in preview) -In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, use the **Add Widgets** menu for text, AI summaries, and layout elements, or add a **Filter** or **Time Granularity** control from the **Add Controls** group. +## Adding widgets + +Add widgets from the toolbar at the top of the dashboard builder: pick reports from the **Charts** picker to add charts, use the **Add Widgets** menu for text, AI summaries, and layout elements, or add a **Filter** or **Time Granularity** control from the **Add Controls** group. + +Each toolbar item can be added in two ways: + +- **Click** it to drop the widget into the first open spot on the canvas. +- **Drag** it from the toolbar onto the canvas to place it exactly where you want. As you drag, a full-size placeholder previews the widget's footprint and the surrounding widgets reflow to open a slot; release to drop it there. Dragging is especially handy on dense dashboards, where clicking would otherwise place the new widget far down the page. + +<Warning> + +Dragging a toolbar item to place it exactly (drag-to-place) is currently in preview, and the behavior may still change. Reach out to the [Cube support team](/admin/account-billing/support) to activate it for your account. Clicking to add a widget is available to everyone. + +</Warning> ## Arranging widgets