Method distinct

lib/sqlalchemy/orm/query.py:2677–2724

r"""Apply a ``DISTINCT`` to the query and return the newly resulting ``Query``. .. note:: The ORM-level :meth:`.distinct` call includes logic that will automatically add columns from the ORDER BY of the query to the columns clause of the SELECT

(self, *expr: _ColumnExpressionArgument[Any])

    @_generative
    @_assertions(_no_statement_condition)
    def distinct(self, *expr: _ColumnExpressionArgument[Any]) -> Self:
        r"""Apply a ``DISTINCT`` to the query and return the newly resulting
        ``Query``.


        .. note::

            The ORM-level :meth:`.distinct` call includes logic that will
            automatically add columns from the ORDER BY of the query to the
            columns clause of the SELECT statement, to satisfy the common need
            of the database backend that ORDER BY columns be part of the SELECT
            list when DISTINCT is used.   These columns *are not* added to the
            list of columns actually fetched by the :class:`_query.Query`,
            however,
            so would not affect results. The columns are passed through when
            using the :attr:`_query.Query.statement` accessor, however.

            .. deprecated:: 2.0  This logic is deprecated and will be removed
               in SQLAlchemy 2.0.     See :ref:`migration_20_query_distinct`
               for a description of this use case in 2.0.

        .. seealso::

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

        :param \*expr: optional column expressions.  When present,
         the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>)``
         construct.

         .. deprecated:: 2.1 Passing expressions to
           :meth:`_orm.Query.distinct` is deprecated, use
           :func:`_postgresql.distinct_on` instead.

        """
        if expr:
            warn_deprecated(
                "Passing expression to ``distinct`` to generate a DISTINCT "
                "ON clause is deprecated. Use instead the "
                "``postgresql.distinct_on`` function as an extension.",
                "2.1",
            )
            self._distinct = True
            self._distinct_on = self._distinct_on + tuple(
                coercions.expect(roles.ByOfRole, e) for e in expr
            )
        else:
            self._distinct = True
        return self

    @_generative
    def ext(self, extension: SyntaxExtension) -> Self: