docs: Calendar cubes

docs/pages/product/caching/recipes/non-additivity.mdx

@@ -165,8 +165,7 @@ cube(`users`, {
 
 ### Decomposing into a formula with additive measures
 
-Non-additive `avg` measures can be rewritten as
-[calculated measures](/product/data-modeling/reference/measures#calculated-measures)
+Non-additive `avg` measures can be rewritten as [calculated measures][ref-calculated-measures]
 that reference additive measures only. Then, this additive measures can be used
 in pre-aggregations. Please note, however, that you shouldn't include `avg_age`
 measure in your pre-aggregation as it renders it non-additive.
@@ -245,4 +244,5 @@ or run it with the `docker-compose up` command. You'll see the result, including
 queried data, in the console.
 
 
-[ref-percentile-recipe]: /product/data-modeling/recipes/percentiles
+[ref-percentile-recipe]: /product/data-modeling/recipes/percentiles
+[ref-calculated-measures]: /product/data-modeling/concepts/calculated-members#calculated-measures

docs/pages/product/data-modeling/concepts.mdx

@@ -42,7 +42,7 @@ metrics-first approaches.
 _Cubes_ represent datasets in Cube and are conceptually similar to [views in
 SQL][wiki-view-sql]. Cubes are usually declared in separate files with one
 cube per file. Typically, a cube points to a single table in
-your database using the [`sql_table` property][ref-schema-ref-sql-table]:
+your [data source][ref-data-sources] using the [`sql_table` property][ref-schema-ref-sql-table]:
 
 <CodeTabs>
 
@@ -104,6 +104,9 @@ Cubes and their members can be further referenced by [views](#views).
 
 Note that cubes support [extension][ref-extending-cubes],
 [polymorphism][ref-polymorphic-cubes], and [data blending][ref-data-blending].
+Custom calendars, such as retail calendars, can be implemented using [calendar
+cubes][ref-calendar-cubes].
+
 Cubes can be defined statically and you can also build [dynamic data
 models][ref-dynamic-data-models].
 
@@ -850,4 +853,6 @@ See the reference documentaton for the full list of pre-aggregation
 [ref-custom-calendar-recipe]: /product/data-modeling/recipes/custom-calendar
 [ref-cube-with-dbt]: /product/data-modeling/recipes/dbt
 [ref-apis-support]: /product/apis-integrations#data-modeling
-[ref-viz-tools]: /product/configuration/visualization-tools
+[ref-viz-tools]: /product/configuration/visualization-tools
+[ref-data-sources]: /product/configuration/data-sources
+[ref-calendar-cubes]: /product/data-modeling/concepts/calendar-cubes

docs/pages/product/data-modeling/concepts/_meta.js

@@ -2,7 +2,8 @@ module.exports = {
   "calculated-members": "Calculated members",
   "multi-stage-calculations": "Multi-stage calculations",
   "working-with-joins": "Joins between cubes",
+  "calendar-cubes": "Calendar cubes",
   "code-reusability-extending-cubes": "Extension",
   "polymorphic-cubes": "Polymorphic cubes",
   "data-blending": "Data blending"
-}
+}

docs/pages/product/data-modeling/concepts/calculated-members.mdx

@@ -17,6 +17,8 @@ into formulas that involve simpler measures. Also, calculated measures [can
 help][ref-decomposition-recipe] to use [non-additive][ref-non-additive] measures with
 pre-aggregations.
 
+### Members of the same cube
+
 In the following example, the `completed_ratio` measure is calculated as a division of
 `completed_count` by total `count`. Note that the result is also multiplied by `1.0`
 since [integer division in SQL][link-postgres-division] would otherwise produce an
@@ -90,6 +92,149 @@ FROM (
 ) AS "orders"
 ```
 
+### Members of other cubes
+
+If you have `first_cube` that is [joined][ref-joins] to `second_cube`, you can define a
+calculated measure that references measures from both `first_cube` and `second_cube`.
+When you query for this calculated measure, Cube will transparently generate SQL with
+necessary joins.
+
+In the following example, the `orders.purchases_to_users_ratio` measure references the
+`purchases` measure from the `orders` cube and the `count` measure from the `users` cube:
+
+<CodeTabs>
+
+```javascript
+cube(`orders`, {
+  sql: `
+    SELECT 1 AS id, 11 AS user_id, 'processing' AS status UNION ALL
+    SELECT 2 AS id, 11 AS user_id, 'completed'  AS status UNION ALL
+    SELECT 3 AS id, 11 AS user_id, 'completed'  AS status
+  `,
+
+  dimensions: {
+    id: {
+      sql: `id`,
+      type: `number`,
+      primary_key: true
+    }
+  },
+
+  measures: {
+    purchases: {
+      type: `count`,
+      filters: [{
+        sql: `${CUBE}.status = 'completed'`
+      }]
+    }
+  }
+})
+
+cube(`users`, {
+  sql: `
+    SELECT 11 AS id, 'Alice' AS name UNION ALL
+    SELECT 12 AS id, 'Bob'   AS name UNION ALL
+    SELECT 13 AS id, 'Eve'   AS name
+  `,
+
+  joins: {
+    orders: {
+      sql: `${CUBE}.id = ${orders}.user_id`,
+      relationship: `one_to_many`
+    }
+  },
+
+  dimensions: {
+    id: {
+      sql: `id`,
+      type: `number`,
+      primary_key: true
+    }
+  },
+
+  measures: {
+    count: {
+      type: `count`
+    },
+
+    purchases_to_users_ratio: {
+      sql: `100.0 * ${orders.purchases} / ${CUBE.count}`,
+      type: `number`,
+      format: `percent`
+    }
+  }
+})
+```
+
+```yaml
+cubes:
+  - name: orders
+    sql: >
+      SELECT 1 AS id, 11 AS user_id, 'processing' AS status UNION ALL
+      SELECT 2 AS id, 11 AS user_id, 'completed'  AS status UNION ALL
+      SELECT 3 AS id, 11 AS user_id, 'completed'  AS status
+
+    dimensions:
+      - name: id
+        sql: id
+        type: number
+        primary_key: true
+
+    measures:
+      - name: purchases
+        type: count
+        filters:
+          - sql: "{CUBE}.status = 'completed'"
+
+  - name: users
+    sql: >
+      SELECT 11 AS id, 'Alice' AS name UNION ALL
+      SELECT 12 AS id, 'Bob'   AS name UNION ALL
+      SELECT 13 AS id, 'Eve'   AS name
+
+    joins:
+      - name: orders
+        sql: "{CUBE}.id = {orders}.user_id"
+        relationship: one_to_many
+
+    dimensions:
+      - name: id
+        sql: id
+        type: number
+        primary_key: true
+
+    measures:
+      - name: count
+        type: count
+
+      - name: purchases_to_users_ratio
+        sql: "1.0 * {orders.purchases} / {CUBE.count}"
+        type: number
+```
+
+</CodeTabs>
+
+If you query for `users.purchases_to_users_ratio`, Cube will generate the following SQL:
+
+```sql
+SELECT
+  1.0 * COUNT(
+    CASE
+      WHEN ("orders".status = 'completed') THEN "orders".id
+    END
+  ) / COUNT(DISTINCT "users".id) "users__purchases_to_users_ratio"
+FROM (
+  SELECT 11 AS id, 'Alice' AS name UNION ALL
+  SELECT 12 AS id, 'Bob'   AS name UNION ALL
+  SELECT 13 AS id, 'Eve'   AS name
+) AS "users"
+LEFT JOIN (
+  SELECT 1 AS id, 11 AS user_id, 'processing' AS status UNION ALL
+  SELECT 2 AS id, 11 AS user_id, 'completed'  AS status UNION ALL
+  SELECT 3 AS id, 11 AS user_id, 'completed'  AS status
+) AS "orders" ON "users".id = "orders".user_id
+```
+
 ## Proxy dimensions
 
 **Proxy dimensions reference dimensions from the same cube or other cubes.**