Method group_by

lib/sqlalchemy/orm/query.py:2079–2120

Apply one or more GROUP BY criterion to the query and return the newly resulting :class:`_query.Query`. All existing GROUP BY settings can be suppressed by passing ``None`` - this will suppress any GROUP BY configured on mappers as well. .. seealso::

(
        self,
        __first: Union[
            Literal[None, False, _NoArg.NO_ARG],
            _ColumnExpressionOrStrLabelArgument[Any],
        ] = _NoArg.NO_ARG,
        /,
        *clauses: _ColumnExpressionOrStrLabelArgument[Any],
    )

    @_generative
    def group_by(
        self,
        __first: Union[
            Literal[None, False, _NoArg.NO_ARG],
            _ColumnExpressionOrStrLabelArgument[Any],
        ] = _NoArg.NO_ARG,
        /,
        *clauses: _ColumnExpressionOrStrLabelArgument[Any],
    ) -> Self:
        """Apply one or more GROUP BY criterion to the query and return
        the newly resulting :class:`_query.Query`.

        All existing GROUP BY settings can be suppressed by
        passing ``None`` - this will suppress any GROUP BY configured
        on mappers as well.

        .. seealso::

            These sections describe GROUP BY in terms of :term:`2.0 style`
            invocation but apply to :class:`_orm.Query` as well:

            :ref:`tutorial_group_by_w_aggregates` - in the
            :ref:`unified_tutorial`

            :ref:`tutorial_order_by_label` - in the :ref:`unified_tutorial`

            :meth:`_sql.Select.group_by` - v2 equivalent method.

        """

        for assertion in (self._no_statement_condition, self._no_limit_offset):
            assertion("group_by")

        if not clauses and (__first is None or __first is False):
            self._group_by_clauses = ()
        elif __first is not _NoArg.NO_ARG:
            criterion = tuple(
                coercions.expect(roles.GroupByRole, clause)
                for clause in (__first,) + clauses
            )
            self._group_by_clauses += criterion
        return self

    @_generative
    @_assertions(_no_statement_condition, _no_limit_offset)