Method distinct

lib/sqlalchemy/sql/selectable.py:6525–6584

r"""Return a new :func:`_expression.select` construct which will apply DISTINCT to the SELECT statement overall. E.g.:: from sqlalchemy import select stmt = select(users_table.c.id, users_table.c.name).distinct() The above would produce an statemen

(self, *expr: _ColumnExpressionArgument[Any])

    @_generative
    def distinct(self, *expr: _ColumnExpressionArgument[Any]) -> Self:
        r"""Return a new :func:`_expression.select` construct which
        will apply DISTINCT to the SELECT statement overall.

        E.g.::

            from sqlalchemy import select

            stmt = select(users_table.c.id, users_table.c.name).distinct()

        The above would produce an statement resembling:

        .. sourcecode:: sql

            SELECT DISTINCT user.id, user.name FROM user

        The method also historically accepted an ``*expr`` parameter which
        produced the PostgreSQL dialect-specific ``DISTINCT ON`` expression.
        This is now replaced using the :func:`_postgresql.distinct_on`
        extension::

            from sqlalchemy import select
            from sqlalchemy.dialects.postgresql import distinct_on

            stmt = select(users_table).ext(distinct_on(users_table.c.name))

        Using this parameter on other backends which don't support this
        syntax will raise an error.

        :param \*expr: optional column expressions.  When present,
         the PostgreSQL dialect will render a ``DISTINCT ON (<expressions>)``
         construct.  A deprecation warning and/or :class:`_exc.CompileError`
         will be raised on other backends.

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

         .. deprecated:: 1.4 Using \*expr in other dialects is deprecated
            and will raise :class:`_exc.CompileError` in a future version.

        .. seealso::

            :func:`_postgresql.distinct_on`

            :meth:`.ext`
        """
        self._distinct = True
        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_on = self._distinct_on + tuple(
                coercions.expect(roles.ByOfRole, e, apply_propagate_attrs=self)
                for e in expr