Function within_group

lib/sqlalchemy/sql/_elements_constructors.py:2069–2114

r"""Produce a :class:`.WithinGroup` object against a function. Used against so-called "ordered set aggregate" and "hypothetical set aggregate" functions, including :class:`.percentile_cont`, :class:`.rank`, :class:`.dense_rank`, etc. This feature is typically used by Oracle Databas

(
    element: FunctionElement[_T], *order_by: _ColumnExpressionArgument[Any]
)

def within_group(
    element: FunctionElement[_T], *order_by: _ColumnExpressionArgument[Any]
) -> WithinGroup[_T]:
    r"""Produce a :class:`.WithinGroup` object against a function.

    Used against so-called "ordered set aggregate" and "hypothetical
    set aggregate" functions, including :class:`.percentile_cont`,
    :class:`.rank`, :class:`.dense_rank`, etc.  This feature is typically
    used by Oracle Database, Microsoft SQL Server.

    For generalized ORDER BY of aggregate functions on all included
    backends, including PostgreSQL, MySQL/MariaDB, SQLite as well as Oracle
    and SQL Server, the :func:`_sql.aggregate_order_by` provides a more
    general approach that compiles to "WITHIN GROUP" only on those backends
    which require it.

    :func:`_expression.within_group` is usually called using
    the :meth:`.FunctionElement.within_group` method, e.g.::

        stmt = select(
            func.percentile_cont(0.5).within_group(department.c.salary.desc()),
        )

    The above statement would produce SQL similar to
    ``SELECT percentile_cont(0.5)
    WITHIN GROUP (ORDER BY department.salary DESC)``.

    :param element: a :class:`.FunctionElement` construct, typically
     generated by :data:`~.expression.func`.
    :param \*order_by: one or more column elements that will be used
     as the ORDER BY clause of the WITHIN GROUP construct.

    .. seealso::

        :ref:`tutorial_functions_within_group` - in the
        :ref:`unified_tutorial`

        :func:`_sql.aggregate_order_by` - helper for PostgreSQL, MySQL,
         SQLite aggregate functions

        :data:`.expression.func`

        :func:`_expression.over`

    """
    return WithinGroup(element, *order_by)


def aggregate_order_by(