sqlalchemy.orm.properties.RelationshipProperty.Comparator

class documentation

class Comparator(PropComparator):

View In Hierarchy

Produce boolean, comparison, and other operators for .RelationshipProperty attributes.

See the documentation for .PropComparator for a brief overview of ORM level operator definition.

See Also

.PropComparator

.ColumnProperty.Comparator

.ColumnOperators

:ref:`types_operators`

.TypeEngine.comparator_factory

Method	`__clause_element__`	Undocumented
Method	`__eq__`	Implement the `==` operator.
Method	`__init__`	Construction of `.RelationshipProperty.Comparator` is internal to the ORM's attribute mechanics.
Method	`__ne__`	Implement the `!=` operator.
Method	`__negated_contains_or_equals`	Undocumented
Method	`_criterion_exists`	Undocumented
Method	`_source_selectable`	Undocumented
Method	`adapt_to_entity`	Return a copy of this PropComparator which will use the given `.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 `_orm.relationship`-based attributes at this time.
Method	`of_type`	Redefine this object in terms of a polymorphic subclass.
Class Variable	`__hash__`	Undocumented
Instance Variable	`_adapt_to_entity`	Undocumented
Instance Variable	`_extra_criteria`	Undocumented
Instance Variable	`_of_type`	Undocumented
Instance Variable	`prop`	Undocumented
Property	`_parententity`	Undocumented
Property	`entity`	The target entity referred to by this `.RelationshipProperty.Comparator`.
Property	`mapper`	The target `_orm.Mapper` referred to by this `.RelationshipProperty.Comparator`.
Property	`property`	Undocumented

Inherited from 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.
Class Variable	`__slots__`	Undocumented
Class Variable	`__visit_name__`	Undocumented
Property	`_parentmapper`	legacy; this is renamed to _parententity to be compatible with QueryableAttribute.
Property	`_propagate_attrs`	Undocumented
Property	`adapter`	Produce a callable that adapts column expressions to suit an aliased version of this comparator.
Property	`info`	Undocumented

Inherited from ColumnOperators (via PropComparator):

Method	`__add__`	Implement the `+` operator.
Method	`__contains__`	Undocumented
Method	`__div__`	Implement the `/` operator.
Method	`__ge__`	Implement the `>=` operator.
Method	`__getitem__`	Implement the [] operator.
Method	`__gt__`	Implement the `>` operator.
Method	`__le__`	Implement the `<=` operator.
Method	`__lshift__`	implement the << operator.
Method	`__lt__`	Implement the `<` operator.
Method	`__mod__`	Implement the `%` operator.
Method	`__mul__`	Implement the `*` operator.
Method	`__neg__`	Implement the `-` operator.
Method	`__radd__`	Implement the `+` operator in reverse.
Method	`__rdiv__`	Implement the `/` operator in reverse.
Method	`__rmod__`	Implement the `%` operator in reverse.
Method	`__rmul__`	Implement the `*` operator in reverse.
Method	`__rshift__`	implement the >> operator.
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 `_expression.all_` clause against the parent object.
Method	`any_`	Produce an `_expression.any_` clause against the parent object.
Method	`asc`	Produce a `_expression.asc` clause against the parent object.
Method	`between`	Produce a `_expression.between` clause against the parent object, given the lower and upper range.
Method	`collate`	Produce a `_expression.collate` clause against the parent object, given the collation string.
Method	`concat`	Implement the 'concat' operator.
Method	`desc`	Produce a `_expression.desc` clause against the parent object.
Method	`distinct`	Produce a `_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	`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	`nulls_first`	Produce a `_expression.nulls_first` clause against the parent object.
Method	`nulls_last`	Produce a `_expression.nulls_last` clause against the parent object.
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.
Class Variable	`timetuple`	Hack, allows datetime objects to be compared on the LHS.

Inherited from Operators (via PropComparator, ColumnOperators):

Method	`__and__`	Implement the `&` operator.
Method	`__invert__`	Implement the `~` operator.
Method	`__or__`	Implement the `\|` operator.
Method	`bool_op`	Return a custom boolean operator.
Method	`op`	Produce a generic operator function.
Method	`operate`	Operate on an argument.
Method	`reverse_operate`	Reverse operate on an argument.

def __clause_element__(self):

overrides sqlalchemy.orm.interfaces.PropComparator.__clause_element__

Undocumented

def __eq__(self, other):

overrides sqlalchemy.sql.operators.ColumnOperators.__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 ~.RelationshipProperty.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 ~.RelationshipProperty.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, parentmapper, adapt_to_entity=None, of_type=None, extra_criteria=()):

overrides sqlalchemy.orm.interfaces.PropComparator.__init__

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

def __ne__(self, other):

overrides sqlalchemy.sql.operators.ColumnOperators.__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 ~.RelationshipProperty.Comparator.contains in conjunction with _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 ~.RelationshipProperty.Comparator.has in conjunction with _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 __negated_contains_or_equals(self, other):

Undocumented

def _criterion_exists(self, criterion=None, **kwargs):

Undocumented

def _source_selectable(self):

Undocumented

def adapt_to_entity(self, adapt_to_entity):

overrides sqlalchemy.orm.interfaces.PropComparator.adapt_to_entity

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

def and_(self, *other):

overrides sqlalchemy.orm.interfaces.PropComparator.and_

Add AND criteria.

See .PropComparator.and_ for an example.

New in version 1.4.

def any(self, criterion=None, **kwargs):

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 ~.RelationshipProperty.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.

~.RelationshipProperty.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))

~.RelationshipProperty.Comparator.any is only valid for collections, i.e. a _orm.relationship that has uselist=True. For scalar references, use ~.RelationshipProperty.Comparator.has.

def contains(self, other, **kwargs):

overrides sqlalchemy.sql.operators.ColumnOperators.contains

Return a simple expression that tests a collection for containment of a particular item.

~.RelationshipProperty.Comparator.contains is only valid for a collection, i.e. a _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 ~.RelationshipProperty.Comparator.contains is very useful when used with simple one-to-many operations.

For many-to-many operations, the behavior of ~.RelationshipProperty.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 ~.RelationshipProperty.Comparator.contains will not work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple ~.RelationshipProperty.Comparator.contains expressions joined by OR. In such cases subqueries or explicit "outer joins" will need to be used instead. See ~.RelationshipProperty.Comparator.any for a less-performant alternative using EXISTS, or refer to _query.Query.outerjoin as well as :ref:`ormtutorial_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=None, **kwargs):

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 ~.RelationshipProperty.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.

~.RelationshipProperty.Comparator.has is only valid for scalar references, i.e. a _orm.relationship that has uselist=False. For collection references, use ~.RelationshipProperty.Comparator.any.

def in_(self, other):

overrides sqlalchemy.sql.operators.ColumnOperators.in_

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

def of_type(self, cls):

overrides sqlalchemy.orm.interfaces.PropComparator.of_type

Redefine this object in terms of a polymorphic subclass.

See .PropComparator.of_type for an example.

__hash__ =

Undocumented

_adapt_to_entity =

overrides sqlalchemy.orm.interfaces.PropComparator._adapt_to_entity

Undocumented

_extra_criteria =

Undocumented

_of_type =

Undocumented

prop =

overrides sqlalchemy.orm.interfaces.PropComparator.prop

Undocumented

@util.memoized_property
_parententity =

overrides sqlalchemy.orm.interfaces.PropComparator._parententity

Undocumented

@util.memoized_property
entity =

The target entity referred to by this .RelationshipProperty.Comparator.

This is either a _orm.Mapper or .AliasedInsp object.

This is the "target" or "remote" side of the _orm.relationship.

@util.memoized_property
mapper =

The target _orm.Mapper referred to by this .RelationshipProperty.Comparator.

This is the "target" or "remote" side of the _orm.relationship.

@util.memoized_property
property =

overrides sqlalchemy.orm.interfaces.PropComparator.property

Undocumented