Skip to content

docs: fill in several undocumented Cube Cloud features #11552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
keydunov wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs: fill in several undocumented Cube Cloud features #11552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
11559ec
docs: document regtype/regtype[] cast support in SQL API
claude Aug 14, 2026
3a71a8a
docs: document several undocumented Cube Cloud features
claude Aug 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs-mintlify/admin/account-billing/ai-tokens.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,6 +68,14 @@ packages are added to a shared pool accessible by all users in the account.

Contact your account executive for details on purchasing token packages.

## Embedded users

AI token usage by [embedded][ref-embedding] end users is not drawn from the account's
per-seat token grants — it is billed separately through token packages, then as
on-demand consumption. By default there is no on-demand spending limit for embedded
usage; set one to cap it, the same way you would for on-demand consumption above. Free
plan accounts are unaffected, since they have no seats.
Comment on lines +71 to +77

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section crosses the page's own customer-type split without acknowledging it. The Overview (lines 13–19) partitions everything into on-demand customers (per-seat grants → on-demand consumption) and contract customers (pooled token packages). This paragraph applies both paths to the same embedded usage — "billed separately through token packages, then as on-demand consumption" — which is a third billing mode. That may well be correct, but as written it reads like a contradiction. Naming the order explicitly would fix it: packages are drawn down first if the account has any, and anything beyond that (or all of it, for an account with no packages) falls to on-demand.

Two smaller points in the same block:

  • "Free plan accounts are unaffected, since they have no seats" — the Free tier section immediately below says "each user on a free plan receives an individual monthly token allowance," so "no seats" is doing subtle work a reader won't follow. If the real statement is that free accounts can't have embedded users at all, say that; if it's that embedded usage on a free plan draws from the free allowance, say that instead.
  • "By default there is no on-demand spending limit for embedded usage" — is this a separate limit from the account-wide "monthly on-demand spending limit" at line 56, or does the same setting cover embedded once you set it? "set one … the same way you would for on-demand consumption above" is ambiguous between the two, and the answer decides whether an admin who already set an account limit is protected.

Also, [ref-embedding]: /embedding (line 131) is the first bare /embedding link in the docs — every other reference goes to a sub-path (/embedding/iframe/...). docs.json:427 registers that page as "embedding/index", not as a group root: the way docs/explore-analyze/dashboards/index is (docs.json:108), so it's worth clicking through on the Mintlify preview to confirm /embedding resolves rather than 404s.


## Free tier

Each user on a free plan receives an individual monthly token allowance. This
Expand Down Expand Up @@ -120,3 +128,4 @@ different reasoning path.

[ref-ai-overview]: /admin/ai
[ref-byom]: /admin/ai/bring-your-own-model
[ref-embedding]: /embedding
13 changes: 13 additions & 0 deletions docs-mintlify/docs/explore-analyze/charts/chart-types/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,16 @@ Cube includes a library of built-in chart types covering the most common visuali
- [HTML](/docs/explore-analyze/charts/chart-types/html)

For configuration options that apply across chart types — axes, color, series settings, tooltips — see [Configure charts](/docs/explore-analyze/charts/configuration).

## Searching for a chart type

The chart type picker's search box also resolves chart concepts Cube doesn't ship as a
dedicated type — searching "gauge," "waterfall," "sankey," "treemap," "radar," "sunburst,"
or "choropleth" surfaces the closest built-in alternative and what it can and can't do,
for example pointing "gauge" to a KPI's progress ring. The search also indexes existing
settings — donut shape, map projection, small multiples, color-scale rules — so they're
findable by name even if you don't know which chart type or tab they live under.

Chart types that don't fit your current query are greyed out in the picker, with a
tooltip naming what's missing (for example, "Needs 1 measure" or "Needs 2 time
dimensions").
9 changes: 9 additions & 0 deletions docs-mintlify/docs/explore-analyze/charts/chart-types/pie.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,12 @@ Drag the **Inner radius** slider in the Style tab or enter a pixel value. Settin
## Color and slice ordering

Slices are colored using the active [color palette](/docs/explore-analyze/charts/configuration/color-and-stacking) in palette order, matched to the sort order of your query results. To change which slice appears first, adjust the sort in the results table.

## Grouping small slices

Use **Slice grouping** in the Fields tab to collapse low-value categories into a single named slice instead of cluttering the chart with slivers. Choose one of two modes:

- **Minimal share** — group any category below a percentage threshold you set.
- **Top N values** — keep only the top N categories by value and group the rest.

The grouped slice's name is editable (defaults to "Other"). Its value is the sum of the measure across every category it absorbed, so it isn't directly comparable to the other slices, which each show one category's exact value.
7 changes: 6 additions & 1 deletion docs-mintlify/docs/explore-analyze/charts/configuration/small-multiples.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,12 @@ Pick a dimension in **Split by** and the chart is replaced by one panel per valu

Only dimensions are offered. Splitting by a measure is not supported — a measure has no discrete values to make panels from.

### Splitting by a second dimension

Once **Split by** is set, a **Second dimension** picker appears. Pick a dimension there to
lay panels out on a 2-D grid — the first dimension's values run down the rows and the
second dimension's values run across the columns, instead of a single row of panels.
Comment on lines +20 to +24

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"instead of a single row of panels" contradicts the rest of the page. Single-dimension splits are already laid out as a grid — line 32 says the Grid option is "Columns × rows, up to 5 × 5. Both are preselected from the number of distinct values in the split dimension, so a four-value dimension opens as a 2 × 2 grid." A reader who just read that will hit this sentence and conclude one of the two is wrong. Dropping the trailing clause fixes it; the "rows = first dimension, columns = second" sentence carries the meaning on its own.

Suggested change
### Splitting by a second dimension
Once **Split by** is set, a **Second dimension** picker appears. Pick a dimension there to
lay panels out on a 2-D grid — the first dimension's values run down the rows and the
second dimension's values run across the columns, instead of a single row of panels.
### Splitting by a second dimension
Once **Split by** is set, a **Second dimension** picker appears. Pick a dimension there to
lay panels out on a 2-D grid — the first dimension's values run down the rows and the
second dimension's values run across the columns, rather than filling the grid
left-to-right with a single dimension's values.

Two follow-on sections are still written as if only one split dimension exists, and are worth a sentence each now that the limitation bullet is gone:

  • Grid (line 32) — if rows/columns are now driven by the two dimensions' distinct values, is the picker still user-settable in 2-D mode, or does it become read-only? "Both are preselected from the number of distinct values in the split dimension" is singular.
  • How many panels are drawn (lines 45–51) — "when a dimension has more values than the grid has tiles, the chart draws the first ones in the current sort order" and Sort panels by both assume one axis of values. With two dimensions, truncation and sorting presumably apply per axis; saying so avoids guesswork.


## Options

These options appear once a **Split by** dimension is chosen.
Expand Down Expand Up @@ -54,7 +60,6 @@ A legend is shared across the grid rather than repeated per panel. Clicking a le

## Limitations

- **One split dimension.** One dimension fills the grid, panel by panel. Splitting by two dimensions at once — one down the rows and another across the columns — is not supported.
- **Cartesian charts only.** Bar, line, area, and scatter. Pie, table, KPI, heatmap, boxplot, map, and HTML charts cannot be split.
- **Panel labels are not configurable.** Each panel is labeled with its dimension value; the font, size, and color are fixed.
- **The split is enabled on a single-view chart.** A chart that already carries data labels, a reference line, or a second Y axis series cannot be split — turn the split on first. The order is the only constraint: once a chart is split, data labels and reference lines can be added freely and are drawn in every panel.
8 changes: 8 additions & 0 deletions docs-mintlify/docs/explore-analyze/dashboards/widgets/charts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,15 @@ Each chart shows the name of the underlying workbook tab as its title. To rename

Use **Hide Title** in the widget's settings menu to suppress the title on the dashboard — useful when the chart's content already makes the subject obvious, or when an adjacent [text widget][ref-text] provides its own heading. Choose **Show Title** in the same menu to bring it back.

## Downloading a chart

Open a chart widget's `⋮` menu on a published dashboard and choose **Download as CSV**,
**Download as PNG**, or **Download as PDF** to export just that chart, without downloading
the whole dashboard. Requires the **Download data** permission. See [Download as PNG or

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The permission claim conflicts with the whole-dashboard section it links to.

docs/explore-analyze/dashboards/index.mdx:83 gates dashboard-level PNG/PDF on a different permission entirely:

Available to users with Manage permission on the workbook that owns the dashboard.

And Download data is described in admin/users-and-permissions/custom-roles.mdx:122 as CSV-scoped:

Download query results as CSV from workbooks, Analytics Chat, and published dashboards.

So one blanket "Requires the Download data permission" across all three formats is very likely wrong for at least PNG/PDF — either they follow the dashboard rule (Manage on the owning workbook), or per-widget image export deliberately diverges from whole-dashboard export, which is surprising enough to state explicitly. A reader with Download data but not Manage can't tell from this page which of the three menu items they'll actually see.

Please confirm against the implementation and split if the gates differ, e.g.:

Suggested change
the whole dashboard. Requires the **Download data** permission. See [Download as PNG or
the whole dashboard. **Download as CSV** requires the **Download data** permission;
**Download as PNG** and **Download as PDF** require **Manage** permission on the workbook
that owns the dashboard. See [Download as PNG or
PDF][ref-dashboard-download] for the whole-dashboard equivalent.

Minor, same paragraph: the dashboard page spells this affordance More actions (⋯); using a bare ⋮ here is a second name for the same kind of menu.

PDF][ref-dashboard-download] for the whole-dashboard equivalent.

[ref-workbooks]: /docs/explore-analyze/workbooks
[ref-dashboard-download]: /docs/explore-analyze/dashboards#download-as-png-or-pdf
[ref-controls]: /docs/explore-analyze/dashboards/widgets/controls
[ref-incompatible-controls]: /docs/explore-analyze/dashboards/widgets/controls#incompatible-controls
[ref-text]: /docs/explore-analyze/dashboards/widgets/text
6 changes: 6 additions & 0 deletions docs-mintlify/docs/explore-analyze/dashboards/widgets/controls.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,12 @@ For [time granularity switchers][ref-time-grain], the dimension picker is restri

Mappings are also configurable by AI agents when they build or edit a dashboard, so an agent can wire controls across charts that use different semantic views without you needing to revisit each chart manually.

#### Mapping suggestions across views

When a chart's semantic view differs from the dimensions the dashboard's controls already target, the chart shows a banner — "Chart not connected to all filters" — naming how many controls could be connected to it. Click **Review** to open **Controls mapping** with name-matched dimensions on the chart's view already suggested for each control, or **Dismiss** to hide the banner for that chart.

Suggestions are staged, not applied automatically — each proposed mapping is marked "Mapping suggestion. Save to apply." until you save. Saving shows a confirmation ("N controls connected") with an **Undo** action.

[ref-time-grain]: #time-granularity-switcher

[ref-workbooks]: /docs/explore-analyze/workbooks
Expand Down
7 changes: 6 additions & 1 deletion docs-mintlify/docs/integrations/mcp-server.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,7 +187,8 @@ For any MCP-compatible client:

An MCP client is not locked to a single deployment for the whole session. After
connecting, it can discover the deployments and agents you can access and target a
specific one on each request.
specific one on each request — every tool accepts an optional `deploymentId`, validated
on each call against the deployments you can actually access.

Three tools work together:

Expand All @@ -205,6 +206,10 @@ Three tools work together:
- **`loadQueryResults`** — paginates through the results of a previous query on the same
deployment context.

Every other tool below — query, discovery, dashboard authoring, data model editing, and
pre-aggregations — also accepts an optional `deploymentId` to target a deployment other
than the session default.
Comment on lines +209 to +211

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This paragraph restates what line 190 (also added in this commit) already says — "every tool accepts an optional deploymentId" — and the validation half of line 191 duplicates the existing paragraph at lines 231–234 ("Requests are always validated against the admin's deployment-access settings…"). docs-mintlify/CLAUDE.md asks for "say it once."

The listing of tool groups here is the part that's actually new information, so I'd keep this paragraph and trim the additions to line 190 back to the original sentence:

Suggested change
Every other tool below — query, discovery, dashboard authoring, data model editing, and
pre-aggregations — also accepts an optional `deploymentId` to target a deployment other
than the session default.
Every other tool below — query, discovery, dashboard authoring, data model editing, and
pre-aggregations — also accepts an optional `deploymentId` to target a deployment other
than the session default.

(and revert lines 189–191 to …and target a specific one on each request.)

One accuracy check while you're here: "every tool accepts an optional deploymentId" is a strong universal over 20 tools. loadQueryResults is described two lines up as operating "on the same deployment context," which reads like it does not take one. Worth confirming the claim holds for all 20 — if there are exceptions, "most tools" plus the exception list is safer than a blanket "every."


A typical client workflow:

<Steps>
Expand Down
4 changes: 4 additions & 0 deletions docs-mintlify/docs/integrations/snowflake-semantic-views.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,10 @@ From the IDE, users can pull semantic views from Snowflake and turn them into cu

This allows you to leverage existing Snowflake semantic views in Cube without manual conversion, ensuring consistency between your Snowflake and Cube definitions.

To pull only specific views instead of the whole schema, enter their names
(comma-separated, `*` wildcards supported) in the **Views** field of the pull dialog.
Leave it empty to pull every semantic view in the schema, as before.

## Push Integration

Alternatively, you can push Cube views into Snowflake as native semantic views. The push integration creates DDL from Cube's definitions and executes it in Snowflake, creating Snowflake Semantic Views that match your Cube schema.
Expand Down
14 changes: 14 additions & 0 deletions docs-mintlify/reference/core-data-apis/sql-api/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -360,6 +360,20 @@ of the PostgreSQL documentation.
| --- | --- | --- | --- |
| `TO_CHAR` | Converts a timestamp to string according to the given format | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |

### Type casts

<Info>

Learn more in the
[relevant section](https://www.postgresql.org/docs/current/sql-expressions.html#SQL-SYNTAX-TYPE-CASTS)
of the PostgreSQL documentation.

</Info>

| Cast | Description |
| --- | --- |
Comment on lines +363 to +374

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two structural notes on the new section:

1. The table drops the Pushdown / Post-processing columns that every other table under "SQL functions and operators" carries (only the trailing "Custom functions" table omits them). Silently dropping them reads as an oversight rather than as "not applicable." Since regtype casts are a pg_catalog introspection concern and never reach a data source, one short sentence above the table would resolve it — e.g. "These casts are resolved by the SQL API in introspection queries against pg_catalog; they are not pushed down to the data source."

2. Placement. Sections 195–361 all mirror the Postgres functions docs and are roughly in that doc's order; this one links to sql-expressions.html and describes syntax, not a function or operator. Inserting it between "Data type formatting functions" and "Date/time functions" breaks that run. Moving it just before "Custom functions" (line 527) — where the 2-column table shape already has precedent — would fit better.

| `::regtype`, `::regtype[]` | Resolves an OID column (e.g., `pg_attribute.atttypid`) to a Postgres type name. Used by BI tools that inspect table columns over the Postgres wire protocol. |

@claude claude Bot Aug 14, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description is accurate for ::regtype but inverted for ::regtype[]. The two casts do opposite things in the implementation:

  • ::regtype on a column identifier is rewritten to format_type(col, NULL) → yields a type name (statement.rs:1230-1240). This matches the row's wording.
  • ::regtype[] is only handled on a string literal array — '{int8,numeric,bool}'::regtype[] is expanded to ARRAY[20, 1700, 16], i.e. it resolves type names to OIDs (replace_regtype_array_cast, statement.rs:1016). There is no path that turns an OID column into an array of type names.

A reader following this row would write a.atttypid::regtype[] and get nothing useful. Splitting into two rows also lets you state the operand shape each form accepts (a bare column identifier vs. a string literal) — casts of arbitrary expressions fall through untouched (statement.rs:1259).

Suggested change
| `::regtype`, `::regtype[]` | Resolves an OID column (e.g., `pg_attribute.atttypid`) to a Postgres type name. Used by BI tools that inspect table columns over the Postgres wire protocol. |
| `::regtype` | Resolves an OID column (e.g., `pg_attribute.atttypid`) to a Postgres type name |
| `::regtype[]` | Resolves an array literal of type names (e.g., `'{int8,numeric,bool}'::regtype[]`) to the corresponding OIDs, so it can be compared against an OID column |

Worth adding a one-line example below the table, since the shape BI tools emit isn't obvious from the description alone:

SELECT a.attname, format_type(a.atttypid, NULL) AS data_type
FROM pg_catalog.pg_attribute a
WHERE a.atttypid = ANY ('{int8,numeric,bool}'::regtype[]);


### Date/time functions

<Info>
Expand Down