From be6643ac5c2d788ef2377b18a42c6e566b03137e Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Sat, 1 Aug 2026 02:14:27 +0200 Subject: [PATCH 1/4] docs: note that the SQL API can't address custom granularities by name --- .../data-modeling/custom-granularity.mdx | 13 +++++++--- .../core-data-apis/sql-api/reference.mdx | 26 ++++++++++++++++++- .../reference/data-modeling/dimensions.mdx | 15 +++++++++++ 3 files changed, 49 insertions(+), 5 deletions(-) diff --git a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx index 97d228db1bb9a..5701f17cb332e 100644 --- a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx +++ b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx @@ -19,10 +19,13 @@ accounting and financial reporting. Consider the following data model. `interval` and `offset` parameters are used to configure each custom granularity in `granularities`. -Note that custom granularities are also exposed via [proxy -dimensions][ref-proxy-granularity] so that we can conveniently query them via -[Playground][ref-playground] or BI tools connected via the [SQL API][ref-sql-api]. -We can also use them in further calculations like rendering `fiscal_quarter_label`. +Note that each custom granularity is also exposed via a [proxy +dimension][ref-proxy-granularity]. This is not just a convenience: while the +[REST API][ref-rest-api] and the [GraphQL API][ref-graphql-api] can query custom +granularities by name, the [SQL API][ref-sql-api] can only address the default +granularities, so a proxy dimension is the way to query a custom granularity +from [Playground][ref-playground] or a BI tool. Proxy dimensions can also be +used in further calculations, like rendering `fiscal_quarter_label` below. @@ -166,4 +169,6 @@ Querying this data modal would yield the following result: [wiki-fiscal-year]: https://en.wikipedia.org/wiki/Fiscal_year [ref-playground]: /docs/explore-analyze/playground [ref-sql-api]: /reference/core-data-apis/sql-api +[ref-rest-api]: /reference/core-data-apis/rest-api +[ref-graphql-api]: /reference/core-data-apis/graphql-api [ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references \ No newline at end of file diff --git a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx index 7127c46196b87..abee5a6fd1506 100644 --- a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx +++ b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx @@ -363,12 +363,31 @@ of the PostgreSQL documentation. | Function | Description | [Pushdown][ref-qpd] | [Post-processing][ref-qpp] | | --- | --- | --- | --- | | `DATE_ADD` | Add an interval to a timestamp with time zone | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | -| `DATE_TRUNC` | Truncate a timestamp to specified precision | ✅ Yes | ✅ Outer
✅ Inner (selections)
✅ Inner (projections) | +| `DATE_TRUNC` | Truncate a timestamp to specified precision. Only [default granularities][ref-granularities] are supported, see below | ✅ Yes | ✅ Outer
✅ Inner (selections)
✅ Inner (projections) | | `DATEDIFF` | From [Redshift](https://docs.aws.amazon.com/redshift/latest/dg/r_DATEDIFF_function.html). Returns the difference between the date parts of two date or time expressions | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | | `EXTRACT` | Retrieves subfields such as year or hour from date/time values | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | | `LOCALTIMESTAMP` | Returns the current date and time **without** time zone | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | | `NOW` | Returns the current date and time **with** time zone | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | + + +`DATE_TRUNC` only accepts the default granularities: `year`, `quarter`, `month`, +`week`, `day`, `hour`, `minute`, `second`. [Custom +granularities][ref-granularities] can't be addressed by name via the SQL API, +even though they are exposed in the [metadata][ref-meta-api] and can be queried +via the [REST API][ref-rest-api] and the [GraphQL API][ref-graphql-api]. Using a +custom granularity name results in an error: + +``` +Execution error: Unsupported date_trunc granularity: fiscal_quarter +``` + +To query a custom granularity via the SQL API, define a [proxy +dimension][ref-proxy-granularity] that references it. It is exposed as a regular +time dimension and can be selected directly. + + + ### Conditional expressions @@ -497,6 +516,11 @@ See the [XIRR recipe](/recipes/data-modeling/xirr) for more details. [ref-qpp]: /reference/core-data-apis/sql-api/query-format#query-post-processing [ref-sql-api]: /reference/core-data-apis/sql-api [ref-sql-api-aggregate-functions]: /reference/core-data-apis/sql-api/query-format#aggregate-functions +[ref-granularities]: /reference/data-modeling/dimensions#granularities +[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references +[ref-meta-api]: /reference/core-data-apis/rest-api/reference#metadata-api +[ref-rest-api]: /reference/core-data-apis/rest-api +[ref-graphql-api]: /reference/core-data-apis/graphql-api [link-postgres-funcs]: https://www.postgresql.org/docs/current/functions.html [link-github-sql-api]: https://github.com/cube-js/cube/issues?q=is%3Aopen+is%3Aissue+label%3Aapi%3Asql [link-github-new-sql-api-issue]: https://github.com/cube-js/cube/issues/new?assignees=&labels=&projects=&template=sql_api_query_issue.md&title= diff --git a/docs-mintlify/reference/data-modeling/dimensions.mdx b/docs-mintlify/reference/data-modeling/dimensions.mdx index f2ff01644dd96..c8a6127873229 100644 --- a/docs-mintlify/reference/data-modeling/dimensions.mdx +++ b/docs-mintlify/reference/data-modeling/dimensions.mdx @@ -1066,6 +1066,17 @@ Please [file an issue](https://github.com/cube-js/cube/issues) if you need suppo + + +Custom granularities can be queried by name via the [REST API][ref-rest-api] and +the [GraphQL API][ref-graphql-api]. However, the [SQL API][ref-sql-api] can only +address the default granularities by name; `DATE_TRUNC` with a custom +granularity name results in an error. To query a custom granularity via the SQL +API or a BI tool, use a [proxy dimension][ref-proxy-granularity] that references +it. + + + For each custom granularity, the `interval` parameter is required. It specifies the duration of the time interval and has the following format: `quantity unit [quantity unit...]`, e.g., `5 days` or `1 year 6 months`. @@ -1347,6 +1358,10 @@ cube(`fiscal_calendar`, { [ref-time-dimensions]: #type [link-date-time-string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date#date_time_string_format [ref-custom-granularity-recipe]: /recipes/data-modeling/custom-granularity +[ref-rest-api]: /reference/core-data-apis/rest-api +[ref-graphql-api]: /reference/core-data-apis/graphql-api +[ref-sql-api]: /reference/core-data-apis/sql-api +[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references [ref-ref-hierarchies]: /reference/data-modeling/hierarchies [ref-data-sources]: /admin/connect-to-data/data-sources [ref-calendar-cubes]: /docs/data-modeling/concepts/calendar-cubes From 57a765000d82e134799575c61323c67b7f027fa5 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Tue, 4 Aug 2026 04:09:44 +0200 Subject: [PATCH 2/4] docs: the GraphQL API can't address custom granularities by name either --- .../recipes/data-modeling/custom-granularity.mdx | 11 ++++++----- .../reference/core-data-apis/sql-api/reference.mdx | 5 +++-- .../reference/data-modeling/dimensions.mdx | 13 +++++++------ 3 files changed, 16 insertions(+), 13 deletions(-) diff --git a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx index 5701f17cb332e..454c0a033cf58 100644 --- a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx +++ b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx @@ -21,11 +21,12 @@ configure each custom granularity in `granularities`. Note that each custom granularity is also exposed via a [proxy dimension][ref-proxy-granularity]. This is not just a convenience: while the -[REST API][ref-rest-api] and the [GraphQL API][ref-graphql-api] can query custom -granularities by name, the [SQL API][ref-sql-api] can only address the default -granularities, so a proxy dimension is the way to query a custom granularity -from [Playground][ref-playground] or a BI tool. Proxy dimensions can also be -used in further calculations, like rendering `fiscal_quarter_label` below. +[REST API][ref-rest-api] can query custom granularities by name, the [SQL +API][ref-sql-api] and the [GraphQL API][ref-graphql-api] can only address the +default granularities, so a proxy dimension is the way to query a custom +granularity from [Playground][ref-playground] or a BI tool. Proxy dimensions can +also be used in further calculations, like rendering `fiscal_quarter_label` +below. diff --git a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx index abee5a6fd1506..9af1cb04b5d15 100644 --- a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx +++ b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx @@ -375,8 +375,9 @@ of the PostgreSQL documentation. `week`, `day`, `hour`, `minute`, `second`. [Custom granularities][ref-granularities] can't be addressed by name via the SQL API, even though they are exposed in the [metadata][ref-meta-api] and can be queried -via the [REST API][ref-rest-api] and the [GraphQL API][ref-graphql-api]. Using a -custom granularity name results in an error: +via the [REST API][ref-rest-api]. (The [GraphQL API][ref-graphql-api] can't +address them by name either — its schema only exposes fields for the default +granularities.) Using a custom granularity name results in an error: ``` Execution error: Unsupported date_trunc granularity: fiscal_quarter diff --git a/docs-mintlify/reference/data-modeling/dimensions.mdx b/docs-mintlify/reference/data-modeling/dimensions.mdx index c8a6127873229..ad6de8d5c2794 100644 --- a/docs-mintlify/reference/data-modeling/dimensions.mdx +++ b/docs-mintlify/reference/data-modeling/dimensions.mdx @@ -1068,12 +1068,13 @@ Please [file an issue](https://github.com/cube-js/cube/issues) if you need suppo -Custom granularities can be queried by name via the [REST API][ref-rest-api] and -the [GraphQL API][ref-graphql-api]. However, the [SQL API][ref-sql-api] can only -address the default granularities by name; `DATE_TRUNC` with a custom -granularity name results in an error. To query a custom granularity via the SQL -API or a BI tool, use a [proxy dimension][ref-proxy-granularity] that references -it. +Custom granularities can be queried by name via the [REST API][ref-rest-api]. +However, neither the [SQL API][ref-sql-api] nor the [GraphQL +API][ref-graphql-api] can address them by name: the SQL API only supports the +default granularities in `DATE_TRUNC`, and the GraphQL schema only exposes +fields for the default granularities. To query a custom granularity via the SQL +API, the GraphQL API, or a BI tool, use a [proxy +dimension][ref-proxy-granularity] that references it. From 87083b5310e69c40648df2384f25848605cab8b5 Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Tue, 4 Aug 2026 04:13:36 +0200 Subject: [PATCH 3/4] docs: don't claim a proxy dimension is required for Playground, which queries via REST --- .../recipes/data-modeling/custom-granularity.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx index 454c0a033cf58..fcd9549da77a5 100644 --- a/docs-mintlify/recipes/data-modeling/custom-granularity.mdx +++ b/docs-mintlify/recipes/data-modeling/custom-granularity.mdx @@ -24,9 +24,8 @@ dimension][ref-proxy-granularity]. This is not just a convenience: while the [REST API][ref-rest-api] can query custom granularities by name, the [SQL API][ref-sql-api] and the [GraphQL API][ref-graphql-api] can only address the default granularities, so a proxy dimension is the way to query a custom -granularity from [Playground][ref-playground] or a BI tool. Proxy dimensions can -also be used in further calculations, like rendering `fiscal_quarter_label` -below. +granularity from those APIs or from a BI tool. Proxy dimensions can also be used +in further calculations, like rendering `fiscal_quarter_label` below. @@ -168,8 +167,7 @@ Querying this data modal would yield the following result: [ref-custom-granularities]: /reference/data-modeling/dimensions#granularities [ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions [wiki-fiscal-year]: https://en.wikipedia.org/wiki/Fiscal_year -[ref-playground]: /docs/explore-analyze/playground [ref-sql-api]: /reference/core-data-apis/sql-api [ref-rest-api]: /reference/core-data-apis/rest-api [ref-graphql-api]: /reference/core-data-apis/graphql-api -[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references \ No newline at end of file +[ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references From e98514d6cbb559fe9d0f798f560831946b971bce Mon Sep 17 00:00:00 2001 From: Igor Lukanin Date: Tue, 4 Aug 2026 17:33:51 +0200 Subject: [PATCH 4/4] docs: point the DATE_TRUNC default-granularities link at the built-in granularities --- docs-mintlify/reference/core-data-apis/sql-api/reference.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx index 9af1cb04b5d15..3923924ffcf24 100644 --- a/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx +++ b/docs-mintlify/reference/core-data-apis/sql-api/reference.mdx @@ -363,7 +363,7 @@ of the PostgreSQL documentation. | Function | Description | [Pushdown][ref-qpd] | [Post-processing][ref-qpp] | | --- | --- | --- | --- | | `DATE_ADD` | Add an interval to a timestamp with time zone | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | -| `DATE_TRUNC` | Truncate a timestamp to specified precision. Only [default granularities][ref-granularities] are supported, see below | ✅ Yes | ✅ Outer
✅ Inner (selections)
✅ Inner (projections) | +| `DATE_TRUNC` | Truncate a timestamp to specified precision. Only [default granularities][ref-default-granularities] are supported, see below | ✅ Yes | ✅ Outer
✅ Inner (selections)
✅ Inner (projections) | | `DATEDIFF` | From [Redshift](https://docs.aws.amazon.com/redshift/latest/dg/r_DATEDIFF_function.html). Returns the difference between the date parts of two date or time expressions | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | | `EXTRACT` | Retrieves subfields such as year or hour from date/time values | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | | `LOCALTIMESTAMP` | Returns the current date and time **without** time zone | ✅ Yes | ✅ Outer
❌ Inner (selections)
✅ Inner (projections) | @@ -518,6 +518,7 @@ See the [XIRR recipe](/recipes/data-modeling/xirr) for more details. [ref-sql-api]: /reference/core-data-apis/sql-api [ref-sql-api-aggregate-functions]: /reference/core-data-apis/sql-api/query-format#aggregate-functions [ref-granularities]: /reference/data-modeling/dimensions#granularities +[ref-default-granularities]: /docs/data-modeling/dimensions#time-dimensions [ref-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references [ref-meta-api]: /reference/core-data-apis/rest-api/reference#metadata-api [ref-rest-api]: /reference/core-data-apis/rest-api