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

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] 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 those APIs or from a BI tool. Proxy dimensions can also be used
+in further calculations, like rendering `fiscal_quarter_label` below.
 
 <CodeGroup>
 
@@ -164,6 +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-proxy-granularity]: /docs/data-modeling/dimensions#time-dimension-granularity-references
+[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

docs-mintlify/reference/core-data-apis/sql-api/reference.mdx

@@ -363,12 +363,32 @@ of the PostgreSQL documentation.
 | Function | Description | [Pushdown][ref-qpd] | <nobr>[Post-processing][ref-qpp]</nobr> |
 | --- | --- | --- | --- |
 | `DATE_ADD` | Add an interval to a timestamp with time zone | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
-| `DATE_TRUNC` | Truncate a timestamp to specified precision | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>✅ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
+| `DATE_TRUNC` | Truncate a timestamp to specified precision. Only [default granularities][ref-default-granularities] are supported, see below | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>✅ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
 | `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 | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
 | `EXTRACT` | Retrieves subfields such as year or hour from date/time values | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
 | `LOCALTIMESTAMP` | Returns the current date and time **without** time zone | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
 | `NOW` | Returns the current date and time **with** time zone | ✅ Yes | <nobr>✅ Outer</nobr><br/><nobr>❌ Inner (selections)</nobr><br/><nobr>✅ Inner (projections)</nobr> |
 
+<Warning>
+
+`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]. (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
+```
+
+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.
+
+</Warning>
+
 ### Conditional expressions
 
 <Info>
@@ -497,6 +517,12 @@ 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-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
+[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=

docs-mintlify/reference/data-modeling/dimensions.mdx

@@ -1066,6 +1066,18 @@ Please [file an issue](https://github.com/cube-js/cube/issues) if you need suppo
 
 </Warning>
 
+<Warning>
+
+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.
+
+</Warning>
+
 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 +1359,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