Skip to content

docs: document KPI per-block styling/format and is empty/is not empty filter operators #11450

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 1 commit into
base: master
Choose a base branch
from
+10 −3
Open

docs: document KPI per-block styling/format and is empty/is not empty filter operators #11450

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 7 additions & 2 deletions docs-mintlify/docs/explore-analyze/charts/chart-types/kpi.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ Displays a single value from your query result.
| **Row** | Which row of the result to read from |
| **Format** | Number formatting (currency, percent, etc.) |
| **Font size / color** | Text appearance |
| **Background** | Background color for the block |
| **Alignment** | Left, center, or right |

{/* TODO screenshot: Number block (hidden — replace this comment with <Frame><img src="..." /></Frame> when image is ready) */}
Expand All @@ -42,7 +43,7 @@ Displays a current value alongside a previous value with a calculated difference
| **Current field / row** | The primary value |
| **Previous field / row** | The value to compare against — can be a different column or a different row from the same column |
| **Difference format** | Absolute, percentage, or both |
| **Positive color / Negative color** | Colors applied based on whether the change is positive or negative |
| **Positive / negative / neutral color** | Colors applied based on whether the change is positive, negative, or unchanged |

@claude claude Bot Aug 2, 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 Comparison block is the one block type listed in the PR description as gaining a Background color that doesn't get a **Background** row here. Number (line 32), Progress bar (line 63), and Sparkline (line 84) all got one, and the HTML section (line 98) now says "Like the other block types, it accepts a background color" — which reads as a promise this table doesn't keep.

Suggested change
| **Positive / negative / neutral color** | Colors applied based on whether the change is positive, negative, or unchanged |
| **Positive / negative / neutral color** | Colors applied based on whether the change is positive, negative, or unchanged |
| **Background** | Background color for the block |

Fix this →


To compare to a static goal, add a column to your query that always returns the same number (e.g. a calculated field with a constant), then select it as the **Previous** field.

Expand All @@ -58,6 +59,8 @@ Shows a value relative to a target as a progress bar or circle. Useful for goal
| **Target field / row** | The goal or maximum value |
| **Style** | Bar or circle |
| **Color** | Fill color for the progress indicator |
| **Format** | Number formatting for the displayed value |
| **Background** | Background color for the block |

<Tip>
To compare against a static number like a quarterly goal, add a calculated field that always returns that number and use it as the **Target** field.
Expand All @@ -77,6 +80,8 @@ Renders a compact trend chart — either a bar or line — within the KPI tile.
| **Height / Width** | Dimensions of the sparkline in the tile |
| **Max points** | Limits the number of data points rendered |
| **Colors** | Line/fill colors |
| **Format** | Number formatting for the displayed value |
| **Background** | Background color for the block |

{/* TODO screenshot: Sparkline block showing a trend line (hidden — replace this comment with <Frame><img src="..." /></Frame> when image is ready) */}

Expand All @@ -90,7 +95,7 @@ Use text blocks for short labels and headings inside the KPI. For complex layout

### HTML

A free-form HTML block rendered inside the KPI tile. Use this for advanced custom layouts that go beyond what the other block types support.
A free-form HTML block rendered inside the KPI tile. Use this for advanced custom layouts that go beyond what the other block types support. Like the other block types, it accepts a background color.

@claude claude Bot Aug 2, 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.

Minor: "Like the other block types" over-generalizes — Text (line 88) documents no settings at all, including no background. Since HTML is the only block whose settings live in prose rather than a table, stating it directly avoids a claim about the whole set:

Suggested change
A free-form HTML block rendered inside the KPI tile. Use this for advanced custom layouts that go beyond what the other block types support. Like the other block types, it accepts a background color.
A free-form HTML block rendered inside the KPI tile. Use this for advanced custom layouts that go beyond what the other block types support. It also accepts a background color.


{/* TODO screenshot: HTML block with custom content (hidden — replace this comment with <Frame><img src="..." /></Frame> when image is ready) */}

Expand Down
4 changes: 3 additions & 1 deletion 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 @@ -18,10 +18,12 @@ The available operators depend on the type of the underlying dimension:

| Dimension type | Operators |
|---|---|
| **String** | `is`, `is not`, `contains`, `not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`, `is null`, `is not null` |
| **String** | `is`, `is not`, `contains`, `not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`, `is null`, `is not null`, `is empty`, `is not empty` |
| **Number** | `is`, `is not`, `greater than`, `greater than or equal`, `less than`, `less than or equal`, `is null`, `is not null` |
| **Time** | `is`, `is not`, `before date`, `before or on date`, `after date`, `after or on date`, `between`, `relative date`, `is null`, `is not null` |

`is empty` and `is not empty` test for an empty string and are distinct from `is null` / `is not null`, which test for a missing value.

@claude claude Bot Aug 2, 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.

Good clarification to include — the two pairs are easy to confuse. Two small wording nits: "a missing value" is vaguer than the thing it's contrasting against, and the sentence would read better naming NULL explicitly. Also worth flagging that these are value-less operators (no input required), which is the other thing a reader hitting this row wants to know.

Suggested change
`is empty` and `is not empty` test for an empty string and are distinct from `is null` / `is not null`, which test for a missing value.
`is empty` and `is not empty` test for an empty string (`''`), while `is null` / `is not null` test for a `NULL` value. Like the null checks, they take no input value.


### Single vs. multiple selection

Filters can allow either a single value or multiple values. Configure this when adding or editing the filter — multi-select is the default for string dimensions, while time and number dimensions default to a single value.
Expand Down
Loading