sqlalchemy.orm.properties.RelationshipProperty.Comparator

class documentation

class Comparator(util.MemoizedSlots, PropComparator[_PT]): (source)

Produce boolean, comparison, and other operators for :class:`.RelationshipProperty` attributes. See the documentation for :class:`.PropComparator` for a brief overview of ORM level operator definition. .. seealso:: :class:`.PropComparator` :class:`.ColumnProperty.Comparator` :class:`.ColumnOperators` :ref:`types_operators` :attr:`.TypeEngine.comparator_factory`

Method	`__clause_element__`	Undocumented
Method	`__eq__`	Implement the ``==`` operator.
Method	`__init__`	Construction of :class:`.RelationshipProperty.Comparator` is internal to the ORM's attribute mechanics.
Method	`__ne__`	Implement the ``!=`` operator.
Method	`adapt_to_entity`	Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions.
Method	`and_`	Add AND criteria.
Method	`any`	Produce an expression that tests a collection against particular criterion, using EXISTS.
Method	`contains`	Return a simple expression that tests a collection for containment of a particular item.
Method	`has`	Produce an expression that tests a scalar reference against particular criterion, using EXISTS.
Method	`in_`	Produce an IN clause - this is not implemented for :func:`_orm.relationship`-based attributes at this time.
Method	`of_type`	Redefine this object in terms of a polymorphic subclass.
Class Variable	`__hash__`	Undocumented
Class Variable	`__slots__`	Undocumented
Class Variable	`entity`	The target entity referred to by this :class:`.RelationshipProperty.Comparator`.
Class Variable	`mapper`	The target :class:`_orm.Mapper` referred to by this :class:`.RelationshipProperty.Comparator`.
Instance Variable	`prop`	Undocumented
Method	`__negated_contains_or_equals`	Undocumented
Method	`_criterion_exists`	Undocumented
Method	`_memoized_attr_entity`	Undocumented
Method	`_memoized_attr_mapper`	Undocumented
Method	`_memoized_attr_property`	Undocumented
Method	`_source_selectable`	Undocumented
Instance Variable	`_adapt_to_entity`	Undocumented
Instance Variable	`_extra_criteria`	Undocumented
Instance Variable	`_of_type`	Undocumented
Instance Variable	`_parententity`	Undocumented

Inherited from MemoizedSlots:

Method	`__getattr__`	Undocumented
Method	`_fallback_getattr`	Undocumented

Inherited from PropComparator (via MemoizedSlots):

Method	`operate`	Operate on an argument.
Method	`reverse_operate`	Reverse operate on an argument.
Class Variable	`__visit_name__`	Undocumented
Class Variable	`any_op`	Undocumented
Class Variable	`has_op`	Undocumented
Class Variable	`of_type_op`	Undocumented
Property	`adapter`	Produce a callable that adapts column expressions to suit an aliased version of this comparator.
Property	`info`	Undocumented
Property	`property`	Return the :class:`.MapperProperty` associated with this :class:`.PropComparator`.
Static Method	`_any_op`	Undocumented
Static Method	`_has_op`	Undocumented
Static Method	`_of_type_op`	Undocumented
Method	`_bulk_update_tuples`	Receive a SQL expression that represents a value in the SET clause of an UPDATE statement.
Property	`_parentmapper`	legacy; this is renamed to _parententity to be compatible with QueryableAttribute.

Inherited from SQLCoreOperations (via MemoizedSlots, PropComparator, SQLORMOperations):

Method	`__add__`	Implement the ``+`` operator.
Method	`__and__`	Implement the ``&`` operator.
Method	`__contains__`	Undocumented
Method	`__floordiv__`	Implement the ``//`` operator.
Method	`__ge__`	Implement the ``>=`` operator.
Method	`__getitem__`	Implement the [] operator.
Method	`__gt__`	Implement the ``>`` operator.
Method	`__invert__`	Implement the ``~`` operator.
Method	`__le__`	Implement the ``<=`` operator.
Method	`__lt__`	Implement the ``<`` operator.
Method	`__mod__`	Implement the ``%`` operator.
Method	`__mul__`	Implement the ``*`` operator.
Method	`__neg__`	Implement the ``-`` operator.
Method	`__or__`	Implement the ``\|`` operator.
Method	`__radd__`	Implement the ``+`` operator in reverse.
Method	`__rfloordiv__`	Implement the ``//`` operator in reverse.
Method	`__rmod__`	Implement the ``%`` operator in reverse.
Method	`__rmul__`	Implement the ``*`` operator in reverse.
Method	`__rsub__`	Implement the ``-`` operator in reverse.
Method	`__rtruediv__`	Implement the ``/`` operator in reverse.
Method	`__sub__`	Implement the ``-`` operator.
Method	`__truediv__`	Implement the ``/`` operator.
Method	`all_`	Produce an :func:`_expression.all_` clause against the parent object.
Method	`any_`	Produce an :func:`_expression.any_` clause against the parent object.
Method	`asc`	Produce a :func:`_expression.asc` clause against the parent object.
Method	`between`	Produce a :func:`_expression.between` clause against the parent object, given the lower and upper range.
Method	`bool_op`	Return a custom boolean operator.
Method	`collate`	Produce a :func:`_expression.collate` clause against the parent object, given the collation string.
Method	`concat`	Implement the 'concat' operator.
Method	`desc`	Produce a :func:`_expression.desc` clause against the parent object.
Method	`distinct`	Produce a :func:`_expression.distinct` clause against the parent object.
Method	`endswith`	Implement the 'endswith' operator.
Method	`ilike`	Implement the ``ilike`` operator, e.g. case insensitive LIKE.
Method	`is_`	Implement the ``IS`` operator.
Method	`is_distinct_from`	Implement the ``IS DISTINCT FROM`` operator.
Method	`is_not`	Implement the ``IS NOT`` operator.
Method	`is_not_distinct_from`	Implement the ``IS NOT DISTINCT FROM`` operator.
Method	`isnot`	Undocumented
Method	`like`	Implement the ``like`` operator.
Method	`match`	Implements a database-specific 'match' operator.
Method	`not_ilike`	implement the ``NOT ILIKE`` operator.
Method	`not_in`	implement the ``NOT IN`` operator.
Method	`not_like`	implement the ``NOT LIKE`` operator.
Method	`notilike`	Undocumented
Method	`notin_`	Undocumented
Method	`notlike`	Undocumented
Method	`nulls_first`	Produce a :func:`_expression.nulls_first` clause against the parent object.
Method	`nulls_last`	Produce a :func:`_expression.nulls_last` clause against the parent object.
Method	`nullsfirst`	Undocumented
Method	`nullslast`	Undocumented
Method	`op`	Produce a generic operator function.
Method	`regexp_match`	Implements a database-specific 'regexp match' operator.
Method	`regexp_replace`	Implements a database-specific 'regexp replace' operator.
Method	`startswith`	Implement the ``startswith`` operator.
Property	`_propagate_attrs`	Undocumented

Inherited from ColumnOperators (via MemoizedSlots, PropComparator, SQLORMOperations, SQLCoreOperations):

Method	`__lshift__`	implement the << operator.
Method	`__rshift__`	implement the >> operator.
Method	`bitwise_and`	Produce a bitwise AND operation, typically via the ``&`` operator.
Method	`bitwise_lshift`	Produce a bitwise LSHIFT operation, typically via the ``<<`` operator.
Method	`bitwise_not`	Produce a bitwise NOT operation, typically via the ``~`` operator.
Method	`bitwise_or`	Produce a bitwise OR operation, typically via the ``\|`` operator.
Method	`bitwise_rshift`	Produce a bitwise RSHIFT operation, typically via the ``>>`` operator.
Method	`bitwise_xor`	Produce a bitwise XOR operation, typically via the ``^`` operator, or ``#`` for PostgreSQL.
Method	`icontains`	Implement the ``icontains`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.contains`.
Method	`iendswith`	Implement the ``iendswith`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.endswith`.
Method	`isnot_distinct_from`	Undocumented
Method	`istartswith`	Implement the ``istartswith`` operator, e.g. case insensitive version of :meth:`.ColumnOperators.startswith`.
Class Variable	`timetuple`	Hack, allows datetime objects to be compared on the LHS.
Method	`_rconcat`	Implement an 'rconcat' operator.

Inherited from TypingOnly (via MemoizedSlots, PropComparator, SQLORMOperations, SQLCoreOperations, ColumnOperators, Operators):

Method __init_subclass__ Undocumented

def __clause_element__(self) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.__clause_element__

Undocumented

def __eq__(self, other: Any) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.sql.elements.SQLCoreOperations.__eq__

Implement the ``==`` operator. In a many-to-one context, such as:: MyClass.some_prop == <some object> this will typically produce a clause such as:: mytable.related_id == <some id> Where ``<some id>`` is the primary key of the given object. The ``==`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce a NOT EXISTS clause.

def __init__(self, prop: RelationshipProperty[_PT], parentmapper: _InternalEntityType[Any], adapt_to_entity: Optional[AliasedInsp[Any]] = None, of_type: Optional[_EntityType[_PT]] = None, extra_criteria: Tuple[ColumnElement[bool], ...] = ()): (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.__init__

Construction of :class:`.RelationshipProperty.Comparator` is internal to the ORM's attribute mechanics.

def __ne__(self, other: Any) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.sql.elements.SQLCoreOperations.__ne__

Implement the ``!=`` operator. In a many-to-one context, such as:: MyClass.some_prop != <some object> This will typically produce a clause such as:: mytable.related_id != <some id> Where ``<some id>`` is the primary key of the given object. The ``!=`` operator provides partial functionality for non- many-to-one comparisons: * Comparisons against collections are not supported. Use :meth:`~.Relationship.Comparator.contains` in conjunction with :func:`_expression.not_`. * Compared to a scalar one-to-many, will produce a clause that compares the target columns in the parent to the given target. * Compared to a scalar many-to-many, an alias of the association table will be rendered as well, forming a natural join that is part of the main body of the query. This will not work for queries that go beyond simple AND conjunctions of comparisons, such as those which use OR. Use explicit joins, outerjoins, or :meth:`~.Relationship.Comparator.has` in conjunction with :func:`_expression.not_` for more comprehensive non-many-to-one scalar membership tests. * Comparisons against ``None`` given in a one-to-many or many-to-many context produce an EXISTS clause.

def adapt_to_entity(self, adapt_to_entity: AliasedInsp[Any]) -> RelationshipProperty.Comparator[Any]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.adapt_to_entity

Return a copy of this PropComparator which will use the given :class:`.AliasedInsp` to produce corresponding expressions.

def and_(self, *criteria: _ColumnExpressionArgument[bool]) -> PropComparator[Any]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.and_

Add AND criteria. See :meth:`.PropComparator.and_` for an example. .. versionadded:: 1.4

def any(self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.any

Produce an expression that tests a collection against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.any(SomeRelated.x==2) ) Will produce a query like:: SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id AND related.x=2) Because :meth:`~.Relationship.Comparator.any` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.any` is particularly useful for testing for empty collections:: session.query(MyClass).filter( ~MyClass.somereference.any() ) will produce:: SELECT * FROM my_table WHERE NOT (EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id)) :meth:`~.Relationship.Comparator.any` is only valid for collections, i.e. a :func:`_orm.relationship` that has ``uselist=True``. For scalar references, use :meth:`~.Relationship.Comparator.has`.

def contains(self, other: _ColumnExpressionArgument[Any], **kwargs: Any) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.sql.elements.SQLCoreOperations.contains

Return a simple expression that tests a collection for containment of a particular item. :meth:`~.Relationship.Comparator.contains` is only valid for a collection, i.e. a :func:`_orm.relationship` that implements one-to-many or many-to-many with ``uselist=True``. When used in a simple one-to-many context, an expression like:: MyClass.contains(other) Produces a clause like:: mytable.id == <some id> Where ``<some id>`` is the value of the foreign key attribute on ``other`` which refers to the primary key of its parent object. From this it follows that :meth:`~.Relationship.Comparator.contains` is very useful when used with simple one-to-many operations. For many-to-many operations, the behavior of :meth:`~.Relationship.Comparator.contains` has more caveats. The association table will be rendered in the statement, producing an "implicit" join, that is, includes multiple tables in the FROM clause which are equated in the WHERE clause:: query(MyClass).filter(MyClass.contains(other)) Produces a query like:: SELECT * FROM my_table, my_association_table AS my_association_table_1 WHERE my_table.id = my_association_table_1.parent_id AND my_association_table_1.child_id = <some id> Where ``<some id>`` would be the primary key of ``other``. From the above, it is clear that :meth:`~.Relationship.Comparator.contains` will **not** work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple :meth:`~.Relationship.Comparator.contains` expressions joined by OR. In such cases subqueries or explicit "outer joins" will need to be used instead. See :meth:`~.Relationship.Comparator.any` for a less-performant alternative using EXISTS, or refer to :meth:`_query.Query.outerjoin` as well as :ref:`orm_queryguide_joins` for more details on constructing outer joins. kwargs may be ignored by this operator but are required for API conformance.

def has(self, criterion: Optional[_ColumnExpressionArgument[bool]] = None, **kwargs: Any) -> ColumnElement[bool]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.has

Produce an expression that tests a scalar reference against particular criterion, using EXISTS. An expression like:: session.query(MyClass).filter( MyClass.somereference.has(SomeRelated.x==2) ) Will produce a query like:: SELECT * FROM my_table WHERE EXISTS (SELECT 1 FROM related WHERE related.id==my_table.related_id AND related.x=2) Because :meth:`~.Relationship.Comparator.has` uses a correlated subquery, its performance is not nearly as good when compared against large target tables as that of using a join. :meth:`~.Relationship.Comparator.has` is only valid for scalar references, i.e. a :func:`_orm.relationship` that has ``uselist=False``. For collection references, use :meth:`~.Relationship.Comparator.any`.

def in_(self, other: Any) -> NoReturn: (source) ¶

overrides sqlalchemy.sql.elements.SQLCoreOperations.in_

Produce an IN clause - this is not implemented for :func:`_orm.relationship`-based attributes at this time.

def of_type(self, class_: _EntityType[Any]) -> PropComparator[_PT]: (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.of_type

Redefine this object in terms of a polymorphic subclass. See :meth:`.PropComparator.of_type` for an example.

__hash__ = (source) ¶

Undocumented

__slots__: tuple[str, ...] = (source) ¶

overrides sqlalchemy.util.langhelpers.MemoizedSlots.__slots__

Undocumented

entity: _InternalEntityType[_PT] = (source) ¶

The target entity referred to by this :class:`.RelationshipProperty.Comparator`. This is either a :class:`_orm.Mapper` or :class:`.AliasedInsp` object. This is the "target" or "remote" side of the :func:`_orm.relationship`.

mapper: Mapper[_PT] = (source) ¶

The target :class:`_orm.Mapper` referred to by this :class:`.RelationshipProperty.Comparator`. This is the "target" or "remote" side of the :func:`_orm.relationship`.

prop = (source) ¶

overrides sqlalchemy.orm.interfaces.PropComparator.prop

Undocumented