Method filter_by

lib/sqlalchemy/sql/selectable.py:5652–5709

r"""Apply the given filtering criterion as a WHERE clause to this select, using keyword expressions. E.g.:: stmt = select(User).filter_by(name="some name") Multiple criteria may be specified as comma separated; the effect is that they will be joined tog

(self, **kwargs: Any)

        def scalar_subquery(self) -> ScalarSelect[Any]: ...

    def filter_by(self, **kwargs: Any) -> Self:
        r"""Apply the given filtering criterion as a WHERE clause
        to this select, using keyword expressions.

        E.g.::

            stmt = select(User).filter_by(name="some name")

        Multiple criteria may be specified as comma separated; the effect
        is that they will be joined together using the :func:`.and_`
        function::

            stmt = select(User).filter_by(name="some name", id=5)

        The keyword expressions are extracted by searching across **all
        entities present in the FROM clause** of the statement. If a
        keyword name is present in more than one entity,
        :class:`_exc.AmbiguousColumnError` is raised. In this case, use
        :meth:`_sql.Select.filter` or :meth:`_sql.Select.where` with
        explicit column references::

            # both User and Address have an 'id' attribute
            stmt = select(User).join(Address).filter_by(id=5)
            # raises AmbiguousColumnError

            # use filter() with explicit qualification instead
            stmt = select(User).join(Address).filter(Address.id == 5)

        .. versionchanged:: 2.1

            :meth:`_sql.Select.filter_by` now searches across all FROM clause
            entities rather than only searching the last joined entity or first
            FROM entity. This allows the method to locate attributes
            unambiguously across multiple joined tables. The new
            :class:`_exc.AmbiguousColumnError` is raised when an attribute name
            is present in more than one entity.

            See :ref:`change_8601` for migration notes.

        .. seealso::

            :ref:`tutorial_selecting_data` - in the :ref:`unified_tutorial`

            :meth:`_sql.Select.filter` - filter on SQL expressions.

            :meth:`_sql.Select.where` - filter on SQL expressions.

        """
        # Get all entities via plugin system
        all_entities = SelectState.get_plugin_class(
            self
        )._get_filter_by_entities(self)

        clauses = [
            _entity_namespace_key_search_all(all_entities, key) == value
            for key, value in kwargs.items()
        ]
        return self.filter(*clauses)