> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# group_by

> Group data by specified columns and apply aggregation functions to each group. 

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      This example groups the dataset by an exact match on the `category` column and a date component (month level) on the `date` column, and then aggregates the count of `sales` and the sum of `revenue`:

      ```stan theme={null}
      group_by(ds, {
        "by": [
          { "by": "category", "groupingType": "EXACT" },
          { "by": "date", "groupingType": "DATE_COMPONENT", "param": { "component": "MONTH", "timezone": "UTC" } }
        ],
        "aggregations": [
          { "name": "total_sales", "on": "sales", "type": "COUNT" },
          { "name": "total_revenue", "on": "revenue", "type": "SUM" }
        ]
      }) -> (ds_grouped)
      ```
    </Tab>

    <Tab title="Example 2">
      This example uses the simplified `by` parameter to group by an exact match on `category`. The aggregation calculates the average of `revenue` for each group:

      ```stan theme={null}
      group_by(ds, {
        "by": ["category"],
        "aggregations": [
          { "name": "average_revenue", "on": "revenue", "type": "AVG" }
        ]
      }) -> (ds_grouped)
      ```
    </Tab>

    <Tab title="Example 3">
      This example groups by `category` and creates a sorted list of `values` based on the `sortCol` column:

      ```stan theme={null}
      group_by(ds, {
        "by": ["category"],
        "aggregations": [
          { "name": "sorted_values", "on": "values", "type": "LIST", "params": { "value": "sortCol" } }
        ]
      }) -> (ds_grouped)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      group_by(ds_in: dataset, {
          "param": value,
          ...
      }) -> (ds_out: dataset)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="ds_in" type="dataset" required>
    The input dataset containing the columns to group by and apply aggregations on.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="ds_out" type="dataset" required>
    A dataset containing the aggregated results based on the grouping operations.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="by" type="array" required>
    Columns to group by.
    An array specifying the columns used for grouping. The `by` parameter can be either:

    * An array of column names (e.g., `["column1", "column2"]`), which defaults to `EXACT` grouping.
    * An array of objects with `by`, `groupingType`, optional `name` and optional `param` properties.

    <Accordion title="Array items">
      <Tabs>
        <Tab title="Column name">
          <ParamField path="{_}" type="string (ds_in.column)">
            Column name to group by.
          </ParamField>
        </Tab>

        <Tab title="Grouping config">
          <ParamField path="by" type="string (ds_in.column)" required>
            Column to group by.
          </ParamField>

          <ParamField path="name" type="string">
            Name of the output column. It is optional and defaults to the column name (`by` parameter).
          </ParamField>

          <ParamField path="groupingType" type="string" required>
            Type of grouping operation.
            The type of grouping operation. You can group by exact value match, a date component,
            a range of numerical values, or quantiles.

            Values must be one of the following:

            * `EXACT`
            * `DATE_COMPONENT`
            * `RANGE`
            * `QUANTILES`
          </ParamField>

          <ParamField path="param" type="[object, object, object, number, null]">
            Grouping parameters.

            <Accordion title="Options">
              <Tabs>
                <Tab title="Date component">
                  <ParamField path="component" type="string" required>
                    Date component to group by.
                    Date component to group by (only for `DATE_COMPONENT` grouping type).

                    Values must be one of the following:

                    `MILLISECOND` `SECOND` `MINUTE` `HOUR` `YEAR_DAY` `MONTH_DAY` `WEEK_DAY` `WEEK` `WEEK_OF_YEAR` `MONTH` `QUARTER` `YEAR`
                  </ParamField>

                  <ParamField path="timezone" type="string" required>
                    Timezone to use for date grouping.
                    The timezone to apply when grouping by date component.
                  </ParamField>
                </Tab>

                <Tab title="Date interval">
                  <ParamField path="interval" type="string" required>
                    Date interval to use.
                    The interval unit to apply when grouping by range.

                    Values must be one of the following:

                    `MILLISECOND` `SECOND` `MINUTE` `HOUR` `DAY` `WEEK` `MONTH` `QUARTER` `YEAR`
                  </ParamField>

                  <ParamField path="count" type="integer" required>
                    Count of intervals in each range.
                    Number of intervals in each range when `groupingType` is `RANGE`.
                  </ParamField>
                </Tab>

                <Tab title="Range bins">
                  <ParamField path="nBins" type="integer" required>
                    Number of bins.
                    Number of bins to divide the data into.

                    Values must be in the following range:

                    ```javascript theme={null}
                    1 ≤ nBins < inf
                    ```
                  </ParamField>

                  <ParamField path="prettyBins" type="boolean" default="true">
                    Use pretty bins.
                    Whether to adjust bin edges to be more human-readable.
                  </ParamField>
                </Tab>

                <Tab title="Range size">
                  <ParamField path="{_}" type="number">
                    Range size as number for `RANGE` grouping or number of quantiles.
                    Specify a range size directly as a number when `groupingType` is `RANGE`
                    or number of quantiles when `groupingType` is `QUANTILES`.
                  </ParamField>
                </Tab>

                <Tab title="None">
                  <ParamField path="{_}" type="null">
                    Null is accepted when no param is needed for the grouping type.
                  </ParamField>
                </Tab>
              </Tabs>
            </Accordion>
          </ParamField>
        </Tab>
      </Tabs>
    </Accordion>
  </ParamField>

  <ParamField path="aggregations" type="array[object]" required>
    Aggregation functions to apply.
    An array specifying the aggregation functions to apply on each group.
    The array can be empty, in which case no aggregations are performed, but the dataset is still grouped by the specified columns.

    <Accordion title="Array items">
      <ParamField path="name" type="string">
        Name of the output column.
      </ParamField>

      <ParamField path="on" type="[string, null]">
        Column on which the aggregation is applied.
        If null, the aggregation applies to the entire group.
      </ParamField>

      <ParamField path="type" type="string">
        Type of aggregation function.
        The type of aggregation function to perform on the specified column.
        Includes support for standard aggregations (e.g., `SUM`, `COUNT`) as well as element-wise aggregations.
        Notes:

        * `PERCENT_OF_ROWS_WHERE`: Computes the percentage **within each group** where a condition is true.
        * `PERCENT_OF_ROWS`: Computes the percentage **relative to the total number of rows** across all groups.

        Values must be one of the following:

        `COUNT` `MIN` `MAX` `SUM` `AVG` `VARIANCE` `STDEV` `FIRST` `LAST` `P25` `P50` `P75` `COUNT_WHERE` `NUMBER_OF_ROWS` `NUMBER_OF_ROWS_WHERE` `PERCENT_OF_ROWS` `PERCENT_OF_ROWS_WHERE` `METRIC` `MODE` `UNIQUE_VALUES` `LIST_UNIQUE` `LIST` `CONCATENATE` `ELEMENT_COUNT` `ELEMENT_MIN` `ELEMENT_MAX` `ELEMENT_SUM` `ELEMENT_AVG` `ELEMENT_VARIANCE` `ELEMENT_STDEV` `ELEMENT_FIRST` `ELEMENT_LAST`
      </ParamField>

      <ParamField path="params" type="object">
        Additional parameters for specific aggregations.

        <Accordion title="Properties">
          <ParamField path="value" type="[number, string, null]">
            value.
            Additional value used for certain aggregation types (e.g., `COUNT_WHERE`, `METRIC`, or `LIST` for presorting).
          </ParamField>
        </Accordion>
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="query" type="string">
    The *graphext advanced query* used to identify the rows to select previous to the grouping.
  </ParamField>
</Accordion>