docs: Custom time dimension granularities (#8679)

Author: igorlukanin

docs/pages/guides/_meta.js

@@ -1,7 +1,7 @@
 module.exports = {
+  "recipes": "Recipes",
   "dbt": "Using Cube with dbt",
   "designing-metrics": "Designing Metrics",
-  "recipes": "Recipes",
   "style-guide": "Style guide",
   "data-store-cost-saving-guide": "Cost saving guide"
 }

docs/pages/guides/recipes.mdx

@@ -32,7 +32,7 @@ These recipes will show you the best practices of using Cube.
 - [Calculating average and percentiles](/guides/recipes/data-modeling/percentiles)
 - [Calculating nested aggregates](/guides/recipes/data-modeling/nested-aggregates)
 - [Calculating period-over-period changes](/guides/recipes/data-modeling/period-over-period)
-- [Implementing fiscal year or fiscal quarter dimensions](/guides/recipes/data-modeling/fiscal-year-quarter-dimensions)
+- [Implementing custom time dimension granularities](/guides/recipes/data-modeling/custom-granularity)
 - [Implementing Entity-Attribute-Value model](/guides/recipes/data-modeling/entity-attribute-value)
 - [Implementing data snapshots](/guides/recipes/data-modeling/snapshots)
 - [Using different data models for tenants](/guides/recipes/access-control/using-different-schemas-for-tenants)

docs/pages/guides/recipes/data-modeling/_meta.js

@@ -2,9 +2,9 @@ module.exports = {
   "percentiles": "Calculating averages and percentiles",
   "nested-aggregates": "Calculating nested aggregates",
   "period-over-period": "Calculating period-over-period changes",
+  "custom-granularity": "Implementing custom time dimension granularities",
   "snapshots": "Implementing data snapshots",
   "entity-attribute-value": "Implementing Entity-Attribute-Value Model (EAV)",
-  "fiscal-year-quarter-dimensions": "Implementing fiscal year or fiscal quarter dimensions",
   "passing-dynamic-parameters-in-a-query": "Passing dynamic parameters in a query",
   "using-dynamic-measures": "Using dynamic measures",
   "dynamic-union-tables": "Using dynamic union tables",

docs/pages/guides/recipes/data-modeling/custom-granularity.mdx

@@ -0,0 +1,161 @@
+# Implementing custom time dimension granularities
+
+This recipe show examples of commonly used [custom
+granularities][ref-custom-granularities].
+
+## Use case
+
+Sometimes, you might need to group the result set by units of time that are
+different from [default granularities][ref-default-granularities] such as `week`
+(starting on Monday) or `year` (starting on January 1).
+
+Below, we explore the following examples of custom granularities:
+* *Week starting on Sunday*, commonly used in the US and some other countries.
+* *[Fiscal year][wiki-fiscal-year]* and *fiscal quarter*, commonly used in
+accounting and financial reporting.
+
+## Data modeling
+
+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`.
+
+<CodeTabs>
+
+```yaml
+cubes:
+  - name: custom_granularities
+    sql: >
+      SELECT '2024-01-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-02-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-03-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-04-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-05-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-06-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-07-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-08-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-09-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-10-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-11-15'::TIMESTAMP AS timestamp UNION ALL
+      SELECT '2024-12-15'::TIMESTAMP AS timestamp
+
+    dimensions:
+      - name: timestamp
+        sql: timestamp
+        type: time
+
+        granularities:
+          - name: sunday_week
+            interval: 1 week
+            offset: -1 day
+
+          - name: fiscal_year
+            title: Federal fiscal year in the United States
+            interval: 1 year
+            offset: -3 months
+
+          - name: fiscal_quarter
+            title: Federal fiscal quarter in the United States
+            interval: 1 quarter
+            offset: -3 months
+      
+      - name: sunday_week
+        sql: "{timestamp.sunday_week}"
+        type: time
+      
+      - name: fiscal_year
+        sql: "{timestamp.fiscal_year}"
+        type: time
+      
+      - name: fiscal_quarter
+        sql: "{timestamp.fiscal_quarter}"
+        type: time
+
+      - name: fiscal_quarter_label
+        sql: >
+          'FY' || EXTRACT(YEAR FROM {timestamp.fiscal_year}) ||
+          '-Q' || EXTRACT(QUARTER FROM {timestamp.fiscal_quarter})
+        type: string
+```
+
+```javascript
+cube(`custom_granularities`, {
+  sql: `
+    SELECT '2024-01-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-02-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-03-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-04-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-05-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-06-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-07-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-08-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-09-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-10-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-11-15'::TIMESTAMP AS timestamp UNION ALL
+    SELECT '2024-12-15'::TIMESTAMP AS timestamp
+  `,
+
+  dimensions: {
+    timestamp: {
+      sql: `timestamp`,
+      type: `time`,
+
+      granularities: {
+        sunday_week: {
+          interval: `1 week`,
+          offset: `-1 day`
+        },
+
+        fiscal_year: {
+          title: `Federal fiscal year in the United States`,
+          interval: `1 year`,
+          offset: `-3 months`
+        },
+
+        fiscal_quarter: {
+          title: `Federal fiscal quarter in the United States`,
+          interval: `1 quarter`,
+          offset: `-3 months`
+        }
+      }
+    },
+    
+    sunday_week: {
+      sql: `${timestamp.sunday_week}`,
+      type: `time`
+    },
+
+    fiscal_year: {
+      sql: `${timestamp.fiscal_year}`,
+      type: `time`
+    },
+      
+    fiscal_quarter: {
+      sql: `${timestamp.fiscal_quarter}`,
+      type: `time`
+    },
+
+    fiscal_quarter_label: {
+      sql: `
+        'FY' || EXTRACT(YEAR FROM ${timestamp.fiscal_year}) ||
+        '-Q' || EXTRACT(QUARTER FROM ${timestamp.fiscal_quarter})
+      `,
+      type: `string`
+    }
+  }
+})
+```
+
+</CodeTabs>
+
+
+[ref-custom-granularities]: /reference/data-model/dimensions#granularities
+[ref-default-granularities]: /product/data-modeling/concepts#time-dimensions
+[wiki-fiscal-year]: https://en.wikipedia.org/wiki/Fiscal_year
+[ref-playground]: /product/workspace/playground
+[ref-sql-api]: /product/apis-integrations/sql-api
+[ref-proxy-granularity]: /product/data-modeling/concepts/calculated-members#time-dimension-granularity

docs/pages/guides/recipes/data-modeling/fiscal-year-quarter-dimensions.mdx

@@ -5,19 +5,17 @@ redirect_from:
 
 # Query format in the REST API
 
-Cube Queries are plain JavaScript objects, describing an analytics query. The
-basic elements of a query (query members) are `measures`, `dimensions`, and
-`segments`.
+Queries to the REST API are plain JavaScript objects, describing an analytics
+query. The basic elements of a query (query members) are `measures`, `dimensions`,
+and `segments`.
 
-The query member format name is `CUBE_NAME.MEMBER_NAME`, for example the
-dimension `email` in the Cube `Users` would have the name `Users.email`.
+The query member format name is `cube_name.member_name`, for example the `email`
+dimension in the `users` cube would have the `users.email` name.
 
-In the case of dimension of type `time` granularity could be optionally added to
-the name, in the following format `CUBE_NAME.TIME_DIMENSION_NAME.GRANULARITY`,
-ex: `stories.time.month`.
-
-Supported granularities: `second`, `minute`, `hour`, `day`, `week`, `month`,
-`quarter` and `year`.
+In the case of a dimension of the `time` type, a granularity could be optionally
+added to the name, in the following format: `cube_name.time_dimension_name.granularity_name`,
+e.g., `stories.time.week`. It can be one of the [default granularities][ref-default-granularities]
+(e.g., `year` or `week`) or a [custom granularity][ref-custom-granularities].
 
 The Cube client also accepts an array of queries. By default, it will be treated
 as a Data Blending query type.
@@ -95,8 +93,8 @@ query][ref-ungrouped-query].
 If the `order` property is not specified in the query, Cube sorts results by
 default using the following rules:
 
-- The first time dimension with granularity, ascending. If no time dimension
-  with granularity exists...
+- The first time dimension with a granularity, ascending. If no time dimension
+  with a granularity exists...
 - The first measure, descending. If no measure exists...
 - The first dimension, ascending.
 
@@ -530,9 +528,10 @@ provides a convenient shortcut to pass a dimension and a filter as a
   range][ref-relative-date-range], for example, `last quarter`.
 - `compareDateRange`: An array of date ranges to compare measure values. See
 [compare date range queries][ref-compare-date-range] for details.
-- `granularity`: A granularity for a time dimension. It supports the following
-  values `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
-  If you pass `null` to the granularity, Cube will only perform filtering by a
+- `granularity`: A granularity for a time dimension. It can be one of the [default
+granularities][ref-default-granularities] (e.g., `year` or `week`) or a [custom
+granularity][ref-custom-granularities].
+  If you don't provide a granularity, Cube will only perform filtering by a
   specified time dimension, without grouping.
 
 ```json
@@ -617,4 +616,6 @@ refer to its documentation for more examples.
 [ref-compare-date-range]: /product/apis-integrations/queries#compare-date-range-query
 [ref-total-query]: /product/apis-integrations/queries#total-query
 [ref-ungrouped-query]: /product/apis-integrations/queries#ungrouped-query
-[ref-default-order]: /product/apis-integrations/queries#order
+[ref-default-order]: /product/apis-integrations/queries#order
+[ref-default-granularities]: /product/data-modeling/concepts#time-dimensions
+[ref-custom-granularities]: /reference/data-model/dimensions#granularities