docs: multi-stage grain directive for measures (follow-up to #10957)

Author: igorlukanin

docs-mintlify/docs/data-modeling/measures.mdx

@@ -307,8 +307,8 @@ periods.
 
 ### Percent of total (fixed dimension)
 
-Use the [`group_by`][ref-group-by] parameter to fix the inner aggregation to
-specific dimensions, enabling percent-of-total calculations:
+Use the [`grain`][ref-grain] parameter with `keep_only` to fix the inner
+aggregation to specific dimensions, enabling percent-of-total calculations:
 
 ```yaml
 measures:
@@ -320,8 +320,9 @@ measures:
     multi_stage: true
     sql: "{revenue}"
     type: sum
-    group_by:
-      - country
+    grain:
+      keep_only:
+        - country
 
   - name: country_revenue_percentage
     multi_stage: true
@@ -371,7 +372,7 @@ The `filter` parameter requires the [Tesseract SQL planner][ref-tesseract-env]
 
 ### Nested aggregates
 
-Use the [`add_group_by`][ref-add-group-by] parameter to compute an aggregate
+Use the [`grain`][ref-grain] parameter with `include` to compute an aggregate
 of an aggregate, e.g., the average of per-customer averages:
 
 ```yaml
@@ -384,13 +385,15 @@ measures:
     multi_stage: true
     sql: "{avg_order_value}"
     type: avg
-    add_group_by:
-      - customer_id
+    grain:
+      include:
+        - customer_id
 ```
 
 ### Ranking
 
-Use the [`reduce_by`][ref-reduce-by] parameter to rank items within groups:
+Use the [`grain`][ref-grain] parameter with `exclude` to rank items within
+groups:
 
 ```yaml
 measures:
@@ -403,11 +406,20 @@ measures:
     order_by:
       - sql: "{revenue}"
         dir: asc
-    reduce_by:
-      - product
+    grain:
+      exclude:
+        - product
     type: rank
 ```
 
+<Note>
+
+`grain` replaces the standalone `group_by`, `reduce_by`, and `add_group_by`
+parameters, which remain supported. See the [`grain`][ref-grain] reference for
+the migration mapping.
+
+</Note>
+
 ### Conditional measures
 
 Conditional measures depend on the value of a dimension, using the
@@ -463,9 +475,7 @@ measures:
 [ref-format]: /reference/data-modeling/measures#format
 [ref-rolling-window]: /reference/data-modeling/measures#rolling_window
 [ref-time-shift]: /reference/data-modeling/measures#time_shift
-[ref-group-by]: /reference/data-modeling/measures#group_by
-[ref-reduce-by]: /reference/data-modeling/measures#reduce_by
-[ref-add-group-by]: /reference/data-modeling/measures#add_group_by
+[ref-grain]: /reference/data-modeling/measures#grain
 [ref-filter]: /reference/data-modeling/measures#filter
 [ref-case]: /reference/data-modeling/measures#case
 [ref-switch-dim]: /reference/data-modeling/dimensions#type

docs-mintlify/recipes/data-modeling/share-of-total.mdx

@@ -58,10 +58,10 @@ When the share measure needs to be part of the semantic model — so it is
 returned by the API, visible in Explore, or accessible to AI agents — define
 it using multi-stage measures powered by [Tesseract][link-tesseract].
 
-The key building block is the [`group_by`][ref-group-by] parameter: when set
-to an empty list, the inner aggregation stage groups by _nothing_, computing
-the grand total across all rows. The outer stage then joins that total back and
-groups by the query's dimensions as usual.
+The key building block is the [`grain`][ref-grain] parameter with `keep_only`:
+when set to an empty list, the inner aggregation stage groups by _nothing_,
+computing the grand total across all rows. The outer stage then joins that total
+back and groups by the query's dimensions as usual.
 
 <Warning>
 
@@ -76,15 +76,16 @@ Calculating share of total requires three measures:
 
 1. A **base measure** — the regular aggregate, e.g., `total_sale_price`.
 2. A **helper measure** — a multi-stage measure that re-aggregates the base
-   measure with `group_by: []`, fixing the inner `GROUP BY` to nothing (the
-   grand total). This measure is internal and should be hidden from views.
+   measure with `grain` set to `keep_only: []`, fixing the inner `GROUP BY` to
+   nothing (the grand total). This measure is internal and should be hidden from
+   views.
 3. A **ratio measure** — a multi-stage measure that divides the base by the
    helper total.
 
 The examples below extend the `order_items` cube from the
 [ecommerce demo model][link-ecommerce-demo]. The `brand` and `category`
 dimensions are proxied from the joined `products` cube so they can be
-referenced by `group_by`.
+referenced by `grain`.
 
 ### Share of grand total
 
@@ -122,7 +123,8 @@ cubes:
         multi_stage: true
         sql: "{total_sale_price}"
         type: sum
-        group_by: []
+        grain:
+          keep_only: []
 
       - name: revenue_share
         multi_stage: true
@@ -165,7 +167,9 @@ cube(`order_items`, {
       multi_stage: true,
       sql: `${total_sale_price}`,
       type: `sum`,
-      group_by: []
+      grain: {
+        keep_only: []
+      }
     },
 
     revenue_share: {
@@ -180,7 +184,7 @@ cube(`order_items`, {
 
 </CodeGroup>
 
-`group_by: []` tells Tesseract that the inner stage for `total_revenue_grand_total`
+`keep_only: []` tells Tesseract that the inner stage for `total_revenue_grand_total`
 should group by no dimensions, producing a single grand-total row. The outer stage
 joins it back and groups by whatever dimensions are in the query (e.g., `brand`),
 so every row receives the same total denominator.
@@ -216,9 +220,9 @@ Sometimes you want each row's share _within a category_ rather than the
 overall total — for example, each brand's share of its product category's
 revenue.
 
-Use `group_by` with the dimension you want to _fix_ as the subtotal boundary.
-The inner stage will group only by that dimension, and the outer stage will
-group by the full set of query dimensions:
+Use `grain` with `keep_only` set to the dimension you want to _fix_ as the
+subtotal boundary. The inner stage will group only by that dimension, and the
+outer stage will group by the full set of query dimensions:
 
 <CodeGroup>
 
@@ -256,8 +260,9 @@ cubes:
         multi_stage: true
         sql: "{total_sale_price}"
         type: sum
-        group_by:
-          - category
+        grain:
+          keep_only:
+            - category
 
       - name: revenue_share_of_category
         multi_stage: true
@@ -304,7 +309,9 @@ cube(`order_items`, {
       multi_stage: true,
       sql: `${total_sale_price}`,
       type: `sum`,
-      group_by: [`category`]
+      grain: {
+        keep_only: [`category`]
+      }
     },
 
     revenue_share_of_category: {
@@ -319,7 +326,7 @@ cube(`order_items`, {
 
 </CodeGroup>
 
-With `group_by: [category]`, the inner stage computes revenue per category.
+With `keep_only: [category]`, the inner stage computes revenue per category.
 The outer stage groups by both `category` and `brand`, so each brand row
 divides its revenue by the right category total. Exclude
 `category_revenue_grand_total` from the view the same way as shown above.
@@ -348,7 +355,7 @@ override)][ref-share-filter].
 
 [link-tesseract]: https://cube.dev/blog/introducing-next-generation-data-modeling-engine
 [link-ecommerce-demo]: https://github.com/cubedevinc/ecommerce_demo
-[ref-group-by]: /reference/data-modeling/measures#group_by
+[ref-grain]: /reference/data-modeling/measures#grain
 [ref-filter]: /reference/data-modeling/measures#filter
 [ref-share-filter]: /docs/data-modeling/measures#share-of-total-filter-override
 [ref-dynamic-params]: /recipes/data-modeling/passing-dynamic-parameters-in-a-query

docs-mintlify/recipes/data-modeling/xirr.mdx

@@ -72,8 +72,9 @@ cubes:
         multi_stage: true
         sql: "XIRR({total_payments}, {date__day})"
         type: number_agg
-        add_group_by:
-          - date__day
+        grain:
+          include:
+            - date__day
 
     pre_aggregations:
       - name: main_xirr
@@ -122,9 +123,9 @@ cube(`payments`, {
       multi_stage: true,
       sql: `XIRR(${CUBE.total_payments}, ${CUBE.date__day})`,
       type: `number_agg`,
-      add_group_by: [
-        date__day
-      ]
+      grain: {
+        include: [date__day]
+      }
     }
   },
 

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

@@ -639,15 +639,21 @@ cube(`time_shift`, {
 
 </CodeGroup>
 
-### `group_by`
+### `grain`
 
-The `group_by` parameter is used with [multi-stage measures][ref-multi-stage] to specify
-dimensions that should be used for the `GROUP BY` of the inner aggregation stage,
-*ignoring* any dimensions present in the query.
+The `grain` parameter is used with [multi-stage measures][ref-multi-stage] to control the
+dimensions of the inner aggregation stage's `GROUP BY` — the *grain* at which the base
+measure is computed before the outer aggregation is applied. It accepts an object with
+three keys, each taking a list of dimension names from the same cube:
 
-This is commonly used for fixed dimension calculations — computing a measure at a fixed
-granularity regardless of the query's dimensions. For example, calculating percent of
-total or comparing individual items to a broader dataset.
+- `keep_only` — group the inner stage by *only* the listed dimensions, ignoring the
+  query's dimensions. Use it for fixed-grain calculations such as percent of total.
+- `exclude` — group the inner stage by the query's dimensions *minus* the listed
+  dimensions. Use it for ranking within groups.
+- `include` — group the inner stage by the query's dimensions *plus* the listed
+  dimensions. Use it for nested aggregates (an aggregate of an aggregate).
+
+`keep_only` and `exclude` are mutually exclusive.
 
 <CodeGroup>
 
@@ -657,8 +663,9 @@ measures:
     multi_stage: true
     sql: "{revenue}"
     type: sum
-    group_by:
-      - country
+    grain:
+      keep_only:
+        - country
 ```
 
 ```javascript title="JavaScript"
@@ -667,104 +674,44 @@ measures: {
     multi_stage: true,
     sql: `${revenue}`,
     type: `sum`,
-    group_by: [country]
+    grain: {
+      keep_only: [country]
+    }
   }
 }
 ```
 
 </CodeGroup>
 
-`group_by` accepts a list of dimension names from the same cube. The inner stage will
-group by *only* these dimensions, while the outer aggregation will group by the query's
-dimensions.
-
-| Parameter | Inner `GROUP BY` | Outer `GROUP BY` |
+| `grain` key | Inner `GROUP BY` | Outer `GROUP BY` |
 |---|---|---|
-| `group_by` | Only the listed dimensions | Query dimensions |
-| `reduce_by` | Query dimensions minus listed | Query dimensions |
-| `add_group_by` | Query dimensions plus listed | Query dimensions |
-
-### `reduce_by`
-
-The `reduce_by` parameter is used with [multi-stage measures][ref-multi-stage] to specify
-dimensions that should be *removed* from the `GROUP BY` of the inner aggregation stage.
-
-This is commonly used for ranking calculations — computing a rank across a dimension
-while still allowing grouping by other dimensions in the query.
-
-<CodeGroup>
-
-```yaml title="YAML"
-measures:
-  - name: product_rank
-    multi_stage: true
-    order_by:
-      - sql: "{revenue}"
-        dir: asc
-    reduce_by:
-      - product
-    type: rank
-```
-
-```javascript title="JavaScript"
-measures: {
-  product_rank: {
-    multi_stage: true,
-    order_by: [{
-      sql: `${revenue}`,
-      dir: `asc`
-    }],
-    reduce_by: [product],
-    type: `rank`
-  }
-}
-```
-
-</CodeGroup>
-
-`reduce_by` accepts a list of dimension names. The inner stage will group by the query's
-dimensions *minus* the listed dimensions, while the outer aggregation will group by the
-query's dimensions.
-
-### `add_group_by`
+| `keep_only` | Only the listed dimensions | Query dimensions |
+| `exclude` | Query dimensions minus listed | Query dimensions |
+| `include` | Query dimensions plus listed | Query dimensions |
 
-The `add_group_by` parameter is used with [multi-stage measures][ref-multi-stage] to
-specify dimensions that should be *added* to the `GROUP BY` of the inner aggregation
-stage, in addition to any dimensions present in the query.
+<Note>
 
-This is commonly used for [nested aggregate][ref-nested-aggregate] patterns — computing
-an aggregate of an aggregate. For example, averaging per-user metrics or counting how
-many groups exceed a threshold.
+`grain` replaces the standalone `group_by`, `reduce_by`, and `add_group_by` parameters,
+which remain supported. To migrate, use `grain.keep_only` instead of `group_by`,
+`grain.exclude` instead of `reduce_by`, and `grain.include` instead of `add_group_by`.
 
-<CodeGroup>
+</Note>
 
-```yaml title="YAML"
-measures:
-  - name: avg_user_score
-    multi_stage: true
-    sql: "{avg_score}"
-    type: avg
-    add_group_by:
-      - user_id
-```
+### `group_by`, `reduce_by`, and `add_group_by` (legacy)
 
-```javascript title="JavaScript"
-measures: {
-  avg_user_score: {
-    multi_stage: true,
-    sql: `${avg_score}`,
-    type: `avg`,
-    add_group_by: [user_id]
-  }
-}
-```
+These three parameters were the original way to control the inner aggregation stage's
+`GROUP BY` for [multi-stage measures][ref-multi-stage]. They are still supported, but
+[`grain`](#grain) now covers all three and is the recommended way to express the grain of
+a multi-stage measure.
 
-</CodeGroup>
+| Legacy parameter | `grain` equivalent | Effect on the inner stage's `GROUP BY` |
+|---|---|---|
+| `group_by` | [`grain.keep_only`](#grain) | Only the listed dimensions, ignoring query dimensions |
+| `reduce_by` | [`grain.exclude`](#grain) | Query dimensions minus the listed dimensions |
+| `add_group_by` | [`grain.include`](#grain) | Query dimensions plus the listed dimensions |
 
-`add_group_by` accepts a list of dimension names from the same cube. The listed
-dimensions will be included in the inner stage's `GROUP BY` but will *not* appear
-in the outer aggregation — they are used only to define the granularity at which
-the base measure is computed before the outer aggregation is applied.
+Each accepts a list of dimension names from the same cube. For new data models, use
+[`grain`](#grain) instead.
 
 ### `filter`