Release: 2.1.0b1 | Release Date: January 21, 2026

# SQLAlchemy 2.1 Documentation

# Source code for examples.syntax_extensions.qualify

    from __future__ import annotations

    from sqlalchemy.ext.compiler import compiles
    from sqlalchemy.sql import ClauseElement
    from sqlalchemy.sql import coercions
    from sqlalchemy.sql import ColumnElement
    from sqlalchemy.sql import ColumnExpressionArgument
    from sqlalchemy.sql import roles
    from sqlalchemy.sql import Select
    from sqlalchemy.sql import SyntaxExtension
    from sqlalchemy.sql import visitors

    def qualify(predicate: ColumnExpressionArgument[bool]) -> Qualify:
        """Return a QUALIFY construct

        E.g.::

            stmt = select(qt_table).ext(
                qualify(func.row_number().over(order_by=qt_table.c.o))
            )

        """
        return Qualify(predicate)

    class Qualify(SyntaxExtension, ClauseElement):
        """Define the QUALIFY class."""

        predicate: ColumnElement[bool]
        """A single column expression that is the predicate within the QUALIFY."""

        _traverse_internals = [
            ("predicate", visitors.InternalTraversal.dp_clauseelement)
        ]
        """This structure defines how SQLAlchemy can do a deep traverse of internal
        contents of this structure.  This is mostly used for cache key generation.
        If the traversal is not written yet, the ``inherit_cache=False`` class
        level attribute may be used to skip caching for the construct.
        """

        def __init__(self, predicate: ColumnExpressionArgument):
            self.predicate = coercions.expect(
                roles.WhereHavingRole, predicate, apply_propagate_attrs=self
            )

        def apply_to_select(self, select_stmt: Select) -> None:
            """Called when the :meth:`.Select.ext` method is called.

            The extension should apply itself to the :class:`.Select`, typically
            using :meth:`.HasStatementExtensions.apply_syntax_extension_point`,
            which receives a callable that receives a list of current elements to
            be concatenated together and then returns a new list of elements to be
            concatenated together in the final structure.  The
            :meth:`.SyntaxExtension.append_replacing_same_type` callable is
            usually used for this.

            """
            select_stmt.apply_syntax_extension_point(
                self.append_replacing_same_type, "post_criteria"
            )

    @compiles(Qualify)
    def _compile_qualify(element, compiler, **kw):
        """a compiles extension that delivers the SQL text for Qualify"""
        return f"QUALIFY {compiler.process(element.predicate, **kw)}"