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`