docs: numeric-string REST API contract and switch-dimension pre-agg matching - #11422
docs: numeric-string REST API contract and switch-dimension pre-agg matching#11422keydunov wants to merge 2 commits into
Conversation
…atching - reference/core-data-apis/rest-api/reference.mdx: update the /v1/load response Warning to reflect that all numeric values are now always serialized as JSON strings across every driver (#10949), replacing the old "most drivers" wording, and link to castNumerics. - reference/data-modeling/pre-aggregations.mdx: document that `switch`-type dimensions no longer need to be listed in a rollup's `dimensions` for pre-aggregation matching to succeed (#11346).
|
Claude finished @keydunov's task in 3m 33s —— View job Review complete — 1 medium, 3 low. Both documented behaviors verified against source; one out-of-scope edit to the metadata example looks wrong.Full reviewTodos
What checks out
Findings
Also considered and not flagged: the "regardless of the data source driver" guarantee — I could not locate the always-stringify enforcement point in the JS packages in this tree (it appears to happen below the gateway), but the claim matches what Nothing security-, performance-, or test-relevant here; docs-only, no code paths touched. |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
…eference Cube CLI's create-branch/dev-mode now fork and print a personal dev-* branch, and put/delete/rename only accept writes to the active dev-mode branch (#11351). Add a short note to the existing Data model Git workflow section.
|
Claude finished @keydunov's task in 2m 53s —— View job Docs review — 1 medium, 3 low, 1 nit · 4 prior threads still applyFull review — click to expand
Verification resultsLink targets — both resolve.
Numeric-string claim — accurate. Consistent with
New in this push:
|
| File | Line | Concern |
|---|---|---|
rest-api/reference.mdx |
1009 | member_references populated with a self-reference; contradicts id/total_amount siblings and the single-entity example of the same cube at line 898 |
rest-api/reference.mdx |
533 | Unrelated whitespace-only table-separator change |
pre-aggregations.mdx |
585 | "the pre-aggregation's built-in dimension enumeration" attributes the enumeration to the rollup; Tesseract-only constraint unstated |
rest-api/reference.mdx |
106 | Breaking change — consider naming v1.7.0 so readers on older deployments aren't misled |
The member_references one is the most worth acting on: reference.mdx:821 defines the field as "Upstream members the member is derived from", and the same orders.status dimension in the single-entity example above (line 898) still shows []. The all-entities example now contradicts a payload the docs explicitly describe as "the same format as the single-entity response above."
Not applicable
No code changes, so security, performance, error handling, and test coverage have nothing to assess here. Linting and tests weren't run — .mdx content only, and there is no docs linter wired into yarn lint for docs-mintlify.
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| "member_references": [ | ||
| { "cube": "orders", "member": "status" } | ||
| ], |
There was a problem hiding this comment.
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.
| "member_references": [ | |
| { "cube": "orders", "member": "status" } | |
| ], | |
| "member_references": [], |
|
|
||
| | Parameter | Description | Required | | ||
| | -------------------------- | -------------------------------------------------------------- | -------- | | ||
| | -------------------------- | ---------------------------------------------------------------- | -------- | |
There was a problem hiding this comment.
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.
| | -------------------------- | ---------------------------------------------------------------- | -------- | | |
| | -------------------------- | -------------------------------------------------------------- | -------- | |
| [`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. |
There was a problem hiding this comment.
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:
- "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/whendefinition) is re-cross-joined over the rollup scan. switchdimensions are Tesseract-only (see the<Warning>atreference/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.
| [`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. |
| 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. |
There was a problem hiding this comment.
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."
| <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 |
There was a problem hiding this comment.
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.
1 participant
Check List
Description of Changes Made
This is a docs-only PR closing gaps found while cross-checking recent
cube-js/cubechanges against/docs-mintlify.reference/core-data-apis/rest-api/reference.mdx— the/v1/loadresponseWarningstill described the pre-feat(cubeorchestrator): Use Arrow format for CubeStore response format #10949 behavior ("most drivers return numerical values as strings"). Since #10949 (breaking change, merged into v1.7.0), all numeric values are always serialized as JSON strings regardless of driver. Updated the warning to state the new guaranteed contract and link to thecastNumericsrecipe.reference/data-modeling/pre-aggregations.mdx— added a note under thedimensionsparameter thatswitch-type dimensions no longer need to be listed in a rollup'sdimensionsfor pre-aggregation matching to succeed, per #11346. Previously this required materializing the dimension into the rollup (cross-joining its value enumeration) purely to satisfy the matcher; that requirement is now gone, and rollups that omit the dimension still match and execute correctly.reference/cli.mdx— added a short note to the existing "Data model Git workflow" section clarifying that--dev-modeforks and prints a personaldev-*branch, and thatput/delete/renameonly accept writes to the active dev-mode branch, per #11351.No code changes.
Test plan
🤖 Generated with Claude Code
https://claude.ai/code/session_01LkeKoVdBbUe8eVBRhr7BHJ