docs: describe how the best-fit chart type is recommended #11567
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -18,3 +18,71 @@ 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). | ||
|
|
||
| ## Recommended chart type | ||
|
|
||
| When your query returns a result, Cube outlines the one chart type that best fits it and labels it | ||
| **Recommended**. It is a suggestion: every other available type stays selectable, and the outline | ||
| disappears once you pick a type yourself. | ||
|
|
||
| On a report that has no chart yet, a recommendation Cube is confident about is applied for you, and | ||
| the report names the rule it followed — for example, *Applied Line — a measure over time*. Anywhere | ||
| else the recommendation is only outlined, never applied. | ||
|
|
||
| ### What Cube looks at | ||
|
|
||
| The recommendation reads the shape of your query and its result: how many measures, dimensions and | ||
| time dimensions you selected, how many distinct values each dimension has, how long the category | ||
| labels are, and how many rows came back. Nothing is sent anywhere and nothing is saved — the | ||
| suggestion lasts for the current session only. | ||
|
Comment on lines
+36
to
+37
Contributor
There was a problem hiding this comment. "Nothing is sent anywhere" reads as a privacy guarantee but the thing being described is derived from a result set that already came back from the server, so a reader can't tell what claim is being made — that the recommendation runs client-side? that no telemetry is emitted? Suggest saying the specific thing ("the recommendation is computed in your browser and isn't persisted"), or dropping the sentence: nobody asked, and an unclear privacy claim is worse than none. |
||
|
|
||
| Where a threshold is involved, it comes from | ||
| [Draco](https://ieeexplore.ieee.org/document/8440847) (Moritz et al., *Formalizing Visualization | ||
| Design Knowledge as Constraints*, IEEE VIS 2018), which encodes established visualization research | ||
| as rules: a category axis becomes crowded past 12 values, a color or stacking channel saturates | ||
| past 10 series, and no axis reads past 30 values. | ||
|
|
||
| Two numbers are Cube's own rather than Draco's, and are tuned by us: a mean label length of **16 | ||
| characters** counts as long, and a result over **5,000 rows** counts as large. | ||
|
|
||
| ### The conditions | ||
|
|
||
| Cube checks these in order and takes the first that matches. | ||
|
|
||
| | Recommendation | When | | ||
| | -- | -- | | ||
| | **Map** | The query contains latitude and longitude | | ||
| | **KPI** | One measure, no dimensions, and a single row | | ||
| | **Line** | A measure over a time dimension, optionally split by one category of up to 10 values | | ||
| | **Scatter** | Two or more measures with no time dimension — the shape for correlating them | | ||
| | **Stacked bar** | One measure split by two categories, the first up to 12 values and the second up to 10 | | ||
| | **Heatmap** | One measure split by two larger categories that fill enough of the grid to be worth drawing | | ||
| | **Bar** | One measure across a few categories with short labels | | ||
| | **Horizontal bar** | The same, where the labels are long or the categories too many for a vertical axis | | ||
|
Comment on lines
+58
to
+61
Contributor
There was a problem hiding this comment. Stacked bar and Horizontal bar are presented here as if they were chart types, but neither appears in this page's own list at lines 8–18 — they're variants of Bar ( Suggest naming them as variants, e.g. "Bar (stacked)" / "Bar (horizontal)", and linking to Bar. Same applies to the prose on line 83.
Comment on lines
+59
to
+61
Contributor
There was a problem hiding this comment. Dropping the Pie row resolves the unreachability problem, but the vagueness half of my earlier comment survives: these three rows are the only qualitative ones in a table that otherwise cites exact numbers (12 / 10 / 30 / 5,000), and the section above defines 12 and 16 precisely so the reader arrives expecting them.
Naming the numbers here costs a few words and makes the table self-consistent. |
||
| | **Table** | The query has no measure, two time dimensions, three or more dimensions, a category past 30 values, or a result over 5,000 rows | | ||
|
|
||
| Pie is not recommended. Its shape — one measure across a few categories — is the same one Bar | ||
| answers, and a bar chart compares those values more accurately, so Cube recommends Bar and leaves | ||
| Pie to you. It remains available in the picker like any other chart type. | ||
|
|
||
| Table's conditions are disqualifiers rather than a last preference: a query that meets any of them | ||
| has no chart encoding that reads well, so the table is the honest answer. Maps are the exception — | ||
| a map has no category axis to crowd, so a large number of plotted places is normal rather than | ||
| unreadable. | ||
|
Comment on lines
+68
to
+71
Contributor
There was a problem hiding this comment. This paragraph contradicts the table it follows. Line 50 says the conditions are checked "in order" with first match winning, and Table is listed last — but "disqualifiers rather than a last preference" means they're evaluated before the others, otherwise a 4-dimension query would match Bar or Stacked bar first and never reach Table. Either move the Table row to the top of the table (and say the first row is a disqualifier gate), or drop the "in order" framing and describe the check as "disqualifiers first, then the ordered preferences." |
||
|
|
||
| ### When nothing is recommended | ||
|
|
||
| Cube suppresses the recommendation rather than guessing. You will see no outline when: | ||
|
|
||
| - no rule matches the query cleanly; | ||
| - a value it needs is still unknown, such as the number of distinct values in a dimension; | ||
| - the result was truncated by a row limit, so the counts it would read are incomplete; | ||
| - the best fit is the chart type you already applied; | ||
| - you have already picked a type by hand in the picker you are looking at. | ||
|
|
||
| Automatic application on an empty report clears a higher bar than the outline does. It happens only | ||
| for Map, KPI, Line, Scatter and vertical Bar, only when no threshold sits within 20% of the observed | ||
| value — so a row either way would not change the answer — and never on a truncated result. Stacked | ||
| bar, heatmap and horizontal bar are offered but never applied for you: stacking asserts that the | ||
| parts compose the whole, which Cube cannot verify from a filtered result, and the others turn on a | ||
| judgment of Cube's own. | ||
|
Comment on lines
+83
to
+88
Contributor
There was a problem hiding this comment. Re-raising on the rewritten paragraph (my earlier thread went outdated when Pie was dropped from the list, but the substance is unchanged). "no threshold sits within 20% of the observed value" is an internal confidence constant — a business user can't observe it, can't act on it, and it goes stale the first time the margin is retuned. The closing rationale ("stacking asserts that the parts compose the whole… the others turn on a judgment of Cube's own") is design justification rather than usage guidance.
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"report" isn't a term in the product taxonomy in
docs-mintlify/CLAUDE.md(Account → Deployment → Workbook → Tab → Dashboard builder → Widget; plus Dashboard), and it appears nowhere else indocs/explore-analyze/charts/. This PR introduces it as a new noun in three places (lines 28, 29, 80).If the surface is a workbook tab, say "a tab with no chart yet"; if it's a dashboard widget, say widget. Whichever it is, the reader needs to know which UI this auto-apply behavior fires in — right now "report" reads as a fourth, undefined surface.