docs: note that the SQL API can't address custom granularities by name

[igorlukanin]

Custom granularities are advertised in /v1/meta but can't be queried through the SQL API by name — DATE_TRUNC('fiscal_quarter', …) fails at execution with Unsupported date_trunc granularity. cubesql's granularity handling is hardcoded to the eight standard units (granularity_str_to_int_order, rust/cubesql/cubesql/src/compile/rewrite/rules/utils.rs:376) and never reads the meta's granularities array.

That limitation wasn't documented on any page a user would consult before hitting it:

• The granularities reference covered interval / offset / origin / title and supported data sources, but said nothing about queryability.
• The SQL API reference didn't mention granularities at all, and listed DATE_TRUNC as fully supported with no qualification.
• The custom-granularity recipe mentioned proxy dimensions only as a convenience, not as the required path.

This adds the limitation to all three, and points at proxy dimensions as the way to query a custom granularity from the SQL API or a BI tool.

Written as current behavior — the engine-side gap is tracked separately, and if the SQL API later resolves custom grains these notes become version-scoped rather than permanent.

Verified with mint broken-links (clean) and by rendering all three pages plus every link target locally.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
cubed3	🟢 Ready	View Preview	Aug 1, 2026, 1:56 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[claude]

Claude finished @igorlukanin's task in 2m 51s —— View job

---

Review: docs-only PR, 1 medium issue (repeated across all 3 files), 1 low

The core claim — the SQL API can't address custom granularities by name — checks out against the code. One secondary claim about the GraphQL API does not.

Full review — verification notes, findings, and checklist

Todos

• Gather context (PR diff, changed files)
• Verify the central claim against cubesql
• Verify the REST / GraphQL / metadata claims against cubejs-api-gateway
• Validate every link target and anchor introduced by the diff
• Check for duplicate/stale prior review threads
• Post findings

What I verified

✅ SQL API limitation is real. granularity_str_to_int_order (rust/cubesql/cubesql/src/compile/rewrite/rules/utils.rs:376) matches exactly the eight standard units and returns None otherwise. Grepping granularities across rust/cubesql/cubesql/src turns up only test fixtures and two comments — nothing reads the meta's granularities array. The PR description's diagnosis is accurate.

✅ All new links and anchors resolve.

Link	Target	Status
#granularities	### granularities, reference/data-modeling/dimensions.mdx:1019	✅
/docs/data-modeling/dimensions#time-dimension-granularity-references	heading at docs/data-modeling/dimensions.mdx:248	✅
/reference/core-data-apis/rest-api/reference#metadata-api	## Metadata API, line 703	✅
/reference/core-data-apis/rest-api, /reference/core-data-apis/graphql-api	both dirs exist with index.mdx	✅

❌ GraphQL API claim is wrong (medium). All three pages assert custom granularities can be queried by name via the GraphQL API. They can't: TimeDimension in packages/cubejs-api-gateway/src/graphql.ts:96-127 is one static object type exposing only value + the eight defaults. It's registered once in makeSchema (graphql.ts:501) and never extended per-cube — per-cube *Members types just map time dimensions onto it via mapType (graphql.ts:132). Nothing in the file reads granularities. A query like orders { created_at { fiscal_quarter } } is rejected at schema validation, before the granularity resolver at graphql.ts:422-431 ever runs. packages/cubejs-api-gateway/src/graphql.ts is the only schema builder in the repo, so there's no dynamic extension elsewhere.

This matters because the pages are steering readers toward proxy dimensions specifically — GraphQL users need the same workaround and currently read that they don't.

Inline comments with suggested wording on all three sites:

• reference/data-modeling/dimensions.mdx:1046
• reference/core-data-apis/sql-api/reference.mdx:378
• recipes/data-modeling/custom-granularity.mdx:24

Low — unverifiable error string. Execution error: Unsupported date_trunc granularity: fiscal_quarter (sql-api/reference.mdx:382) doesn't appear anywhere in this repo; it comes from vendored DataFusion, which I couldn't reach in this sandbox. The format matches DataFusion's DataFusionError::Execution display, and you say you reproduced it — just flagging that it's coupled to an upstream string, so it may drift on a DataFusion bump.

Nit. recipes/data-modeling/custom-granularity.mdx still ends without a trailing newline (pre-existing, the diff just extends the last line region).

What's good

• Placing the limitation on all three pages a user would actually consult first — reference, API reference, and recipe — rather than one.
• Qualifying the DATE_TRUNC table row itself, not just the prose below it. The table is what gets skimmed.
• Including the verbatim error text; that's what people paste into search.
• Framing the proxy dimension as the required path in the recipe rather than a nicety.

Nothing security-, performance-, or test-related applies — this is a docs-only change with no code paths touched.

· branch `igor/core-719-docs-sql-api-custom-granularities`

[claude]

Claude finished @igorlukanin's task in 2m 4s —— View job

---

Re-review of b9ed5b9: GraphQL fix is correct in all 3 files. 1 new low-medium issue.

Full review — verification notes, findings, and checklist

Todos

• Fetch updated diff (446de99...HEAD)
• Verify the GraphQL narrowing is correct and complete across all 3 files
• Verify the new REST-API claim against the gateway
• Re-check links and anchors
• Check prior threads (all 3 already resolved by author)
• Post findings

The GraphQL correction is right, and complete

All three sites now say only the REST API addresses custom granularities by name:

File	New wording	✅
reference/data-modeling/dimensions.mdx:1044-1053	"neither the SQL API nor the GraphQL API can address them by name"	✅
reference/core-data-apis/sql-api/reference.mdx:374-380	parenthetical: GraphQL "can't address them by name either"	✅
recipes/data-modeling/custom-granularity.mdx:22-29	"SQL API and the GraphQL API can only address the default granularities"	✅

Re-confirmed against the code: TimeDimension (packages/cubejs-api-gateway/src/graphql.ts:96-127) is a static object type with value + exactly the eight defaults, never extended per-cube; the only granularit* hit in the file is the resolver at 422-431, which reads whatever field name already survived schema validation.

The new REST claim also checks out

• packages/cubejs-api-gateway/src/query.js:174 — granularity: Joi.string().max(128, 'utf8') with the comment // Custom granularities may have arbitrary names. No enum constraint.
• packages/cubejs-api-gateway/src/helpers/prepare-annotation.ts:125 — resolves td.granularity against the dimension's granularities array by name.

So "REST yes, SQL/GraphQL no" is accurate.

New finding (low-medium) — the recipe's Playground claim

recipes/data-modeling/custom-granularity.mdx:27 says a proxy dimension "is the way to query a custom granularity from Playground or a BI tool" — but the same sentence just said the REST API can address custom granularities by name, and Playground queries via REST. Client-side support is there too (cubejs-client-core/src/types.ts:451, time.ts:225). The pre-fix wording ("conveniently query them via Playground or BI tools") didn't have this tension; the necessity framing introduces it. Inline suggestion at recipes/data-modeling/custom-granularity.mdx:22-29.

Caveat: the Playground query-builder UI isn't in this repo, so if its granularity picker genuinely lists only the eight defaults, the claim holds — but then it's a UI statement, not a queryability one, and reads better said that way.

Links re-verified

Link	Target	Status
#granularities	### \granularities`, reference/data-modeling/dimensions.mdx:1019`	✅
/docs/data-modeling/dimensions#time-dimension-granularity-references	heading at docs/data-modeling/dimensions.mdx:248	✅
/reference/core-data-apis/rest-api/reference#metadata-api	## Metadata API, line 703	✅
/reference/core-data-apis/rest-api, /graphql-api, /sql-api	all three have index.mdx	✅

[ref-graphql-api] on sql-api/reference.mdx is now used (the parenthetical), so the dead-link-def concern from my earlier thread no longer applies.

Still open from the prior round

• Low — unverifiable error string. Execution error: Unsupported date_trunc granularity: fiscal_quarter (sql-api/reference.mdx:383) is a vendored-DataFusion string not present in this repo; it may drift on an upstream bump.
• Nit. recipes/data-modeling/custom-granularity.mdx still ends without a trailing newline (pre-existing).

Nothing security-, performance-, or test-related applies — docs-only, no code paths touched.

· branch `igor/core-719-docs-sql-api-custom-granularities`

[igorlukanin]

Fair, and the tension was mine to fix: REST takes arbitrary granularity names (query.js:174, max(128) with that exact comment) and Playground goes through REST, so calling a proxy dimension the way to query one from Playground contradicted the clause before it. Dropped Playground from that sentence in d117aa4fc5 rather than asserting a picker limitation I can't verify from this repo — it now reads "from those APIs or from a BI tool". Removed the orphaned [ref-playground] def and added the trailing newline while I was in there.

Leaving the Unsupported date_trunc granularity string as-is: it's what the user actually sees, and attributing it to vendored DataFusion in the docs would be noise for the reader. Worth revisiting if an upstream bump changes it.

[claude]

Claude finished @igorlukanin's task in 1m 39s —— View job

---

Re-review of d117aa4: Playground contradiction resolved. No new issues — LGTM.

Full review — verification notes and checklist

Todos

• Fetch the updated diff (446de99..HEAD)
• Verify the Playground fix reads consistently
• Re-check links, anchors, and the removed [ref-playground] def
• Re-verify the eight-granularity list against cubesql
• Resolve my stale thread
• Post findings

The Playground fix is correct

recipes/data-modeling/custom-granularity.mdx:22-28 now reads "…a proxy dimension is the way to query a custom granularity from those APIs or from a BI tool". "Those APIs" is bound by the immediately preceding clause to the SQL API and the GraphQL API, so the necessity framing no longer collides with the REST claim in the same sentence. Dropping Playground rather than asserting a picker limitation is the right call given the query builder UI isn't in this repo — agreed with your reasoning.

Cleanup checks:

Check	Result
[ref-playground] def removed	✅ line gone
Any remaining ref-playground / "Playground" usage in the file	✅ zero — no dangling reference
Trailing newline	✅ file now ends ...references\n
The ## Result screenshot at line 162	✅ unlabeled, never named Playground in prose, so removing the mention leaves nothing orphaned
Duplicate link defs from the three new ones	✅ none — ref-rest-api / ref-graphql-api / ref-sql-api / ref-proxy-granularity each defined once per file

Re-verified the substantive claims

granularity_str_to_int_order (rust/cubesql/cubesql/src/compile/rewrite/rules/utils.rs:376-394) matches exactly second, minute, hour, day, week, month, quarter, year → _ => None. The eight units enumerated in the DATE_TRUNC warning (sql-api/reference.mdx:374-375) match that arm-for-arm, with no extras or omissions.

GraphQL narrowing and the REST claim were confirmed in the previous round and are unchanged by this commit.

Threads

Resolved my own now-addressed Playground thread (PRRT_kwDOCOH19M6WLMpB). No unresolved claude threads remain; nothing to re-affirm.

Still open (both accepted, no action needed)

• Low — error string coupling. Execution error: Unsupported date_trunc granularity: fiscal_quarter (sql-api/reference.mdx:383) is a vendored-DataFusion string. Your call to keep it verbatim is the right one for the reader — noted only so it's on record if an upstream bump changes the wording.

Pre-existing nit, not introduced here

[ref-custom-granularities] (recipes/data-modeling/custom-granularity.mdx:167) is an unused link definition — it predates this PR (line 9 uses [ref-default-granularities], and nothing references the custom one). Harmless in Mintlify; a one-line delete if you're already in the file.

What's good about the final shape

The three pages now say the same thing in three registers without contradicting each other: the reference states the rule, the SQL API page gives the error text and the escape hatch, and the recipe explains why the proxy dimensions in the example are load-bearing rather than decorative. Two rounds of narrowing (GraphQL, then Playground) landed on a claim that's exactly as broad as the code supports.

Docs-only — nothing security-, performance-, or test-related applies.

· branch `igor/core-719-docs-sql-api-custom-granularities`

[claude]

Claude finished @igorlukanin's task in 1m 15s —— View job

---

Re-review after force-push (87083b5): content unchanged from the previously-approved state — LGTM. 0 new issues, 1 nit.

Full review — verification notes and checklist

Todos

• Fetch the updated diff (origin/master...HEAD)
• Diff the new tip against the previously-reviewed content
• Re-verify the SQL / GraphQL / REST claims against the code
• Re-check links, anchors, and link defs
• Check existing review threads (all 4 already resolved — nothing to resolve, nothing to re-affirm)

This synchronize is a rebase, not new content

The three commits (be6643a, 57a7650, 87083b5) are the rebased equivalents of 446de99-era be…/b9ed5b9/d117aa4. Diffing origin/master...HEAD yields byte-identical prose to the state approved in the previous round, including:

Item	State
recipes/.../custom-granularity.mdx:22-28	"…from those APIs or from a BI tool" — Playground fix intact
[ref-playground] def	✅ removed, zero remaining usages
Trailing newline	✅ file ends …-references\n
GraphQL narrowing in all 3 files	✅ present

Substantive claims re-verified against this checkout

• SQL API. granularity_str_to_int_order (rust/cubesql/cubesql/src/compile/rewrite/rules/utils.rs:376-394) matches exactly second, minute, hour, day, week, month, quarter, year → _ => None. The eight units listed in the warning (sql-api/reference.mdx:374-375) match arm-for-arm.
• GraphQL API. The only granularit* hits in packages/cubejs-api-gateway/src/graphql.ts are the resolver at 422-431, which reads whatever field name already survived schema validation. Nothing reads the meta's granularities array, so the "can't address them by name either" claim holds.
• REST API. Unchanged since last round: free-form granularity string in query.js:174, name resolution in prepare-annotation.ts:125.

Links and anchors

Link	Target	Status
#granularities	### \granularities`, reference/data-modeling/dimensions.mdx:1044`	✅
/docs/data-modeling/dimensions#time-dimension-granularity-references	heading at docs/data-modeling/dimensions.mdx:248	✅
/reference/core-data-apis/rest-api/reference#metadata-api	## Metadata API, line 703	✅
/reference/core-data-apis/{rest,graphql,sql}-api	all three have index.mdx	✅

All five new defs in sql-api/reference.mdx (520-524) are used; all four new defs in the other two files are used. No duplicates.

Nit (new, low) — link label vs. target

sql-api/reference.mdx:366 labels the link "default granularities" but [ref-granularities] points at #granularities, which is the reference section for custom granularities. A reader clicking "default granularities" lands on the custom-granularity parameter docs. Either relabel to just "granularities", or point at /docs/data-modeling/dimensions#time-dimensions (the def the recipe uses as [ref-default-granularities]). Cosmetic — the prose immediately below the table enumerates the eight defaults verbatim, so nobody is left guessing.

Pre-existing, not introduced here

• [ref-custom-granularities] (recipes/data-modeling/custom-granularity.mdx:167) is still an unused link def, predating this PR. Harmless in Mintlify.
• Low — error string coupling. Execution error: Unsupported date_trunc granularity: fiscal_quarter (sql-api/reference.mdx:383) is a vendored-DataFusion string. Accepted last round; noted only for the record if an upstream bump changes the wording.

Docs-only — nothing security-, performance-, or test-related applies.

· branch `igor/core-719-docs-sql-api-custom-granularities`

[igorlukanin]

Took the nit in e98514d6cb: the "default granularities" label now points at #time-dimensions, which enumerates the eight built-ins, instead of #granularities, which documents the custom-granularity parameter. Left the line 376 [ref-granularities] alone — that one really is about custom granularities, so its target was already right.

The two pre-existing items stay as they are: the unused [ref-custom-granularities] def predates this PR, and the vendored-DataFusion error string is what the user actually sees.

[claude]

Claude finished @igorlukanin's task in 1m 0s —— View job

---

Re-review of e98514d: the link-label nit is fixed correctly. 0 new issues — LGTM.

Full review — verification notes and checklist

Todos

• Fetch the updated diff (origin/master...HEAD)
• Verify the new [ref-default-granularities] target actually documents the built-ins
• Confirm [ref-granularities] at line 376 still points where it should
• Re-verify the SQL / GraphQL / REST claims against the code
• Re-check all link defs for duplicates and orphans
• Check review threads (all 4 already resolved — nothing to resolve or re-affirm)

The nit fix is right

sql-api/reference.mdx:366 now reads [default granularities][ref-default-granularities] → /docs/data-modeling/dimensions#time-dimensions (def at line 521). That heading (docs/data-modeling/dimensions.mdx:82) opens with "grouping by time granularity (year, quarter, month, week, day, hour, minute, second)" — exactly the eight units the warning below the table enumerates, so label and destination now agree.

And your call on line 376 is correct: [Custom granularities][ref-granularities] → #granularities is the custom-granularity parameter reference, which is what that sentence is about. Leaving it alone was right; the two defs now differ deliberately rather than by accident.

Def	Target	Used at	✅
ref-default-granularities	/docs/data-modeling/dimensions#time-dimensions	366	✅
ref-granularities	/reference/data-modeling/dimensions#granularities	376	✅
ref-meta-api	…/rest-api/reference#metadata-api	377	✅
ref-rest-api	/reference/core-data-apis/rest-api	378	✅
ref-graphql-api	/reference/core-data-apis/graphql-api	378	✅
ref-proxy-granularity	…#time-dimension-granularity-references	387	✅

No duplicates, no orphans among the six new defs in this file. #time-dimensions (line 82) and #time-dimension-granularity-references (line 248) both resolve in docs/data-modeling/dimensions.mdx.

Substantive claims re-verified against this checkout

• SQL API. granularity_str_to_int_order (rust/cubesql/cubesql/src/compile/rewrite/rules/utils.rs:376-394) matches exactly second, minute, hour, day, week, month, quarter, year → _ => None. Arm-for-arm match with the eight units in the warning at sql-api/reference.mdx:374-375.
• GraphQL API. Static TimeDimension type, never extended per-cube; nothing reads the meta's granularities array. "Can't address them by name either" holds.
• REST API. Free-form granularity string (query.js:174) plus name resolution against granularities (prepare-annotation.ts:125). "REST yes, SQL/GraphQL no" is accurate.

The other two files are untouched by this commit and remain in their approved state — Playground fix intact, [ref-playground] gone with zero remaining usages, trailing newline present.

Pre-existing, not introduced here

• [ref-custom-granularities] (recipes/data-modeling/custom-granularity.mdx:167) is still an unused link def, predating this PR. Harmless in Mintlify.
• Low — error string coupling. Execution error: Unsupported date_trunc granularity: fiscal_quarter (sql-api/reference.mdx:383) is a vendored-DataFusion string. Agreed with your reasoning: it's what the user pastes into search, and attributing it to DataFusion would be reader noise. On record only in case an upstream bump changes it.

Docs-only — nothing security-, performance-, or test-related applies.

· branch [`igor/core-719-docs-sql-api-custom-granularities`](https://github.com/cube-js/cube/tree/igor/core-719-docs-sql-api-custom-granularities)