Skip to content

docs: numeric-string REST API contract and switch-dimension pre-agg matching #11422

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
+34 −7
Open

docs: numeric-string REST API contract and switch-dimension pre-agg matching #11422

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
ff03bf7
docs: numeric-string REST API contract and switch-dimension pre-agg m…
keydunov Jul 30, 2026
3cf83d5
docs: clarify dev-mode branch forking and write restrictions in CLI r…
keydunov Jul 30, 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
11 changes: 11 additions & 0 deletions docs-mintlify/reference/cli.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,17 @@ cube data-model merge-to-default DEPLOYMENT_ID --branch my-branch -m "add orders

`merge-to-default` merges into the deploy branch and rebuilds production.

<Info>

`--dev-mode` (on `create-branch` and `dev-mode`) forks a personal `dev-*`
branch for you rather than writing directly to the named branch, and prints
the actual forked branch name (e.g. `dev-pavel-ab12cd34`) to pass via
`--branch` on subsequent commands — or omit `--branch` to use your currently
active dev-mode session. `put`, `delete`, and `rename` only accept writes to
Comment on lines +181 to +187

@claude claude Bot Jul 30, 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 note contradicts the code sample it sits under (lines 174–176), and the sample is the part most readers will copy.

The sample does:

cube data-model create-branch DEPLOYMENT_ID my-branch --dev-mode
cube data-model put DEPLOYMENT_ID model/cubes/orders.yml --file orders.yml --branch my-branch
cube data-model merge-to-default DEPLOYMENT_ID --branch my-branch -m "add orders cube"

But per this note, --dev-mode does not create my-branch — it forks dev-<user>-<hash>, and put "only accept[s] writes to the active dev-mode branch; targeting any other branch is rejected." So put ... --branch my-branch in the sample is exactly the case the new paragraph says is rejected. A reader following the sample verbatim gets an error, then has to read the <Info> to find out why.

Since the note already says --branch can be omitted to use the active session, the cleanest fix is to make the sample the working flow and let the note explain the mechanism rather than correct the example:

cube data-model create-branch DEPLOYMENT_ID my-branch --dev-mode
# prints the forked branch, e.g. dev-alice-ab12cd34
cube data-model put DEPLOYMENT_ID model/cubes/orders.yml --file orders.yml
cube data-model merge-to-default DEPLOYMENT_ID -m "add orders cube"

(Separately: dev-pavel-ab12cd34 bakes a real teammate's name into a public docs example — a neutral placeholder like dev-alice-ab12cd34 or dev-<user>-<hash> reads better.)

I couldn't verify the underlying claims against source — the Cube Cloud CLI that implements data-model create-branch/dev-mode isn't in this repo (packages/cubejs-cli/src has no dev-mode command), so this rests on #11351 as cited in the commit message. Worth a maintainer confirming whether --branch is rejected outright or silently redirected, and whether the restriction applies to commit/pull too.

Fix this →

the active dev-mode branch; targeting any other branch is rejected.

</Info>

## Environment variables

| Variable | Description |
Expand Down
18 changes: 11 additions & 7 deletions docs-mintlify/reference/core-data-apis/rest-api/reference.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,11 +98,12 @@ Example response:

<Warning>

Currently all fetched numericals are returned in the same format as driver
returns it without any additional processing. Most of drivers return numerical
values as strings instead of javascript integer or float to ensure there's no
loss of significance. Client code should take care of parsing such numerical
values.
All numeric values in the response (e.g., `"700"` in the example above) are
serialized as JSON strings, regardless of the data source driver. This
guarantees a consistent response contract across all drivers and avoids loss
of significance for large numbers. Client code should parse numeric strings
into the appropriate type; the `castNumerics` option in the
[JavaScript SDKs][ref-cast-numerics] does this automatically.
Comment on lines +101 to +106

@claude claude Bot Jul 30, 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.

Content is accurate and consistent with recipes/core-data-api/cast-numerics.mdx (which already describes strings-always), and [ref-cast-numerics] resolves to a real page. One suggestion: since #10949 was a breaking change, consider naming the version so readers on older deployments aren't misled — the switch dimension <Warning> in reference/data-modeling/dimensions.mdx:935-937 sets the precedent ("In versions before v1.7.0, …").

Something like: "Since v1.7.0, all numeric values … Before v1.7.0, the format depended on the data source driver."


</Warning>

Expand Down Expand Up @@ -529,7 +530,7 @@ This endpoint is part of the [Orchestration API][ref-orchestration-api].
### Triggering jobs

| Parameter | Description | Required |
| -------------------------- | -------------------------------------------------------------- | -------- |
| -------------------------- | ---------------------------------------------------------------- | -------- |

@claude claude Bot Jul 30, 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.

Unrelated whitespace-only change — the separator row is now 2 chars wider than every other row in the table, so the source no longer lines up (rendering is unaffected). Worth reverting to keep the diff to the two intended edits.

Suggested change
| -------------------------- | ---------------------------------------------------------------- | -------- |
| -------------------------- | -------------------------------------------------------------- | -------- |

| `action` | Use `post` to trigger jobs | ✅ |
| `selector.contexts` | Array of objects, each containing a `securityContext` | ✅ |
| `selector.timezones` | Array of timezones | ✅ |
Expand Down Expand Up @@ -1003,7 +1004,9 @@ entities before `offset` and `limit` are applied:
"type": "string",
"sql": "${CUBE}.status",
"is_primary_key": false,
"member_references": [],
"member_references": [
{ "cube": "orders", "member": "status" }
],
Comment on lines +1007 to +1009

@claude claude Bot Jul 30, 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 edit looks incorrect, and it's outside the PR's stated scope (the description says the only changes are the numeric warning and the pre-agg note).

In this part of the /v1/meta?extended=true example, orders is the cube, and status's sql is ${CUBE}.status — a column reference, not a member reference. Compare the two siblings that were left untouched:

  • orders.id, sql: "${CUBE}.id" → "member_references": [] (line 990)
  • orders.total_amount, sql: "${CUBE}.amount" → "member_references": [] (line 971)

The populated form belongs to the orders_view section further down, where sql is ${orders.status} and the reference is genuine (lines 1062–1066). As written, the cube-level dimension now claims to reference itself, which contradicts the neighbouring entries and the view/cube distinction the example is built to illustrate.

Suggested change
"member_references": [
{ "cube": "orders", "member": "status" }
],
"member_references": [],

Fix this →

"column_references": [
{
"data_source": "default",
Expand Down Expand Up @@ -1178,3 +1181,4 @@ Keep-Alive: timeout=5
[link-tzdb]: https://en.wikipedia.org/wiki/Tz_database
[ref-control-plane-api]: /reference/control-plane-api
[self-metadata-api]: #metadata-api
[ref-cast-numerics]: /recipes/core-data-api/cast-numerics
12 changes: 12 additions & 0 deletions docs-mintlify/reference/data-modeling/pre-aggregations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -575,6 +575,17 @@ cube(`orders`, {

</CodeGroup>

<Note>

[`switch`-type dimensions][ref-switch-dim] don't need to be listed here for a
query to match this pre-aggregation. Since a `switch` dimension represents a
predefined set of values rather than stored data, Cube can resolve it from the
query filter (or the pre-aggregation's built-in dimension enumeration) even
when it's omitted from the rollup — you no longer need to include it just to
satisfy matching.
Comment on lines +580 to +585

@claude claude Bot Jul 30, 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 behavior claim checks out against dimension_matcher.rs:201-207, where a calc-group (switch) dimension short-circuits to MatchState::Full regardless of the rollup's dimensions. Two wording nits:

  1. "the pre-aggregation's built-in dimension enumeration" reads as though the rollup carries the enumeration — the opposite of the point the note is making. Per the code comment, the value is either pinned by a filter (rendered as a literal) or the enumeration (which comes from the dimension's own case/when definition) is re-cross-joined over the rollup scan.
  2. switch dimensions are Tesseract-only (see the <Warning> at reference/data-modeling/dimensions.mdx:933), so it's worth stating that this matching behavior follows the same constraint rather than leaving the reader to infer it.
Suggested change
[`switch`-type dimensions][ref-switch-dim] don't need to be listed here for a
query to match this pre-aggregation. Since a `switch` dimension represents a
predefined set of values rather than stored data, Cube can resolve it from the
query filter (or the pre-aggregation's built-in dimension enumeration) even
when it's omitted from the rollup — you no longer need to include it just to
satisfy matching.
[`switch`-type dimensions][ref-switch-dim] don't need to be listed here for a
query to match this pre-aggregation. Since a `switch` dimension represents a
predefined set of values rather than stored data, any rollup can serve it: the
value is either pinned by a query filter and rendered as a literal, or the
dimension's value enumeration is cross-joined over the rollup scan. Like
`switch` dimensions themselves, this requires Tesseract.


</Note>

### `time_dimension`

The `time_dimension` property can be any [`dimension`][ref-schema-dimensions] of
Expand Down Expand Up @@ -1840,3 +1851,4 @@ cube(`orders`, {
[ref-ref-cubes]: /reference/data-modeling/cube
[ref-custom-granularity]: /reference/data-modeling/dimensions#granularities
[ref-env-allow-non-strict]: /reference/configuration/environment-variables#cubejs-pre-aggregations-allow-non-strict-date-range-match
[ref-switch-dim]: /reference/data-modeling/dimensions#type