Release: 1.4.54 | Release Date: September 5, 2024

# SQLAlchemy 1.4 Documentation

# ORM Internals

Key ORM constructs, not otherwise covered in other sections, are listed here.

Object Name | Description
--- | ---
AttributeEvent | A token propagated throughout the course of a chain of attribute events.
AttributeState | Provide an inspection interface corresponding to a particular attribute on a particular mapped object.
CascadeOptions | Keeps track of the options sent to `relationship.cascade`
ClassManager | Tracks state information at the class level.
ColumnProperty | Describes an object attribute that corresponds to a table column.
CompositeProperty | Defines a “composite” mapped attribute, representing a collection of columns as one attribute.
IdentityMap |
InspectionAttr | A base class applied to all ORM objects that can be returned by the `inspect()` function.
InspectionAttrInfo | Adds the `.info` attribute to `InspectionAttr`.
InstanceState | tracks state information at the instance level.
InstrumentedAttribute | Class bound instrumented attribute which adds basic descriptor methods.
MANYTOMANY | Indicates the many-to-many direction for a `relationship()`.
MANYTOONE | Indicates the many-to-one direction for a `relationship()`.
Mapped | Represent an ORM mapped descriptor attribute for typing purposes.
MapperProperty | Represent a particular class attribute mapped by `Mapper`.
merge_frozen_result(session, statement, frozen_result[, load]) | Merge a `FrozenResult` back into a `Session`, returning a new `Result` object with persistent objects.
merge_result(query, iterator[, load]) | Merge a result into the given `Query` object’s Session.
NOT_EXTENSION | Symbol indicating an `InspectionAttr` that’s not part of sqlalchemy.ext.
ONETOMANY | Indicates the one-to-many direction for a `relationship()`.
PropComparator | Defines SQL operators for `MapperProperty` objects.
QueryableAttribute | Base class for descriptor objects that intercept attribute events on behalf of a `MapperProperty` object. The actual `MapperProperty` is accessible via the `QueryableAttribute.property` attribute.
QueryContext |
RelationshipProperty | Describes an object property that holds a single item or list of items that correspond to a related database table.
SynonymProperty |
UOWTransaction |

class sqlalchemy.orm.AttributeState(state, key)

  Provide an inspection interface corresponding to a particular attribute on a particular mapped object.

  The `AttributeState` object is accessed via the `InstanceState.attrs` collection of a particular `InstanceState`:

  Members

  history, load_history(), loaded_value, value

      from sqlalchemy import inspect

      insp = inspect(some_mapped_object)
      attr_state = insp.attrs.some_attribute

  attribute `sqlalchemy.orm.AttributeState.`history

    Return the current pre-flush change history for this attribute, via the `History` interface.

    This method will not emit loader callables if the value of the attribute is unloaded.

    Note

    The attribute history system tracks changes on a per flush basis. Each time the `Session` is flushed, the history of each attribute is reset to empty. The `Session` by default autoflushes each time a `Query` is invoked. For options on how to control this, see Flushing.

    See also

    `AttributeState.load_history()` - retrieve history using loader callables if the value is not locally present.

    `get_history()` - underlying function

  method `sqlalchemy.orm.AttributeState.`load_history()

    Return the current pre-flush change history for this attribute, via the `History` interface.

    This method will emit loader callables if the value of the attribute is unloaded.

    Note

    The attribute history system tracks changes on a per flush basis. Each time the `Session` is flushed, the history of each attribute is reset to empty. The `Session` by default autoflushes each time a `Query` is invoked. For options on how to control this, see Flushing.

    See also

    `AttributeState.history`

    `get_history()` - underlying function

    Added in version 0.9.0.

  attribute `sqlalchemy.orm.AttributeState.`loaded_value

    The current value of this attribute as loaded from the database.

    If the value has not been loaded, or is otherwise not present in the object’s dictionary, returns NO_VALUE.

  attribute `sqlalchemy.orm.AttributeState.`value

    Return the value of this attribute.

    This operation is equivalent to accessing the object’s attribute directly or via `getattr()`, and will fire off any pending loader callables if needed.

class sqlalchemy.orm.CascadeOptions(value_list)

  Keeps track of the options sent to `relationship.cascade`

  Class signature

  class `sqlalchemy.orm.CascadeOptions` (`builtins.frozenset`)

class sqlalchemy.orm.ClassManager(class_)

  Tracks state information at the class level.

  Members

  deferred_scalar_loader, expired_attribute_loader, has_parent(), manage(), state_getter(), unregister()

  Class signature

  class `sqlalchemy.orm.ClassManager` (`sqlalchemy.util.langhelpers.HasMemoized`, `builtins.dict`)

  attribute `sqlalchemy.orm.ClassManager.`deferred_scalar_loader

    Deprecated since version 1.4: The ClassManager.deferred_scalar_loader attribute is now named expired_attribute_loader

  attribute `sqlalchemy.orm.ClassManager.`expired_attribute_loader = None

    previously known as deferred_scalar_loader

  method `sqlalchemy.orm.ClassManager.`has_parent(state, key, optimistic=False)

    TODO

  method `sqlalchemy.orm.ClassManager.`manage()

    Mark this instance as the manager for its class.

  method `sqlalchemy.orm.ClassManager.`state_getter()

    Return a (instance) -> InstanceState callable.

    “state getter” callables should raise either KeyError or AttributeError if no InstanceState could be found for the instance.

  method `sqlalchemy.orm.ClassManager.`unregister()

    remove all instrumentation established by this ClassManager.

class sqlalchemy.orm.ColumnProperty(*columns, **kwargs)

  Describes an object attribute that corresponds to a table column.

  Public constructor is the `column_property()` function.

  Members

  expressions, operate(), reverse_operate(), __init__(), do_init(), expression, inherit_cache, instrument_class(), merge()

  Class signature

  class `sqlalchemy.orm.ColumnProperty` (`sqlalchemy.orm.StrategizedProperty`)

  attribute `sqlalchemy.orm.ColumnProperty.`Comparator.expressions

    The full sequence of columns referenced by this attribute, adjusted for any aliasing in progress.

    Added in version 1.3.17.

    See also

    Mapping a Class against Multiple Tables - usage example

  class Comparator(prop, parentmapper, adapt_to_entity=None)

    Produce boolean, comparison, and other operators for `ColumnProperty` attributes.

    See the documentation for `PropComparator` for a brief overview.

    See also

    `PropComparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

    Class signature

    class `sqlalchemy.orm.ColumnProperty.Comparator` (`sqlalchemy.util.langhelpers.MemoizedSlots`, `sqlalchemy.orm.PropComparator`)

    method `sqlalchemy.orm.ColumnProperty.Comparator.`operate(op, *other, **kwargs)

      Operate on an argument.

      This is the lowest level of operation, raises `NotImplementedError` by default.

      Overriding this on a subclass can allow common behavior to be applied to all operations. For example, overriding `ColumnOperators` to apply `func.lower()` to the left and right side:

          class MyComparator(ColumnOperators):
              def operate(self, op, other, **kwargs):
                  return op(func.lower(self), func.lower(other), **kwargs)

      Parameters:

        - op – Operator callable.

        - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.

        - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

    method `sqlalchemy.orm.ColumnProperty.Comparator.`reverse_operate(op, other, **kwargs)

      Reverse operate on an argument.

      Usage is the same as `operate()`.

  method `sqlalchemy.orm.ColumnProperty.`__init__(*columns, **kwargs)

    Construct a new `ColumnProperty` object.

    This constructor is mirrored as a public API function; see `sqlalchemy.orm.column_property()` for a full usage and argument description.

  method `sqlalchemy.orm.ColumnProperty.`do_init()

    Perform subclass-specific initialization post-mapper-creation steps.

    This is a template method called by the `MapperProperty` object’s init() method.

  attribute `sqlalchemy.orm.ColumnProperty.`expression

    Return the primary column or expression for this ColumnProperty.

    E.g.:

        class File(Base):
            # ...

            name = Column(String(64))
            extension = Column(String(8))
            filename = column_property(name + '.' + extension)
            path = column_property('C:/' + filename.expression)

    See also

    Composing from Column Properties at Mapping Time

  attribute `sqlalchemy.orm.ColumnProperty.`inherit_cache = True

    Indicate if this `HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass.

    The attribute defaults to `None`, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to `False`, except that a warning is also emitted.

    This flag can be set to `True` on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

    See also

    Enabling Caching Support for Custom Constructs - General guideslines for setting the `HasCacheKey.inherit_cache` attribute for third-party or user defined SQL constructs.

  method `sqlalchemy.orm.ColumnProperty.`instrument_class(mapper)

    Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.

    The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.

    This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.

    The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

  method `sqlalchemy.orm.ColumnProperty.`merge(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)

    Merge the attribute represented by this `MapperProperty` from source to destination object.

class sqlalchemy.orm.CompositeProperty(class_, *attrs, **kwargs)

  Defines a “composite” mapped attribute, representing a collection of columns as one attribute.

  `CompositeProperty` is constructed using the `composite()` function.

  See also

  Composite Column Types

  Members

  create_row_processor(), __init__(), do_init(), get_history(), instrument_class()

  Class signature

  class `sqlalchemy.orm.CompositeProperty` (`sqlalchemy.orm.descriptor_props.DescriptorProperty`)

  class Comparator(prop, parentmapper, adapt_to_entity=None)

    Produce boolean, comparison, and other operators for `CompositeProperty` attributes.

    See the example in Redefining Comparison Operations for Composites for an overview of usage , as well as the documentation for `PropComparator`.

    See also

    `PropComparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

    Class signature

    class `sqlalchemy.orm.CompositeProperty.Comparator` (`sqlalchemy.orm.PropComparator`)

  class CompositeBundle(property_, expr)

    Class signature

    class `sqlalchemy.orm.CompositeProperty.CompositeBundle` (`sqlalchemy.orm.Bundle`)

    method `sqlalchemy.orm.CompositeProperty.CompositeBundle.`create_row_processor(query, procs, labels)

      Produce the “row processing” function for this `Bundle`.

      May be overridden by subclasses.

      See also

      Column Bundles - includes an example of subclassing.

  method `sqlalchemy.orm.CompositeProperty.`__init__(class_, *attrs, **kwargs)

    Construct a new `CompositeProperty` object.

    This constructor is mirrored as a public API function; see `sqlalchemy.orm.composite()` for a full usage and argument description.

  method `sqlalchemy.orm.CompositeProperty.`do_init()

    Initialization which occurs after the `CompositeProperty` has been associated with its parent mapper.

  method `sqlalchemy.orm.CompositeProperty.`get_history(state, dict_, passive=symbol('PASSIVE_OFF'))

    Provided for userland code that uses attributes.get_history().

  method `sqlalchemy.orm.CompositeProperty.`instrument_class(mapper)

    Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.

    The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.

    This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.

    The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

class sqlalchemy.orm.AttributeEvent(attribute_impl, op)

  A token propagated throughout the course of a chain of attribute events.

  Serves as an indicator of the source of the event and also provides a means of controlling propagation across a chain of attribute operations.

  The `Event` object is sent as the `initiator` argument when dealing with events such as `AttributeEvents.append()`, `AttributeEvents.set()`, and `AttributeEvents.remove()`.

  The `Event` object is currently interpreted by the backref event handlers, and is used to control the propagation of operations across two mutually-dependent attributes.

  Added in version 0.9.0.

  Attribute impl:

    The `AttributeImpl` which is the current event initiator.

  Attribute op:

    The symbol `OP_APPEND`, `OP_REMOVE`, `OP_REPLACE`, or `OP_BULK_REPLACE`, indicating the source operation.

class sqlalchemy.orm.IdentityMap

  Members

  check_modified()

  method `sqlalchemy.orm.IdentityMap.`check_modified()

    return True if any InstanceStates present have been marked as ‘modified’.

class sqlalchemy.orm.InspectionAttr

  A base class applied to all ORM objects that can be returned by the `inspect()` function.

  The attributes defined here allow the usage of simple boolean checks to test basic facts about the object returned.

  Members

  extension_type, is_aliased_class, is_attribute, is_bundle, is_clause_element, is_instance, is_mapper, is_property, is_selectable

  While the boolean checks here are basically the same as using the Python isinstance() function, the flags here can be used without the need to import all of these classes, and also such that the SQLAlchemy class system can change while leaving the flags here intact for forwards-compatibility.

  attribute `sqlalchemy.orm.InspectionAttr.`extension_type = symbol('NOT_EXTENSION')

    The extension type, if any. Defaults to `NOT_EXTENSION`

    See also

    `HYBRID_METHOD`

    `HYBRID_PROPERTY`

    `ASSOCIATION_PROXY`

  attribute `sqlalchemy.orm.InspectionAttr.`is_aliased_class = False

    True if this object is an instance of `AliasedClass`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_attribute = False

    True if this object is a Python descriptor.

    This can refer to one of many types. Usually a `QueryableAttribute` which handles attributes events on behalf of a `MapperProperty`. But can also be an extension type such as `AssociationProxy` or `hybrid_property`. The `InspectionAttr.extension_type` will refer to a constant identifying the specific subtype.

    See also

    `Mapper.all_orm_descriptors`

  attribute `sqlalchemy.orm.InspectionAttr.`is_bundle = False

    True if this object is an instance of `Bundle`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_clause_element = False

    True if this object is an instance of `ClauseElement`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_instance = False

    True if this object is an instance of `InstanceState`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_mapper = False

    True if this object is an instance of `Mapper`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_property = False

    True if this object is an instance of `MapperProperty`.

  attribute `sqlalchemy.orm.InspectionAttr.`is_selectable = False

    Return True if this object is an instance of `Selectable`.

class sqlalchemy.orm.InspectionAttrInfo

  Adds the `.info` attribute to `InspectionAttr`.

  The rationale for `InspectionAttr` vs. `InspectionAttrInfo` is that the former is compatible as a mixin for classes that specify `__slots__`; this is essentially an implementation artifact.

  Members

  info

  Class signature

  class `sqlalchemy.orm.InspectionAttrInfo` (`sqlalchemy.orm.base.InspectionAttr`)

  attribute `sqlalchemy.orm.InspectionAttrInfo.`info

    Info dictionary associated with the object, allowing user-defined data to be associated with this `InspectionAttr`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    Changed in version 1.0.0: `MapperProperty.info` is also available on extension types via the `InspectionAttrInfo.info` attribute, so that it can apply to a wider variety of ORM and extension constructs.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

class sqlalchemy.orm.InstanceState(obj, manager)

  tracks state information at the instance level.

  The `InstanceState` is a key object used by the SQLAlchemy ORM in order to track the state of an object; it is created the moment an object is instantiated, typically as a result of instrumentation which SQLAlchemy applies to the `__init__()` method of the class.

  `InstanceState` is also a semi-public object, available for runtime inspection as to the state of a mapped instance, including information such as its current status within a particular `Session` and details about data on individual attributes. The public API in order to acquire a `InstanceState` object is to use the `inspect()` system:

      >>> from sqlalchemy import inspect
      >>> insp = inspect(some_mapped_object)
      >>> insp.attrs.nickname.history
      History(added=['new nickname'], unchanged=(), deleted=['nickname'])

  See also

  Inspection of Mapped Instances

  Members

  async_session, attrs, callables, deleted, detached, dict, expired_attributes, has_identity, identity, identity_key, is_instance, mapper, object, pending, persistent, session, transient, unloaded, unloaded_expirable, unmodified, unmodified_intersection(), was_deleted

  Class signature

  class `sqlalchemy.orm.InstanceState` (`sqlalchemy.orm.base.InspectionAttrInfo`)

  attribute `sqlalchemy.orm.InstanceState.`async_session

    Return the owning `AsyncSession` for this instance, or `None` if none available.

    This attribute is only non-None when the `sqlalchemy.ext.asyncio` API is in use for this ORM object. The returned `AsyncSession` object will be a proxy for the `Session` object that would be returned from the `InstanceState.session` attribute for this `InstanceState`.

    Added in version 1.4.18.

    See also

    Asynchronous I/O (asyncio)

  attribute `sqlalchemy.orm.InstanceState.`attrs

    Return a namespace representing each attribute on the mapped object, including its current value and history.

    The returned object is an instance of `AttributeState`. This object allows inspection of the current data within an attribute as well as attribute history since the last flush.

  attribute `sqlalchemy.orm.InstanceState.`callables = ()

    A namespace where a per-state loader callable can be associated.

    In SQLAlchemy 1.0, this is only used for lazy loaders / deferred loaders that were set up via query option.

    Previously, callables was used also to indicate expired attributes by storing a link to the InstanceState itself in this dictionary. This role is now handled by the expired_attributes set.

  attribute `sqlalchemy.orm.InstanceState.`deleted

    Return `True` if the object is deleted.

    An object that is in the deleted state is guaranteed to not be within the `Session.identity_map` of its parent `Session`; however if the session’s transaction is rolled back, the object will be restored to the persistent state and the identity map.

    Note

    The `InstanceState.deleted` attribute refers to a specific state of the object that occurs between the “persistent” and “detached” states; once the object is detached, the `InstanceState.deleted` attribute no longer returns True; in order to detect that a state was deleted, regardless of whether or not the object is associated with a `Session`, use the `InstanceState.was_deleted` accessor.

    See also

    Quickie Intro to Object States

  attribute `sqlalchemy.orm.InstanceState.`detached

    Return `True` if the object is detached.

    See also

    Quickie Intro to Object States

  attribute `sqlalchemy.orm.InstanceState.`dict

    Return the instance dict used by the object.

    Under normal circumstances, this is always synonymous with the `__dict__` attribute of the mapped object, unless an alternative instrumentation system has been configured.

    In the case that the actual object has been garbage collected, this accessor returns a blank dictionary.

  attribute `sqlalchemy.orm.InstanceState.`expired_attributes = None

    The set of keys which are ‘expired’ to be loaded by the manager’s deferred scalar loader, assuming no pending changes.

    see also the `unmodified` collection which is intersected against this set when a refresh operation occurs.

  attribute `sqlalchemy.orm.InstanceState.`has_identity

    Return `True` if this object has an identity key.

    This should always have the same value as the expression `state.persistent` or `state.detached`.

  attribute `sqlalchemy.orm.InstanceState.`identity

    Return the mapped identity of the mapped object. This is the primary key identity as persisted by the ORM which can always be passed directly to `Query.get()`.

    Returns `None` if the object has no primary key identity.

    Note

    An object which is transient or pending does not have a mapped identity until it is flushed, even if its attributes include primary key values.

  attribute `sqlalchemy.orm.InstanceState.`identity_key

    Return the identity key for the mapped object.

    This is the key used to locate the object within the `Session.identity_map` mapping. It contains the identity as returned by `identity` within it.

  attribute `sqlalchemy.orm.InstanceState.`is_instance = True

    True if this object is an instance of `InstanceState`.

  attribute `sqlalchemy.orm.InstanceState.`mapper

    Return the `Mapper` used for this mapped object.

  attribute `sqlalchemy.orm.InstanceState.`object

    Return the mapped object represented by this `InstanceState`.

  attribute `sqlalchemy.orm.InstanceState.`pending

    Return `True` if the object is pending.

    See also

    Quickie Intro to Object States

  attribute `sqlalchemy.orm.InstanceState.`persistent

    Return `True` if the object is persistent.

    An object that is in the persistent state is guaranteed to be within the `Session.identity_map` of its parent `Session`.

    Changed in version 1.1: The `InstanceState.persistent` accessor no longer returns True for an object that was “deleted” within a flush; use the `InstanceState.deleted` accessor to detect this state. This allows the “persistent” state to guarantee membership in the identity map.

    See also

    Quickie Intro to Object States

  attribute `sqlalchemy.orm.InstanceState.`session

    Return the owning `Session` for this instance, or `None` if none available.

    Note that the result here can in some cases be different from that of `obj in session`; an object that’s been deleted will report as not `in session`, however if the transaction is still in progress, this attribute will still refer to that session. Only when the transaction is completed does the object become fully detached under normal circumstances.

    See also

    `InstanceState.async_session`

  attribute `sqlalchemy.orm.InstanceState.`transient

    Return `True` if the object is transient.

    See also

    Quickie Intro to Object States

  attribute `sqlalchemy.orm.InstanceState.`unloaded

    Return the set of keys which do not have a loaded value.

    This includes expired attributes and any other attribute that was never populated or modified.

  attribute `sqlalchemy.orm.InstanceState.`unloaded_expirable

    Return the set of keys which do not have a loaded value.

    This includes expired attributes and any other attribute that was never populated or modified.

  attribute `sqlalchemy.orm.InstanceState.`unmodified

    Return the set of keys which have no uncommitted changes

  method `sqlalchemy.orm.InstanceState.`unmodified_intersection(keys)

    Return self.unmodified.intersection(keys).

  attribute `sqlalchemy.orm.InstanceState.`was_deleted

    Return True if this object is or was previously in the “deleted” state and has not been reverted to persistent.

    This flag returns True once the object was deleted in flush. When the object is expunged from the session either explicitly or via transaction commit and enters the “detached” state, this flag will continue to report True.

    Added in version 1.1: - added a local method form of `was_deleted()`.

    See also

    `InstanceState.deleted` - refers to the “deleted” state

    `was_deleted()` - standalone function

    Quickie Intro to Object States

class sqlalchemy.orm.InstrumentedAttribute(class_, key, parententity, impl=None, comparator=None, of_type=None, extra_criteria=())

  Class bound instrumented attribute which adds basic descriptor methods.

  See `QueryableAttribute` for a description of most features.

  Members

  __delete__(), __get__(), __set__()

  Class signature

  class `sqlalchemy.orm.InstrumentedAttribute` (`sqlalchemy.orm.Mapped`)

  method `sqlalchemy.orm.InstrumentedAttribute.`__delete__(instance)
  method `sqlalchemy.orm.InstrumentedAttribute.`__get__(instance, owner)
  method `sqlalchemy.orm.InstrumentedAttribute.`__set__(instance, value)

sqlalchemy.orm.MANYTOONE = symbol('MANYTOONE')

  Indicates the many-to-one direction for a `relationship()`.

  This symbol is typically used by the internals but may be exposed within certain API features.

sqlalchemy.orm.MANYTOMANY = symbol('MANYTOMANY')

  Indicates the many-to-many direction for a `relationship()`.

  This symbol is typically used by the internals but may be exposed within certain API features.

class sqlalchemy.orm.Mapped(class_, key, parententity, impl=None, comparator=None, of_type=None, extra_criteria=())

  Represent an ORM mapped descriptor attribute for typing purposes.

  This class represents the complete descriptor interface for any class attribute that will have been instrumented by the ORM `Mapper` class. When used with typing stubs, it is the final type that would be used by a type checker such as mypy to provide the full behavioral contract for the attribute.

  Tip

  The `Mapped` class represents attributes that are handled directly by the `Mapper` class. It does not include other Python descriptor classes that are provided as extensions, including Hybrid Attributes and the Association Proxy. While these systems still make use of ORM-specific superclasses and structures, they are not instrumented by the `Mapper` and instead provide their own functionality when they are accessed on a class.

  When using the SQLAlchemy Mypy plugin, the `Mapped` construct is used in typing annotations to indicate to the plugin those attributes that are expected to be mapped; the plugin also applies `Mapped` as an annotation automatically when it scans through declarative mappings in Declarative Table style. For more indirect mapping styles such as imperative table it is typically applied explicitly to class level attributes that expect to be mapped based on a given `Table` configuration.

  `Mapped` is defined in the sqlalchemy2-stubs project as a PEP 484 generic class which may subscribe to any arbitrary Python type, which represents the Python type handled by the attribute:

      class MyMappedClass(Base):
          __table_ = Table(
              "some_table", Base.metadata,
              Column("id", Integer, primary_key=True),
              Column("data", String(50)),
              Column("created_at", DateTime)
          )

          id : Mapped[int]
          data: Mapped[str]
          created_at: Mapped[datetime]

  For complete background on how to use `Mapped` with pep-484 tools like Mypy, see the link below for background on SQLAlchemy’s Mypy plugin.

  Added in version 1.4.

  See also

  Mypy / Pep-484 Support for ORM Mappings - complete background on Mypy integration

  Class signature

  class `sqlalchemy.orm.Mapped` (`sqlalchemy.orm.QueryableAttribute`, `typing.Generic`)

class sqlalchemy.orm.MapperProperty

  Represent a particular class attribute mapped by `Mapper`.

  The most common occurrences of `MapperProperty` are the mapped `Column`, which is represented in a mapping as an instance of `ColumnProperty`, and a reference to another class produced by `relationship()`, represented in the mapping as an instance of `RelationshipProperty`.

  Members

  info, cascade, cascade_iterator(), class_attribute, create_row_processor(), do_init(), init(), instrument_class(), is_property, merge(), post_instrument_class(), set_parent(), setup()

  Class signature

  class `sqlalchemy.orm.MapperProperty` (`sqlalchemy.sql.traversals.HasCacheKey`, `sqlalchemy.orm.base._MappedAttribute`, `sqlalchemy.orm.base.InspectionAttr`, `sqlalchemy.util.langhelpers.MemoizedSlots`)

  attribute `sqlalchemy.orm.MapperProperty.`info

    Info dictionary associated with the object, allowing user-defined data to be associated with this `InspectionAttr`.

    The dictionary is generated when first accessed. Alternatively, it can be specified as a constructor argument to the `column_property()`, `relationship()`, or `composite()` functions.

    Changed in version 1.0.0: `InspectionAttr.info` moved from `MapperProperty` so that it can apply to a wider variety of ORM and extension constructs.

    See also

    `QueryableAttribute.info`

    `SchemaItem.info`

  attribute `sqlalchemy.orm.MapperProperty.`cascade = frozenset({})

    The set of ‘cascade’ attribute names.

    This collection is checked before the ‘cascade_iterator’ method is called.

    The collection typically only applies to a RelationshipProperty.

  method `sqlalchemy.orm.MapperProperty.`cascade_iterator(type_, state, dict_, visited_states, halt_on=None)

    Iterate through instances related to the given instance for a particular ‘cascade’, starting with this MapperProperty.

    Return an iterator3-tuples (instance, mapper, state).

    Note that the ‘cascade’ collection on this MapperProperty is checked first for the given type before cascade_iterator is called.

    This method typically only applies to RelationshipProperty.

  attribute `sqlalchemy.orm.MapperProperty.`class_attribute

    Return the class-bound descriptor corresponding to this `MapperProperty`.

    This is basically a `getattr()` call:

        return getattr(self.parent.class_, self.key)

    I.e. if this `MapperProperty` were named `addresses`, and the class to which it is mapped is `User`, this sequence is possible:

        >>> from sqlalchemy import inspect
        >>> mapper = inspect(User)
        >>> addresses_property = mapper.attrs.addresses
        >>> addresses_property.class_attribute is User.addresses
        True
        >>> User.addresses.property is addresses_property
        True

  method `sqlalchemy.orm.MapperProperty.`create_row_processor(context, query_entity, path, mapper, result, adapter, populators)

    Produce row processing functions and append to the given set of populators lists.

  method `sqlalchemy.orm.MapperProperty.`do_init()

    Perform subclass-specific initialization post-mapper-creation steps.

    This is a template method called by the `MapperProperty` object’s init() method.

  method `sqlalchemy.orm.MapperProperty.`init()

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  method `sqlalchemy.orm.MapperProperty.`instrument_class(mapper)

    Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.

    The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.

    This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.

    The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

  attribute `sqlalchemy.orm.MapperProperty.`is_property = True

    Part of the InspectionAttr interface; states this object is a mapper property.

  method `sqlalchemy.orm.MapperProperty.`merge(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)

    Merge the attribute represented by this `MapperProperty` from source to destination object.

  method `sqlalchemy.orm.MapperProperty.`post_instrument_class(mapper)

    Perform instrumentation adjustments that need to occur after init() has completed.

    The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.

    This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.

  method `sqlalchemy.orm.MapperProperty.`set_parent(parent, init)

    Set the parent mapper that references this MapperProperty.

    This method is overridden by some subclasses to perform extra setup when the mapper is first known.

  method `sqlalchemy.orm.MapperProperty.`setup(context, query_entity, path, adapter, **kwargs)

    Called by Query for the purposes of constructing a SQL statement.

    Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate.

sqlalchemy.orm.NOT_EXTENSION = symbol('NOT_EXTENSION')

  Symbol indicating an `InspectionAttr` that’s not part of sqlalchemy.ext.

  Is assigned to the `InspectionAttr.extension_type` attribute.

function sqlalchemy.orm.merge_result(query, iterator, load=True)

  Merge a result into the given `Query` object’s Session.

  Deprecated since version 1.4: The `merge_result()` function is considered legacy as of the 1.x series of SQLAlchemy and becomes a legacy construct in 2.0. The function as well as the method on `Query` is superseded by the `merge_frozen_result()` function. (Background on SQLAlchemy 2.0 at: Migrating to SQLAlchemy 2.0)

  See `Query.merge_result()` for top-level documentation on this function.

function sqlalchemy.orm.merge_frozen_result(session, statement, frozen_result, load=True)

  Merge a `FrozenResult` back into a `Session`, returning a new `Result` object with persistent objects.

  See the section Re-Executing Statements for an example.

  See also

  Re-Executing Statements

  `Result.freeze()`

  `FrozenResult`

sqlalchemy.orm.ONETOMANY = symbol('ONETOMANY')

  Indicates the one-to-many direction for a `relationship()`.

  This symbol is typically used by the internals but may be exposed within certain API features.

class sqlalchemy.orm.PropComparator(prop, parentmapper, adapt_to_entity=None)

  Defines SQL operators for `MapperProperty` objects.

  SQLAlchemy allows for operators to be redefined at both the Core and ORM level. `PropComparator` is the base class of operator redefinition for ORM-level operations, including those of `ColumnProperty`, `RelationshipProperty`, and `CompositeProperty`.

  Note

  With the advent of Hybrid properties introduced in SQLAlchemy 0.7, as well as Core-level operator redefinition in SQLAlchemy 0.8, the use case for user-defined `PropComparator` instances is extremely rare. See Hybrid Attributes as well as Redefining and Creating New Operators.

  User-defined subclasses of `PropComparator` may be created. The built-in Python comparison and math operator methods, such as `ColumnOperators.__eq__()`, `ColumnOperators.__lt__()`, and `ColumnOperators.__add__()`, can be overridden to provide new operator behavior. The custom `PropComparator` is passed to the `MapperProperty` instance via the `comparator_factory` argument. In each case, the appropriate subclass of `PropComparator` should be used:

      # definition of custom PropComparator subclasses

      from sqlalchemy.orm.properties import \
                              ColumnProperty,\
                              CompositeProperty,\
                              RelationshipProperty

      class MyColumnComparator(ColumnProperty.Comparator):
          def __eq__(self, other):
              return self.__clause_element__() == other

      class MyRelationshipComparator(RelationshipProperty.Comparator):
          def any(self, expression):
              "define the 'any' operation"
              # ...

      class MyCompositeComparator(CompositeProperty.Comparator):
          def __gt__(self, other):
              "redefine the 'greater than' operation"

              return sql.and_(*[a>b for a, b in
                                zip(self.__clause_element__().clauses,
                                    other.__composite_values__())])

      # application of custom PropComparator subclasses

      from sqlalchemy.orm import column_property, relationship, composite
      from sqlalchemy import Column, String

      class SomeMappedClass(Base):
          some_column = column_property(Column("some_column", String),
                              comparator_factory=MyColumnComparator)

          some_relationship = relationship(SomeOtherClass,
                              comparator_factory=MyRelationshipComparator)

          some_composite = composite(
                  Column("a", String), Column("b", String),
                  comparator_factory=MyCompositeComparator
              )

  Note that for column-level operator redefinition, it’s usually simpler to define the operators at the Core level, using the `TypeEngine.comparator_factory` attribute. See Redefining and Creating New Operators for more detail.

  See also

  `Comparator`

  `Comparator`

  `Comparator`

  `ColumnOperators`

  Redefining and Creating New Operators

  `TypeEngine.comparator_factory`

  Members

  __eq__(), __le__(), __lt__(), __ne__(), adapt_to_entity(), adapter, all_(), and_(), any(), any_(), asc(), between(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), has(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), like(), match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), of_type(), op(), operate(), regexp_match(), regexp_replace(), reverse_operate(), startswith(), timetuple

  Class signature

  class `sqlalchemy.orm.PropComparator` (`sqlalchemy.sql.expression.ColumnOperators`)

  method `sqlalchemy.orm.PropComparator.`__eq__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__eq__` method of `ColumnOperators`

    Implement the `==` operator.

    In a column context, produces the clause `a = b`. If the target is `None`, produces `a IS NULL`.

  method `sqlalchemy.orm.PropComparator.`__le__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__le__` method of `ColumnOperators`

    Implement the `<=` operator.

    In a column context, produces the clause `a <= b`.

  method `sqlalchemy.orm.PropComparator.`__lt__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__lt__` method of `ColumnOperators`

    Implement the `<` operator.

    In a column context, produces the clause `a < b`.

  method `sqlalchemy.orm.PropComparator.`__ne__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__ne__` method of `ColumnOperators`

    Implement the `!=` operator.

    In a column context, produces the clause `a != b`. If the target is `None`, produces `a IS NOT NULL`.

  method `sqlalchemy.orm.PropComparator.`adapt_to_entity(adapt_to_entity)

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

  attribute `sqlalchemy.orm.PropComparator.`adapter

    Produce a callable that adapts column expressions to suit an aliased version of this comparator.

  method `sqlalchemy.orm.PropComparator.`all_()

    inherited from the `ColumnOperators.all_()` method of `ColumnOperators`

    Produce an `all_()` clause against the parent object.

    See the documentation for `all_()` for examples.

    Note

    be sure to not confuse the newer `ColumnOperators.all_()` method with its older `ARRAY`-specific counterpart, the `Comparator.all()` method, which a different calling syntax and usage pattern.

    Added in version 1.1.

  method `sqlalchemy.orm.PropComparator.`and_(*criteria)

    Add additional criteria to the ON clause that’s represented by this relationship attribute.

    E.g.:

        stmt = select(User).join(
            User.addresses.and_(Address.email_address != 'foo')
        )

        stmt = select(User).options(
            joinedload(User.addresses.and_(Address.email_address != 'foo'))
        )

    Added in version 1.4.

    See also

    Augmenting Built-in ON Clauses

    Adding Criteria to loader options

    `with_loader_criteria()`

  method `sqlalchemy.orm.PropComparator.`any(criterion=None, **kwargs)

    Return true if this collection contains any member that meets the given criterion.

    The usual implementation of `any()` is `Comparator.any()`.

    Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.

      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  method `sqlalchemy.orm.PropComparator.`any_()

    inherited from the `ColumnOperators.any_()` method of `ColumnOperators`

    Produce an `any_()` clause against the parent object.

    See the documentation for `any_()` for examples.

    Note

    be sure to not confuse the newer `ColumnOperators.any_()` method with its older `ARRAY`-specific counterpart, the `Comparator.any()` method, which a different calling syntax and usage pattern.

    Added in version 1.1.

  method `sqlalchemy.orm.PropComparator.`asc()

    inherited from the `ColumnOperators.asc()` method of `ColumnOperators`

    Produce a `asc()` clause against the parent object.

  method `sqlalchemy.orm.PropComparator.`between(cleft, cright, symmetric=False)

    inherited from the `ColumnOperators.between()` method of `ColumnOperators`

    Produce a `between()` clause against the parent object, given the lower and upper range.

  method `sqlalchemy.orm.PropComparator.`bool_op(opstring, precedence=0)

    inherited from the `Operators.bool_op()` method of `Operators`

    Return a custom boolean operator.

    This method is shorthand for calling `Operators.op()` and passing the `Operators.op.is_comparison` flag with True. A key advantage to using `Operators.bool_op()` is that when using column constructs, the “boolean” nature of the returned expression will be present for PEP 484 purposes.

    See also

    `Operators.op()`

  method `sqlalchemy.orm.PropComparator.`collate(collation)

    inherited from the `ColumnOperators.collate()` method of `ColumnOperators`

    Produce a `collate()` clause against the parent object, given the collation string.

    See also

    `collate()`

  method `sqlalchemy.orm.PropComparator.`concat(other)

    inherited from the `ColumnOperators.concat()` method of `ColumnOperators`

    Implement the ‘concat’ operator.

    In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

  method `sqlalchemy.orm.PropComparator.`contains(other, **kwargs)

    inherited from the `ColumnOperators.contains()` method of `ColumnOperators`

    Implement the ‘contains’ operator.

    Produces a LIKE expression that tests against a match for the middle of a string value:

        column LIKE '%' || <other> || '%'

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.contains("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.contains.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.contains.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.contains.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.contains("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE '%' || :param || '%' ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.contains("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE '%' || :param || '%' ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.contains.autoescape`:

            somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.startswith()`

    `ColumnOperators.endswith()`

    `ColumnOperators.like()`

  method `sqlalchemy.orm.PropComparator.`desc()

    inherited from the `ColumnOperators.desc()` method of `ColumnOperators`

    Produce a `desc()` clause against the parent object.

  method `sqlalchemy.orm.PropComparator.`distinct()

    inherited from the `ColumnOperators.distinct()` method of `ColumnOperators`

    Produce a `distinct()` clause against the parent object.

  method `sqlalchemy.orm.PropComparator.`endswith(other, **kwargs)

    inherited from the `ColumnOperators.endswith()` method of `ColumnOperators`

    Implement the ‘endswith’ operator.

    Produces a LIKE expression that tests against a match for the end of a string value:

        column LIKE '%' || <other>

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.endswith("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.endswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.endswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.endswith.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.endswith("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE '%' || :param ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.endswith("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE '%' || :param ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.endswith.autoescape`:

            somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.startswith()`

    `ColumnOperators.contains()`

    `ColumnOperators.like()`

  method `sqlalchemy.orm.PropComparator.`has(criterion=None, **kwargs)

    Return true if this element references a member which meets the given criterion.

    The usual implementation of `has()` is `Comparator.has()`.

    Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.

      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  method `sqlalchemy.orm.PropComparator.`ilike(other, escape=None)

    inherited from the `ColumnOperators.ilike()` method of `ColumnOperators`

    Implement the `ilike` operator, e.g. case insensitive LIKE.

    In a column context, produces an expression either of the form:

        lower(a) LIKE lower(other)

    Or on backends that support the ILIKE operator:

        a ILIKE other

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.ilike("%foobar%"))

    Parameters:

      - other – expression to be compared

      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.ilike("foo/%bar", escape="/")

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.PropComparator.`in_(other)

    inherited from the `ColumnOperators.in_()` method of `ColumnOperators`

    Implement the `in` operator.

    In a column context, produces the clause `column IN <other>`.

    The given parameter `other` may be:

    - A list of literal values, e.g.:

          stmt.where(column.in_([1, 2, 3]))

      In this calling form, the list of items is converted to a set of bound parameters the same length as the list given:

          WHERE COL IN (?, ?, ?)

    - A list of tuples may be provided if the comparison is against a `tuple_()` containing multiple expressions:

          from sqlalchemy import tuple_
          stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

    - An empty list, e.g.:

          stmt.where(column.in_([]))

      In this calling form, the expression renders an “empty set” expression. These expressions are tailored to individual backends and are generally trying to get an empty SELECT statement as a subquery. Such as on SQLite, the expression is:

          WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

      Changed in version 1.4: empty IN expressions now use an execution-time generated SELECT subquery in all cases.

    - A bound parameter, e.g. `bindparam()`, may be used if it includes the `bindparam.expanding` flag:

          stmt.where(column.in_(bindparam('value', expanding=True)))

      In this calling form, the expression renders a special non-SQL placeholder expression that looks like:

          WHERE COL IN ([EXPANDING_value])

      This placeholder expression is intercepted at statement execution time to be converted into the variable number of bound parameter form illustrated earlier. If the statement were executed as:

          connection.execute(stmt, {"value": [1, 2, 3]})

      The database would be passed a bound parameter for each value:

          WHERE COL IN (?, ?, ?)

      Added in version 1.2: added “expanding” bound parameters

      If an empty list is passed, a special “empty list” expression, which is specific to the database in use, is rendered. On SQLite this would be:

          WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

      Added in version 1.3: “expanding” bound parameters now support empty lists

    - a `select()` construct, which is usually a correlated scalar select:

          stmt.where(
              column.in_(
                  select(othertable.c.y).
                  where(table.c.x == othertable.c.x)
              )
          )

      In this calling form, `ColumnOperators.in_()` renders as given:

          WHERE COL IN (SELECT othertable.y
          FROM othertable WHERE othertable.x = table.x)

    Parameters:

      other – a list of literals, a `select()` construct, or a `bindparam()` construct that includes the `bindparam.expanding` flag set to True.

  method `sqlalchemy.orm.PropComparator.`is_(other)

    inherited from the `ColumnOperators.is_()` method of `ColumnOperators`

    Implement the `IS` operator.

    Normally, `IS` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS` may be desirable if comparing to boolean values on certain platforms.

    See also

    `ColumnOperators.is_not()`

  method `sqlalchemy.orm.PropComparator.`is_distinct_from(other)

    inherited from the `ColumnOperators.is_distinct_from()` method of `ColumnOperators`

    Implement the `IS DISTINCT FROM` operator.

    Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.

    Added in version 1.1.

  method `sqlalchemy.orm.PropComparator.`is_not(other)

    inherited from the `ColumnOperators.is_not()` method of `ColumnOperators`

    Implement the `IS NOT` operator.

    Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

    Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.is_()`

  method `sqlalchemy.orm.PropComparator.`is_not_distinct_from(other)

    inherited from the `ColumnOperators.is_not_distinct_from()` method of `ColumnOperators`

    Implement the `IS NOT DISTINCT FROM` operator.

    Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

    Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

    Added in version 1.1.

  method `sqlalchemy.orm.PropComparator.`isnot(other)

    inherited from the `ColumnOperators.isnot()` method of `ColumnOperators`

    Implement the `IS NOT` operator.

    Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

    Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.is_()`

  method `sqlalchemy.orm.PropComparator.`isnot_distinct_from(other)

    inherited from the `ColumnOperators.isnot_distinct_from()` method of `ColumnOperators`

    Implement the `IS NOT DISTINCT FROM` operator.

    Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

    Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

    Added in version 1.1.

  method `sqlalchemy.orm.PropComparator.`like(other, escape=None)

    inherited from the `ColumnOperators.like()` method of `ColumnOperators`

    Implement the `like` operator.

    In a column context, produces the expression:

        a LIKE other

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.like("%foobar%"))

    Parameters:

      - other – expression to be compared

      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.like("foo/%bar", escape="/")

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.PropComparator.`match(other, **kwargs)

    inherited from the `ColumnOperators.match()` method of `ColumnOperators`

    Implements a database-specific ‘match’ operator.

    `ColumnOperators.match()` attempts to resolve to a MATCH-like function or operator provided by the backend. Examples include:

    - PostgreSQL - renders `x @@ to_tsquery(y)`

    - MySQL - renders `MATCH (x) AGAINST (y IN BOOLEAN MODE)`

      See also

      `match` - MySQL specific construct with additional features.

    - Oracle - renders `CONTAINS(x, y)`

    - other backends may provide special implementations.

    - Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.

  method `sqlalchemy.orm.PropComparator.`not_ilike(other, escape=None)

    inherited from the `ColumnOperators.not_ilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.PropComparator.`not_in(other)

    inherited from the `ColumnOperators.not_in()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

    Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

    Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

    See also

    `ColumnOperators.in_()`

  method `sqlalchemy.orm.PropComparator.`not_like(other, escape=None)

    inherited from the `ColumnOperators.not_like()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.PropComparator.`notilike(other, escape=None)

    inherited from the `ColumnOperators.notilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.PropComparator.`notin_(other)

    inherited from the `ColumnOperators.notin_()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

    Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

    Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

    See also

    `ColumnOperators.in_()`

  method `sqlalchemy.orm.PropComparator.`notlike(other, escape=None)

    inherited from the `ColumnOperators.notlike()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.PropComparator.`nulls_first()

    inherited from the `ColumnOperators.nulls_first()` method of `ColumnOperators`

    Produce a `nulls_first()` clause against the parent object.

    Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.PropComparator.`nulls_last()

    inherited from the `ColumnOperators.nulls_last()` method of `ColumnOperators`

    Produce a `nulls_last()` clause against the parent object.

    Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.PropComparator.`nullsfirst()

    inherited from the `ColumnOperators.nullsfirst()` method of `ColumnOperators`

    Produce a `nulls_first()` clause against the parent object.

    Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.PropComparator.`nullslast()

    inherited from the `ColumnOperators.nullslast()` method of `ColumnOperators`

    Produce a `nulls_last()` clause against the parent object.

    Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.PropComparator.`of_type(class_)

    Redefine this object in terms of a polymorphic subclass, `with_polymorphic()` construct, or `aliased()` construct.

    Returns a new PropComparator from which further criterion can be evaluated.

    e.g.:

        query.join(Company.employees.of_type(Engineer)).\
           filter(Engineer.name=='foo')

    Parameters:

      class_ – a class or mapper indicating that criterion will be against this specific subclass.

    See also

    Joins to a Target with an ON Clause - in the ORM Querying Guide

    Referring to specific subtypes on relationships

  method `sqlalchemy.orm.PropComparator.`op(opstring, precedence=0, is_comparison=False, return_type=None)

    inherited from the `Operators.op()` method of `Operators`

    Produce a generic operator function.

    e.g.:

        somecolumn.op("*")(5)

    produces:

        somecolumn * 5

    This function can also be used to make bitwise operators explicit. For example:

        somecolumn.op('&')(0xff)

    is a bitwise AND of the value in `somecolumn`.

    Parameters:

      - operator – a string which will be output as the infix operator between this element and the expression passed to the generated function.

      - precedence –

        precedence which the database is expected to apply to the operator in SQL expressions. This integer value acts as a hint for the SQL compiler to know when explicit parenthesis should be rendered around a particular operation. A lower number will cause the expression to be parenthesized when applied against another operator with higher precedence. The default value of `0` is lower than all operators except for the comma (`,`) and `AS` operators. A value of 100 will be higher or equal to all operators, and -100 will be lower than or equal to all operators.

        See also

        I’m using op() to generate a custom operator and my parenthesis are not coming out correctly - detailed description of how the SQLAlchemy SQL compiler renders parenthesis

      - is_comparison –

        legacy; if True, the operator will be considered as a “comparison” operator, that is which evaluates to a boolean true/false value, like `==`, `>`, etc. This flag is provided so that ORM relationships can establish that the operator is a comparison operator when used in a custom join condition.

        Using the `is_comparison` parameter is superseded by using the `Operators.bool_op()` method instead; this more succinct operator sets this parameter automatically. In SQLAlchemy 2.0 it will also provide for improved typing support.

      - return_type – a `TypeEngine` class or object that will force the return type of an expression produced by this operator to be of that type. By default, operators that specify `Operators.op.is_comparison` will resolve to `Boolean`, and those that do not will be of the same type as the left-hand operand.

    See also

    `Operators.bool_op()`

    Redefining and Creating New Operators

    Using custom operators in join conditions

  method `sqlalchemy.orm.PropComparator.`operate(op, *other, **kwargs)

    inherited from the `Operators.operate()` method of `Operators`

    Operate on an argument.

    This is the lowest level of operation, raises `NotImplementedError` by default.

    Overriding this on a subclass can allow common behavior to be applied to all operations. For example, overriding `ColumnOperators` to apply `func.lower()` to the left and right side:

        class MyComparator(ColumnOperators):
            def operate(self, op, other, **kwargs):
                return op(func.lower(self), func.lower(other), **kwargs)

    Parameters:

      - op – Operator callable.

      - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.

      - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

  method `sqlalchemy.orm.PropComparator.`regexp_match(pattern, flags=None)

    inherited from the `ColumnOperators.regexp_match()` method of `ColumnOperators`

    Implements a database-specific ‘regexp match’ operator.

    E.g.:

        stmt = select(table.c.some_column).where(
            table.c.some_column.regexp_match('^(b|c)')
        )

    `ColumnOperators.regexp_match()` attempts to resolve to a REGEXP-like function or operator provided by the backend, however the specific regular expression syntax and flags available are not backend agnostic.

    Examples include:

    - PostgreSQL - renders `x ~ y` or `x !~ y` when negated.

    - Oracle - renders `REGEXP_LIKE(x, y)`

    - SQLite - uses SQLite’s `REGEXP` placeholder operator and calls into the Python `re.match()` builtin.

    - other backends may provide special implementations.

    - Backends without any special implementation will emit the operator as “REGEXP” or “NOT REGEXP”. This is compatible with SQLite and MySQL, for example.

    Regular expression support is currently implemented for Oracle, PostgreSQL, MySQL and MariaDB. Partial support is available for SQLite. Support among third-party dialects may vary.

    Parameters:

      - pattern – The regular expression pattern string or column clause.

      - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern. When using the ignore case flag ‘i’ in PostgreSQL, the ignore case regexp match operator `~*` or `!~*` will be used.

    Added in version 1.4.

    Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

    See also

    `ColumnOperators.regexp_replace()`

  method `sqlalchemy.orm.PropComparator.`regexp_replace(pattern, replacement, flags=None)

    inherited from the `ColumnOperators.regexp_replace()` method of `ColumnOperators`

    Implements a database-specific ‘regexp replace’ operator.

    E.g.:

        stmt = select(
            table.c.some_column.regexp_replace(
                'b(..)',
                'XY',
                flags='g'
            )
        )

    `ColumnOperators.regexp_replace()` attempts to resolve to a REGEXP_REPLACE-like function provided by the backend, that usually emit the function `REGEXP_REPLACE()`. However, the specific regular expression syntax and flags available are not backend agnostic.

    Regular expression replacement support is currently implemented for Oracle, PostgreSQL, MySQL 8 or greater and MariaDB. Support among third-party dialects may vary.

    Parameters:

      - pattern – The regular expression pattern string or column clause.

      - pattern – The replacement string or column clause.

      - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern.

    Added in version 1.4.

    Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

    See also

    `ColumnOperators.regexp_match()`

  method `sqlalchemy.orm.PropComparator.`reverse_operate(op, other, **kwargs)

    inherited from the `Operators.reverse_operate()` method of `Operators`

    Reverse operate on an argument.

    Usage is the same as `operate()`.

  method `sqlalchemy.orm.PropComparator.`startswith(other, **kwargs)

    inherited from the `ColumnOperators.startswith()` method of `ColumnOperators`

    Implement the `startswith` operator.

    Produces a LIKE expression that tests against a match for the start of a string value:

        column LIKE <other> || '%'

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.startswith("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.startswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.startswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.startswith.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.startswith("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE :param || '%' ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.startswith("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE :param || '%' ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.startswith.autoescape`:

            somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.endswith()`

    `ColumnOperators.contains()`

    `ColumnOperators.like()`

  attribute `sqlalchemy.orm.PropComparator.`timetuple = None

    inherited from the `ColumnOperators.timetuple` attribute of `ColumnOperators`

    Hack, allows datetime objects to be compared on the LHS.

class sqlalchemy.orm.RelationshipProperty(argument, secondary=None, primaryjoin=None, secondaryjoin=None, foreign_keys=None, uselist=None, order_by=False, backref=None, back_populates=None, overlaps=None, post_update=False, cascade=False, viewonly=False, lazy='select', collection_class=None, passive_deletes=False, passive_updates=True, remote_side=None, enable_typechecks=True, join_depth=None, comparator_factory=None, single_parent=False, innerjoin=False, distinct_target_key=None, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, bake_queries=True, _local_remote_pairs=None, query_class=None, info=None, omit_join=None, sync_backref=None, _legacy_inactive_history_style=False)

  Describes an object property that holds a single item or list of items that correspond to a related database table.

  Public constructor is the `relationship()` function.

  See also

  Relationship Configuration

  Members

  __eq__(), __init__(), __le__(), __lt__(), __ne__(), adapt_to_entity(), adapter, all_(), and_(), any(), any_(), asc(), between(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), entity, has(), ilike(), in_(), is_(), is_distinct_from(), is_not(), is_not_distinct_from(), isnot(), isnot_distinct_from(), like(), mapper, match(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), of_type(), op(), operate(), regexp_match(), regexp_replace(), reverse_operate(), startswith(), timetuple, __init__(), cascade, cascade_iterator(), class_attribute, create_row_processor(), do_init(), entity, extension_type, inherit_cache, init(), instrument_class(), is_aliased_class, is_attribute, is_bundle, is_clause_element, is_instance, is_mapper, is_property, is_selectable, mapper, merge(), post_instrument_class(), set_parent(), setup()

  Class signature

  class `sqlalchemy.orm.RelationshipProperty` (`sqlalchemy.orm.StrategizedProperty`)

  class Comparator(prop, parentmapper, adapt_to_entity=None, of_type=None, extra_criteria=())

    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`

    `Comparator`

    `ColumnOperators`

    Redefining and Creating New Operators

    `TypeEngine.comparator_factory`

    Class signature

    class `sqlalchemy.orm.RelationshipProperty.Comparator` (`sqlalchemy.orm.PropComparator`)

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`__eq__(other)

      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 `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 `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.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`__init__(prop, parentmapper, adapt_to_entity=None, of_type=None, extra_criteria=())

      Construction of `Comparator` is internal to the ORM’s attribute mechanics.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`__le__(other)

      inherited from the `sqlalchemy.sql.expression.ColumnOperators.__le__` method of `ColumnOperators`

      Implement the `<=` operator.

      In a column context, produces the clause `a <= b`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`__lt__(other)

      inherited from the `sqlalchemy.sql.expression.ColumnOperators.__lt__` method of `ColumnOperators`

      Implement the `<` operator.

      In a column context, produces the clause `a < b`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`__ne__(other)

      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 `Comparator.contains()` in conjunction with `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 `Comparator.has()` in conjunction with `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.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`adapt_to_entity(adapt_to_entity)

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

    attribute `sqlalchemy.orm.RelationshipProperty.Comparator.`adapter

      inherited from the `PropComparator.adapter` attribute of `PropComparator`

      Produce a callable that adapts column expressions to suit an aliased version of this comparator.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`all_()

      inherited from the `ColumnOperators.all_()` method of `ColumnOperators`

      Produce an `all_()` clause against the parent object.

      See the documentation for `all_()` for examples.

      Note

      be sure to not confuse the newer `ColumnOperators.all_()` method with its older `ARRAY`-specific counterpart, the `Comparator.all()` method, which a different calling syntax and usage pattern.

      Added in version 1.1.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`and_(*other)

      Add AND criteria.

      See `PropComparator.and_()` for an example.

      Added in version 1.4.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`any(criterion=None, **kwargs)

      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 `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.

      `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))

      `Comparator.any()` is only valid for collections, i.e. a `relationship()` that has `uselist=True`. For scalar references, use `Comparator.has()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`any_()

      inherited from the `ColumnOperators.any_()` method of `ColumnOperators`

      Produce an `any_()` clause against the parent object.

      See the documentation for `any_()` for examples.

      Note

      be sure to not confuse the newer `ColumnOperators.any_()` method with its older `ARRAY`-specific counterpart, the `Comparator.any()` method, which a different calling syntax and usage pattern.

      Added in version 1.1.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`asc()

      inherited from the `ColumnOperators.asc()` method of `ColumnOperators`

      Produce a `asc()` clause against the parent object.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`between(cleft, cright, symmetric=False)

      inherited from the `ColumnOperators.between()` method of `ColumnOperators`

      Produce a `between()` clause against the parent object, given the lower and upper range.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`bool_op(opstring, precedence=0)

      inherited from the `Operators.bool_op()` method of `Operators`

      Return a custom boolean operator.

      This method is shorthand for calling `Operators.op()` and passing the `Operators.op.is_comparison` flag with True. A key advantage to using `Operators.bool_op()` is that when using column constructs, the “boolean” nature of the returned expression will be present for PEP 484 purposes.

      See also

      `Operators.op()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`collate(collation)

      inherited from the `ColumnOperators.collate()` method of `ColumnOperators`

      Produce a `collate()` clause against the parent object, given the collation string.

      See also

      `collate()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`concat(other)

      inherited from the `ColumnOperators.concat()` method of `ColumnOperators`

      Implement the ‘concat’ operator.

      In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`contains(other, **kwargs)

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

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

      For many-to-many operations, the behavior of `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 `Comparator.contains()` will not work with many-to-many collections when used in queries that move beyond simple AND conjunctions, such as multiple `Comparator.contains()` expressions joined by OR. In such cases subqueries or explicit “outer joins” will need to be used instead. See `Comparator.any()` for a less-performant alternative using EXISTS, or refer to `Query.outerjoin()` as well as Joins for more details on constructing outer joins.

      kwargs may be ignored by this operator but are required for API conformance.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`desc()

      inherited from the `ColumnOperators.desc()` method of `ColumnOperators`

      Produce a `desc()` clause against the parent object.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`distinct()

      inherited from the `ColumnOperators.distinct()` method of `ColumnOperators`

      Produce a `distinct()` clause against the parent object.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`endswith(other, **kwargs)

      inherited from the `ColumnOperators.endswith()` method of `ColumnOperators`

      Implement the ‘endswith’ operator.

      Produces a LIKE expression that tests against a match for the end of a string value:

          column LIKE '%' || <other>

      E.g.:

          stmt = select(sometable).\
              where(sometable.c.column.endswith("foobar"))

      Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.endswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.endswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

      Parameters:

        - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.endswith.autoescape` flag is set to True.

        - autoescape –

          boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

          An expression such as:

              somecolumn.endswith("foo%bar", autoescape=True)

          Will render as:

              somecolumn LIKE '%' || :param ESCAPE '/'

          With the value of `:param` as `"foo/%bar"`.

        - escape –

          a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

          An expression such as:

              somecolumn.endswith("foo/%bar", escape="^")

          Will render as:

              somecolumn LIKE '%' || :param ESCAPE '^'

          The parameter may also be combined with `ColumnOperators.endswith.autoescape`:

              somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

          Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

      See also

      `ColumnOperators.startswith()`

      `ColumnOperators.contains()`

      `ColumnOperators.like()`

    attribute `sqlalchemy.orm.RelationshipProperty.Comparator.`entity

      The target entity referred to by this `Comparator`.

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

      This is the “target” or “remote” side of the `relationship()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`has(criterion=None, **kwargs)

      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 `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.

      `Comparator.has()` is only valid for scalar references, i.e. a `relationship()` that has `uselist=False`. For collection references, use `Comparator.any()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`ilike(other, escape=None)

      inherited from the `ColumnOperators.ilike()` method of `ColumnOperators`

      Implement the `ilike` operator, e.g. case insensitive LIKE.

      In a column context, produces an expression either of the form:

          lower(a) LIKE lower(other)

      Or on backends that support the ILIKE operator:

          a ILIKE other

      E.g.:

          stmt = select(sometable).\
              where(sometable.c.column.ilike("%foobar%"))

      Parameters:

        - other – expression to be compared

        - escape –

          optional escape character, renders the `ESCAPE` keyword, e.g.:

              somecolumn.ilike("foo/%bar", escape="/")

      See also

      `ColumnOperators.like()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`in_(other)

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

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`is_(other)

      inherited from the `ColumnOperators.is_()` method of `ColumnOperators`

      Implement the `IS` operator.

      Normally, `IS` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS` may be desirable if comparing to boolean values on certain platforms.

      See also

      `ColumnOperators.is_not()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`is_distinct_from(other)

      inherited from the `ColumnOperators.is_distinct_from()` method of `ColumnOperators`

      Implement the `IS DISTINCT FROM` operator.

      Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.

      Added in version 1.1.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`is_not(other)

      inherited from the `ColumnOperators.is_not()` method of `ColumnOperators`

      Implement the `IS NOT` operator.

      Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

      Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.is_()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`is_not_distinct_from(other)

      inherited from the `ColumnOperators.is_not_distinct_from()` method of `ColumnOperators`

      Implement the `IS NOT DISTINCT FROM` operator.

      Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

      Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

      Added in version 1.1.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`isnot(other)

      inherited from the `ColumnOperators.isnot()` method of `ColumnOperators`

      Implement the `IS NOT` operator.

      Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

      Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.is_()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`isnot_distinct_from(other)

      inherited from the `ColumnOperators.isnot_distinct_from()` method of `ColumnOperators`

      Implement the `IS NOT DISTINCT FROM` operator.

      Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

      Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

      Added in version 1.1.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`like(other, escape=None)

      inherited from the `ColumnOperators.like()` method of `ColumnOperators`

      Implement the `like` operator.

      In a column context, produces the expression:

          a LIKE other

      E.g.:

          stmt = select(sometable).\
              where(sometable.c.column.like("%foobar%"))

      Parameters:

        - other – expression to be compared

        - escape –

          optional escape character, renders the `ESCAPE` keyword, e.g.:

              somecolumn.like("foo/%bar", escape="/")

      See also

      `ColumnOperators.ilike()`

    attribute `sqlalchemy.orm.RelationshipProperty.Comparator.`mapper

      The target `Mapper` referred to by this `Comparator`.

      This is the “target” or “remote” side of the `relationship()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`match(other, **kwargs)

      inherited from the `ColumnOperators.match()` method of `ColumnOperators`

      Implements a database-specific ‘match’ operator.

      `ColumnOperators.match()` attempts to resolve to a MATCH-like function or operator provided by the backend. Examples include:

      - PostgreSQL - renders `x @@ to_tsquery(y)`

      - MySQL - renders `MATCH (x) AGAINST (y IN BOOLEAN MODE)`

        See also

        `match` - MySQL specific construct with additional features.

      - Oracle - renders `CONTAINS(x, y)`

      - other backends may provide special implementations.

      - Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`not_ilike(other, escape=None)

      inherited from the `ColumnOperators.not_ilike()` method of `ColumnOperators`

      implement the `NOT ILIKE` operator.

      This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

      Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.ilike()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`not_in(other)

      inherited from the `ColumnOperators.not_in()` method of `ColumnOperators`

      implement the `NOT IN` operator.

      This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

      In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

      Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

      Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

      See also

      `ColumnOperators.in_()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`not_like(other, escape=None)

      inherited from the `ColumnOperators.not_like()` method of `ColumnOperators`

      implement the `NOT LIKE` operator.

      This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

      Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.like()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`notilike(other, escape=None)

      inherited from the `ColumnOperators.notilike()` method of `ColumnOperators`

      implement the `NOT ILIKE` operator.

      This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

      Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.ilike()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`notin_(other)

      inherited from the `ColumnOperators.notin_()` method of `ColumnOperators`

      implement the `NOT IN` operator.

      This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

      In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

      Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

      Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

      See also

      `ColumnOperators.in_()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`notlike(other, escape=None)

      inherited from the `ColumnOperators.notlike()` method of `ColumnOperators`

      implement the `NOT LIKE` operator.

      This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

      Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

      See also

      `ColumnOperators.like()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`nulls_first()

      inherited from the `ColumnOperators.nulls_first()` method of `ColumnOperators`

      Produce a `nulls_first()` clause against the parent object.

      Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`nulls_last()

      inherited from the `ColumnOperators.nulls_last()` method of `ColumnOperators`

      Produce a `nulls_last()` clause against the parent object.

      Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`nullsfirst()

      inherited from the `ColumnOperators.nullsfirst()` method of `ColumnOperators`

      Produce a `nulls_first()` clause against the parent object.

      Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`nullslast()

      inherited from the `ColumnOperators.nullslast()` method of `ColumnOperators`

      Produce a `nulls_last()` clause against the parent object.

      Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`of_type(cls)

      Redefine this object in terms of a polymorphic subclass.

      See `PropComparator.of_type()` for an example.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`op(opstring, precedence=0, is_comparison=False, return_type=None)

      inherited from the `Operators.op()` method of `Operators`

      Produce a generic operator function.

      e.g.:

          somecolumn.op("*")(5)

      produces:

          somecolumn * 5

      This function can also be used to make bitwise operators explicit. For example:

          somecolumn.op('&')(0xff)

      is a bitwise AND of the value in `somecolumn`.

      Parameters:

        - operator – a string which will be output as the infix operator between this element and the expression passed to the generated function.

        - precedence –

          precedence which the database is expected to apply to the operator in SQL expressions. This integer value acts as a hint for the SQL compiler to know when explicit parenthesis should be rendered around a particular operation. A lower number will cause the expression to be parenthesized when applied against another operator with higher precedence. The default value of `0` is lower than all operators except for the comma (`,`) and `AS` operators. A value of 100 will be higher or equal to all operators, and -100 will be lower than or equal to all operators.

          See also

          I’m using op() to generate a custom operator and my parenthesis are not coming out correctly - detailed description of how the SQLAlchemy SQL compiler renders parenthesis

        - is_comparison –

          legacy; if True, the operator will be considered as a “comparison” operator, that is which evaluates to a boolean true/false value, like `==`, `>`, etc. This flag is provided so that ORM relationships can establish that the operator is a comparison operator when used in a custom join condition.

          Using the `is_comparison` parameter is superseded by using the `Operators.bool_op()` method instead; this more succinct operator sets this parameter automatically. In SQLAlchemy 2.0 it will also provide for improved typing support.

        - return_type – a `TypeEngine` class or object that will force the return type of an expression produced by this operator to be of that type. By default, operators that specify `Operators.op.is_comparison` will resolve to `Boolean`, and those that do not will be of the same type as the left-hand operand.

      See also

      `Operators.bool_op()`

      Redefining and Creating New Operators

      Using custom operators in join conditions

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`operate(op, *other, **kwargs)

      inherited from the `Operators.operate()` method of `Operators`

      Operate on an argument.

      This is the lowest level of operation, raises `NotImplementedError` by default.

      Overriding this on a subclass can allow common behavior to be applied to all operations. For example, overriding `ColumnOperators` to apply `func.lower()` to the left and right side:

          class MyComparator(ColumnOperators):
              def operate(self, op, other, **kwargs):
                  return op(func.lower(self), func.lower(other), **kwargs)

      Parameters:

        - op – Operator callable.

        - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.

        - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`regexp_match(pattern, flags=None)

      inherited from the `ColumnOperators.regexp_match()` method of `ColumnOperators`

      Implements a database-specific ‘regexp match’ operator.

      E.g.:

          stmt = select(table.c.some_column).where(
              table.c.some_column.regexp_match('^(b|c)')
          )

      `ColumnOperators.regexp_match()` attempts to resolve to a REGEXP-like function or operator provided by the backend, however the specific regular expression syntax and flags available are not backend agnostic.

      Examples include:

      - PostgreSQL - renders `x ~ y` or `x !~ y` when negated.

      - Oracle - renders `REGEXP_LIKE(x, y)`

      - SQLite - uses SQLite’s `REGEXP` placeholder operator and calls into the Python `re.match()` builtin.

      - other backends may provide special implementations.

      - Backends without any special implementation will emit the operator as “REGEXP” or “NOT REGEXP”. This is compatible with SQLite and MySQL, for example.

      Regular expression support is currently implemented for Oracle, PostgreSQL, MySQL and MariaDB. Partial support is available for SQLite. Support among third-party dialects may vary.

      Parameters:

        - pattern – The regular expression pattern string or column clause.

        - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern. When using the ignore case flag ‘i’ in PostgreSQL, the ignore case regexp match operator `~*` or `!~*` will be used.

      Added in version 1.4.

      Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

      See also

      `ColumnOperators.regexp_replace()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`regexp_replace(pattern, replacement, flags=None)

      inherited from the `ColumnOperators.regexp_replace()` method of `ColumnOperators`

      Implements a database-specific ‘regexp replace’ operator.

      E.g.:

          stmt = select(
              table.c.some_column.regexp_replace(
                  'b(..)',
                  'XY',
                  flags='g'
              )
          )

      `ColumnOperators.regexp_replace()` attempts to resolve to a REGEXP_REPLACE-like function provided by the backend, that usually emit the function `REGEXP_REPLACE()`. However, the specific regular expression syntax and flags available are not backend agnostic.

      Regular expression replacement support is currently implemented for Oracle, PostgreSQL, MySQL 8 or greater and MariaDB. Support among third-party dialects may vary.

      Parameters:

        - pattern – The regular expression pattern string or column clause.

        - pattern – The replacement string or column clause.

        - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern.

      Added in version 1.4.

      Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

      See also

      `ColumnOperators.regexp_match()`

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`reverse_operate(op, other, **kwargs)

      inherited from the `Operators.reverse_operate()` method of `Operators`

      Reverse operate on an argument.

      Usage is the same as `operate()`.

    method `sqlalchemy.orm.RelationshipProperty.Comparator.`startswith(other, **kwargs)

      inherited from the `ColumnOperators.startswith()` method of `ColumnOperators`

      Implement the `startswith` operator.

      Produces a LIKE expression that tests against a match for the start of a string value:

          column LIKE <other> || '%'

      E.g.:

          stmt = select(sometable).\
              where(sometable.c.column.startswith("foobar"))

      Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.startswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.startswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

      Parameters:

        - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.startswith.autoescape` flag is set to True.

        - autoescape –

          boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

          An expression such as:

              somecolumn.startswith("foo%bar", autoescape=True)

          Will render as:

              somecolumn LIKE :param || '%' ESCAPE '/'

          With the value of `:param` as `"foo/%bar"`.

        - escape –

          a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

          An expression such as:

              somecolumn.startswith("foo/%bar", escape="^")

          Will render as:

              somecolumn LIKE :param || '%' ESCAPE '^'

          The parameter may also be combined with `ColumnOperators.startswith.autoescape`:

              somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

          Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

      See also

      `ColumnOperators.endswith()`

      `ColumnOperators.contains()`

      `ColumnOperators.like()`

    attribute `sqlalchemy.orm.RelationshipProperty.Comparator.`timetuple = None

      inherited from the `ColumnOperators.timetuple` attribute of `ColumnOperators`

      Hack, allows datetime objects to be compared on the LHS.

  method `sqlalchemy.orm.RelationshipProperty.`__init__(argument, secondary=None, primaryjoin=None, secondaryjoin=None, foreign_keys=None, uselist=None, order_by=False, backref=None, back_populates=None, overlaps=None, post_update=False, cascade=False, viewonly=False, lazy='select', collection_class=None, passive_deletes=False, passive_updates=True, remote_side=None, enable_typechecks=True, join_depth=None, comparator_factory=None, single_parent=False, innerjoin=False, distinct_target_key=None, doc=None, active_history=False, cascade_backrefs=True, load_on_pending=False, bake_queries=True, _local_remote_pairs=None, query_class=None, info=None, omit_join=None, sync_backref=None, _legacy_inactive_history_style=False)

    Construct a new `RelationshipProperty` object.

    This constructor is mirrored as a public API function; see `sqlalchemy.orm.relationship()` for a full usage and argument description.

  attribute `sqlalchemy.orm.RelationshipProperty.`cascade

    The set of ‘cascade’ attribute names.

    This collection is checked before the ‘cascade_iterator’ method is called.

    The collection typically only applies to a RelationshipProperty.

  method `sqlalchemy.orm.RelationshipProperty.`cascade_iterator(type_, state, dict_, visited_states, halt_on=None)

    Iterate through instances related to the given instance for a particular ‘cascade’, starting with this MapperProperty.

    Return an iterator3-tuples (instance, mapper, state).

    Note that the ‘cascade’ collection on this MapperProperty is checked first for the given type before cascade_iterator is called.

    This method typically only applies to RelationshipProperty.

  attribute `sqlalchemy.orm.RelationshipProperty.`class_attribute

    inherited from the `MapperProperty.class_attribute` attribute of `MapperProperty`

    Return the class-bound descriptor corresponding to this `MapperProperty`.

    This is basically a `getattr()` call:

        return getattr(self.parent.class_, self.key)

    I.e. if this `MapperProperty` were named `addresses`, and the class to which it is mapped is `User`, this sequence is possible:

        >>> from sqlalchemy import inspect
        >>> mapper = inspect(User)
        >>> addresses_property = mapper.attrs.addresses
        >>> addresses_property.class_attribute is User.addresses
        True
        >>> User.addresses.property is addresses_property
        True

  method `sqlalchemy.orm.RelationshipProperty.`create_row_processor(context, query_entity, path, mapper, result, adapter, populators)

    inherited from the `StrategizedProperty.create_row_processor()` method of `StrategizedProperty`

    Produce row processing functions and append to the given set of populators lists.

  method `sqlalchemy.orm.RelationshipProperty.`do_init()

    Perform subclass-specific initialization post-mapper-creation steps.

    This is a template method called by the `MapperProperty` object’s init() method.

  attribute `sqlalchemy.orm.RelationshipProperty.`entity

    Return the target mapped entity, which is an inspect() of the class or aliased class that is referred towards.

  attribute `sqlalchemy.orm.RelationshipProperty.`extension_type = symbol('NOT_EXTENSION')

    inherited from the `InspectionAttr.extension_type` attribute of `InspectionAttr`

    The extension type, if any. Defaults to `NOT_EXTENSION`

    See also

    `HYBRID_METHOD`

    `HYBRID_PROPERTY`

    `ASSOCIATION_PROXY`

  attribute `sqlalchemy.orm.RelationshipProperty.`inherit_cache = True

    Indicate if this `HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass.

    The attribute defaults to `None`, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to `False`, except that a warning is also emitted.

    This flag can be set to `True` on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

    See also

    Enabling Caching Support for Custom Constructs - General guideslines for setting the `HasCacheKey.inherit_cache` attribute for third-party or user defined SQL constructs.

  method `sqlalchemy.orm.RelationshipProperty.`init()

    inherited from the `MapperProperty.init()` method of `MapperProperty`

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  method `sqlalchemy.orm.RelationshipProperty.`instrument_class(mapper)

    Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.

    The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.

    This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.

    The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

  attribute `sqlalchemy.orm.RelationshipProperty.`is_aliased_class = False

    inherited from the `InspectionAttr.is_aliased_class` attribute of `InspectionAttr`

    True if this object is an instance of `AliasedClass`.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_attribute = False

    inherited from the `InspectionAttr.is_attribute` attribute of `InspectionAttr`

    True if this object is a Python descriptor.

    This can refer to one of many types. Usually a `QueryableAttribute` which handles attributes events on behalf of a `MapperProperty`. But can also be an extension type such as `AssociationProxy` or `hybrid_property`. The `InspectionAttr.extension_type` will refer to a constant identifying the specific subtype.

    See also

    `Mapper.all_orm_descriptors`

  attribute `sqlalchemy.orm.RelationshipProperty.`is_bundle = False

    inherited from the `InspectionAttr.is_bundle` attribute of `InspectionAttr`

    True if this object is an instance of `Bundle`.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_clause_element = False

    inherited from the `InspectionAttr.is_clause_element` attribute of `InspectionAttr`

    True if this object is an instance of `ClauseElement`.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_instance = False

    inherited from the `InspectionAttr.is_instance` attribute of `InspectionAttr`

    True if this object is an instance of `InstanceState`.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_mapper = False

    inherited from the `InspectionAttr.is_mapper` attribute of `InspectionAttr`

    True if this object is an instance of `Mapper`.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_property = True

    inherited from the `MapperProperty.is_property` attribute of `MapperProperty`

    Part of the InspectionAttr interface; states this object is a mapper property.

  attribute `sqlalchemy.orm.RelationshipProperty.`is_selectable = False

    inherited from the `InspectionAttr.is_selectable` attribute of `InspectionAttr`

    Return True if this object is an instance of `Selectable`.

  attribute `sqlalchemy.orm.RelationshipProperty.`mapper

    Return the targeted `Mapper` for this `RelationshipProperty`.

    This is a lazy-initializing static attribute.

  method `sqlalchemy.orm.RelationshipProperty.`merge(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)

    Merge the attribute represented by this `MapperProperty` from source to destination object.

  method `sqlalchemy.orm.RelationshipProperty.`post_instrument_class(mapper)

    inherited from the `StrategizedProperty.post_instrument_class()` method of `StrategizedProperty`

    Perform instrumentation adjustments that need to occur after init() has completed.

    The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.

    This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.

  method `sqlalchemy.orm.RelationshipProperty.`set_parent(parent, init)

    inherited from the `MapperProperty.set_parent()` method of `MapperProperty`

    Set the parent mapper that references this MapperProperty.

    This method is overridden by some subclasses to perform extra setup when the mapper is first known.

  method `sqlalchemy.orm.RelationshipProperty.`setup(context, query_entity, path, adapter, **kwargs)

    inherited from the `StrategizedProperty.setup()` method of `StrategizedProperty`

    Called by Query for the purposes of constructing a SQL statement.

    Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate.

class sqlalchemy.orm.SynonymProperty(name, map_column=None, descriptor=None, comparator_factory=None, doc=None, info=None)

  Members

  __init__(), cascade, cascade_iterator(), class_attribute, create_row_processor(), do_init(), extension_type, inherit_cache, init(), instrument_class(), is_aliased_class, is_attribute, is_bundle, is_clause_element, is_instance, is_mapper, is_property, is_selectable, merge(), post_instrument_class(), set_parent(), setup(), uses_objects

  Class signature

  class `sqlalchemy.orm.SynonymProperty` (`sqlalchemy.orm.descriptor_props.DescriptorProperty`)

  method `sqlalchemy.orm.SynonymProperty.`__init__(name, map_column=None, descriptor=None, comparator_factory=None, doc=None, info=None)

    Construct a new `SynonymProperty` object.

    This constructor is mirrored as a public API function; see `sqlalchemy.orm.synonym()` for a full usage and argument description.

  attribute `sqlalchemy.orm.SynonymProperty.`cascade = frozenset({})

    inherited from the `MapperProperty.cascade` attribute of `MapperProperty`

    The set of ‘cascade’ attribute names.

    This collection is checked before the ‘cascade_iterator’ method is called.

    The collection typically only applies to a RelationshipProperty.

  method `sqlalchemy.orm.SynonymProperty.`cascade_iterator(type_, state, dict_, visited_states, halt_on=None)

    inherited from the `MapperProperty.cascade_iterator()` method of `MapperProperty`

    Iterate through instances related to the given instance for a particular ‘cascade’, starting with this MapperProperty.

    Return an iterator3-tuples (instance, mapper, state).

    Note that the ‘cascade’ collection on this MapperProperty is checked first for the given type before cascade_iterator is called.

    This method typically only applies to RelationshipProperty.

  attribute `sqlalchemy.orm.SynonymProperty.`class_attribute

    inherited from the `MapperProperty.class_attribute` attribute of `MapperProperty`

    Return the class-bound descriptor corresponding to this `MapperProperty`.

    This is basically a `getattr()` call:

        return getattr(self.parent.class_, self.key)

    I.e. if this `MapperProperty` were named `addresses`, and the class to which it is mapped is `User`, this sequence is possible:

        >>> from sqlalchemy import inspect
        >>> mapper = inspect(User)
        >>> addresses_property = mapper.attrs.addresses
        >>> addresses_property.class_attribute is User.addresses
        True
        >>> User.addresses.property is addresses_property
        True

  method `sqlalchemy.orm.SynonymProperty.`create_row_processor(context, query_entity, path, mapper, result, adapter, populators)

    inherited from the `MapperProperty.create_row_processor()` method of `MapperProperty`

    Produce row processing functions and append to the given set of populators lists.

  method `sqlalchemy.orm.SynonymProperty.`do_init()

    inherited from the `MapperProperty.do_init()` method of `MapperProperty`

    Perform subclass-specific initialization post-mapper-creation steps.

    This is a template method called by the `MapperProperty` object’s init() method.

  attribute `sqlalchemy.orm.SynonymProperty.`extension_type = symbol('NOT_EXTENSION')

    inherited from the `InspectionAttr.extension_type` attribute of `InspectionAttr`

    The extension type, if any. Defaults to `NOT_EXTENSION`

    See also

    `HYBRID_METHOD`

    `HYBRID_PROPERTY`

    `ASSOCIATION_PROXY`

  attribute `sqlalchemy.orm.SynonymProperty.`inherit_cache = None

    inherited from the `HasCacheKey.inherit_cache` attribute of `HasCacheKey`

    Indicate if this `HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass.

    The attribute defaults to `None`, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to `False`, except that a warning is also emitted.

    This flag can be set to `True` on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

    See also

    Enabling Caching Support for Custom Constructs - General guideslines for setting the `HasCacheKey.inherit_cache` attribute for third-party or user defined SQL constructs.

  method `sqlalchemy.orm.SynonymProperty.`init()

    inherited from the `MapperProperty.init()` method of `MapperProperty`

    Called after all mappers are created to assemble relationships between mappers and perform other post-mapper-creation initialization steps.

  method `sqlalchemy.orm.SynonymProperty.`instrument_class(mapper)

    inherited from the `DescriptorProperty.instrument_class()` method of `DescriptorProperty`

    Hook called by the Mapper to the property to initiate instrumentation of the class attribute managed by this MapperProperty.

    The MapperProperty here will typically call out to the attributes module to set up an InstrumentedAttribute.

    This step is the first of two steps to set up an InstrumentedAttribute, and is called early in the mapper setup process.

    The second step is typically the init_class_attribute step, called from StrategizedProperty via the post_instrument_class() hook. This step assigns additional state to the InstrumentedAttribute (specifically the “impl”) which has been determined after the MapperProperty has determined what kind of persistence management it needs to do (e.g. scalar, object, collection, etc).

  attribute `sqlalchemy.orm.SynonymProperty.`is_aliased_class = False

    inherited from the `InspectionAttr.is_aliased_class` attribute of `InspectionAttr`

    True if this object is an instance of `AliasedClass`.

  attribute `sqlalchemy.orm.SynonymProperty.`is_attribute = False

    inherited from the `InspectionAttr.is_attribute` attribute of `InspectionAttr`

    True if this object is a Python descriptor.

    This can refer to one of many types. Usually a `QueryableAttribute` which handles attributes events on behalf of a `MapperProperty`. But can also be an extension type such as `AssociationProxy` or `hybrid_property`. The `InspectionAttr.extension_type` will refer to a constant identifying the specific subtype.

    See also

    `Mapper.all_orm_descriptors`

  attribute `sqlalchemy.orm.SynonymProperty.`is_bundle = False

    inherited from the `InspectionAttr.is_bundle` attribute of `InspectionAttr`

    True if this object is an instance of `Bundle`.

  attribute `sqlalchemy.orm.SynonymProperty.`is_clause_element = False

    inherited from the `InspectionAttr.is_clause_element` attribute of `InspectionAttr`

    True if this object is an instance of `ClauseElement`.

  attribute `sqlalchemy.orm.SynonymProperty.`is_instance = False

    inherited from the `InspectionAttr.is_instance` attribute of `InspectionAttr`

    True if this object is an instance of `InstanceState`.

  attribute `sqlalchemy.orm.SynonymProperty.`is_mapper = False

    inherited from the `InspectionAttr.is_mapper` attribute of `InspectionAttr`

    True if this object is an instance of `Mapper`.

  attribute `sqlalchemy.orm.SynonymProperty.`is_property = True

    inherited from the `MapperProperty.is_property` attribute of `MapperProperty`

    Part of the InspectionAttr interface; states this object is a mapper property.

  attribute `sqlalchemy.orm.SynonymProperty.`is_selectable = False

    inherited from the `InspectionAttr.is_selectable` attribute of `InspectionAttr`

    Return True if this object is an instance of `Selectable`.

  method `sqlalchemy.orm.SynonymProperty.`merge(session, source_state, source_dict, dest_state, dest_dict, load, _recursive, _resolve_conflict_map)

    inherited from the `MapperProperty.merge()` method of `MapperProperty`

    Merge the attribute represented by this `MapperProperty` from source to destination object.

  method `sqlalchemy.orm.SynonymProperty.`post_instrument_class(mapper)

    inherited from the `MapperProperty.post_instrument_class()` method of `MapperProperty`

    Perform instrumentation adjustments that need to occur after init() has completed.

    The given Mapper is the Mapper invoking the operation, which may not be the same Mapper as self.parent in an inheritance scenario; however, Mapper will always at least be a sub-mapper of self.parent.

    This method is typically used by StrategizedProperty, which delegates it to LoaderStrategy.init_class_attribute() to perform final setup on the class-bound InstrumentedAttribute.

  method `sqlalchemy.orm.SynonymProperty.`set_parent(parent, init)

    Set the parent mapper that references this MapperProperty.

    This method is overridden by some subclasses to perform extra setup when the mapper is first known.

  method `sqlalchemy.orm.SynonymProperty.`setup(context, query_entity, path, adapter, **kwargs)

    inherited from the `MapperProperty.setup()` method of `MapperProperty`

    Called by Query for the purposes of constructing a SQL statement.

    Each MapperProperty associated with the target mapper processes the statement referenced by the query context, adding columns and/or criterion as appropriate.

  attribute `sqlalchemy.orm.SynonymProperty.`uses_objects

class sqlalchemy.orm.QueryContext(compile_state, statement, params, session, load_options, execution_options=None, bind_arguments=None)
  class default_load_options(**kw)

    Class signature

    class `sqlalchemy.orm.QueryContext.default_load_options` (`sqlalchemy.sql.expression.Options`)

class sqlalchemy.orm.QueryableAttribute(class_, key, parententity, impl=None, comparator=None, of_type=None, extra_criteria=())

  Base class for descriptor objects that intercept attribute events on behalf of a `MapperProperty` object. The actual `MapperProperty` is accessible via the `QueryableAttribute.property` attribute.

  See also

  `InstrumentedAttribute`

  `MapperProperty`

  `Mapper.all_orm_descriptors`

  `Mapper.attrs`

  Members

  __eq__(), __le__(), __lt__(), __ne__(), adapt_to_entity(), adapter, all_(), and_(), any(), any_(), asc(), between(), bool_op(), collate(), concat(), contains(), desc(), distinct(), endswith(), expression, extension_type, has(), ilike(), in_(), info, inherit_cache, is_(), is_aliased_class, is_attribute, is_bundle, is_clause_element, is_distinct_from(), is_instance, is_mapper, is_not(), is_not_distinct_from(), is_property, is_selectable, isnot(), isnot_distinct_from(), like(), match(), memoized_instancemethod(), not_ilike(), not_in(), not_like(), notilike(), notin_(), notlike(), nulls_first(), nulls_last(), nullsfirst(), nullslast(), of_type(), op(), operate(), parent, property, regexp_match(), regexp_replace(), reverse_operate(), startswith(), timetuple

  Class signature

  class `sqlalchemy.orm.QueryableAttribute` (`sqlalchemy.orm.base._MappedAttribute`, `sqlalchemy.orm.base.InspectionAttr`, `sqlalchemy.orm.PropComparator`, `sqlalchemy.sql.traversals.HasCopyInternals`, `sqlalchemy.sql.roles.JoinTargetRole`, `sqlalchemy.sql.roles.OnClauseRole`, `sqlalchemy.sql.expression.Immutable`, `sqlalchemy.sql.traversals.MemoizedHasCacheKey`)

  method `sqlalchemy.orm.QueryableAttribute.`__eq__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__eq__` method of `ColumnOperators`

    Implement the `==` operator.

    In a column context, produces the clause `a = b`. If the target is `None`, produces `a IS NULL`.

  method `sqlalchemy.orm.QueryableAttribute.`__le__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__le__` method of `ColumnOperators`

    Implement the `<=` operator.

    In a column context, produces the clause `a <= b`.

  method `sqlalchemy.orm.QueryableAttribute.`__lt__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__lt__` method of `ColumnOperators`

    Implement the `<` operator.

    In a column context, produces the clause `a < b`.

  method `sqlalchemy.orm.QueryableAttribute.`__ne__(other)

    inherited from the `sqlalchemy.sql.expression.ColumnOperators.__ne__` method of `ColumnOperators`

    Implement the `!=` operator.

    In a column context, produces the clause `a != b`. If the target is `None`, produces `a IS NOT NULL`.

  method `sqlalchemy.orm.QueryableAttribute.`adapt_to_entity(adapt_to_entity)

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

  attribute `sqlalchemy.orm.QueryableAttribute.`adapter

    inherited from the `PropComparator.adapter` attribute of `PropComparator`

    Produce a callable that adapts column expressions to suit an aliased version of this comparator.

  method `sqlalchemy.orm.QueryableAttribute.`all_()

    inherited from the `ColumnOperators.all_()` method of `ColumnOperators`

    Produce an `all_()` clause against the parent object.

    See the documentation for `all_()` for examples.

    Note

    be sure to not confuse the newer `ColumnOperators.all_()` method with its older `ARRAY`-specific counterpart, the `Comparator.all()` method, which a different calling syntax and usage pattern.

    Added in version 1.1.

  method `sqlalchemy.orm.QueryableAttribute.`and_(*other)

    Add additional criteria to the ON clause that’s represented by this relationship attribute.

    E.g.:

        stmt = select(User).join(
            User.addresses.and_(Address.email_address != 'foo')
        )

        stmt = select(User).options(
            joinedload(User.addresses.and_(Address.email_address != 'foo'))
        )

    Added in version 1.4.

    See also

    Augmenting Built-in ON Clauses

    Adding Criteria to loader options

    `with_loader_criteria()`

  method `sqlalchemy.orm.QueryableAttribute.`any(criterion=None, **kwargs)

    inherited from the `PropComparator.any()` method of `PropComparator`

    Return true if this collection contains any member that meets the given criterion.

    The usual implementation of `any()` is `Comparator.any()`.

    Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.

      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  method `sqlalchemy.orm.QueryableAttribute.`any_()

    inherited from the `ColumnOperators.any_()` method of `ColumnOperators`

    Produce an `any_()` clause against the parent object.

    See the documentation for `any_()` for examples.

    Note

    be sure to not confuse the newer `ColumnOperators.any_()` method with its older `ARRAY`-specific counterpart, the `Comparator.any()` method, which a different calling syntax and usage pattern.

    Added in version 1.1.

  method `sqlalchemy.orm.QueryableAttribute.`asc()

    inherited from the `ColumnOperators.asc()` method of `ColumnOperators`

    Produce a `asc()` clause against the parent object.

  method `sqlalchemy.orm.QueryableAttribute.`between(cleft, cright, symmetric=False)

    inherited from the `ColumnOperators.between()` method of `ColumnOperators`

    Produce a `between()` clause against the parent object, given the lower and upper range.

  method `sqlalchemy.orm.QueryableAttribute.`bool_op(opstring, precedence=0)

    inherited from the `Operators.bool_op()` method of `Operators`

    Return a custom boolean operator.

    This method is shorthand for calling `Operators.op()` and passing the `Operators.op.is_comparison` flag with True. A key advantage to using `Operators.bool_op()` is that when using column constructs, the “boolean” nature of the returned expression will be present for PEP 484 purposes.

    See also

    `Operators.op()`

  method `sqlalchemy.orm.QueryableAttribute.`collate(collation)

    inherited from the `ColumnOperators.collate()` method of `ColumnOperators`

    Produce a `collate()` clause against the parent object, given the collation string.

    See also

    `collate()`

  method `sqlalchemy.orm.QueryableAttribute.`concat(other)

    inherited from the `ColumnOperators.concat()` method of `ColumnOperators`

    Implement the ‘concat’ operator.

    In a column context, produces the clause `a || b`, or uses the `concat()` operator on MySQL.

  method `sqlalchemy.orm.QueryableAttribute.`contains(other, **kwargs)

    inherited from the `ColumnOperators.contains()` method of `ColumnOperators`

    Implement the ‘contains’ operator.

    Produces a LIKE expression that tests against a match for the middle of a string value:

        column LIKE '%' || <other> || '%'

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.contains("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.contains.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.contains.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.contains.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.contains("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE '%' || :param || '%' ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.contains("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE '%' || :param || '%' ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.contains.autoescape`:

            somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.startswith()`

    `ColumnOperators.endswith()`

    `ColumnOperators.like()`

  method `sqlalchemy.orm.QueryableAttribute.`desc()

    inherited from the `ColumnOperators.desc()` method of `ColumnOperators`

    Produce a `desc()` clause against the parent object.

  method `sqlalchemy.orm.QueryableAttribute.`distinct()

    inherited from the `ColumnOperators.distinct()` method of `ColumnOperators`

    Produce a `distinct()` clause against the parent object.

  method `sqlalchemy.orm.QueryableAttribute.`endswith(other, **kwargs)

    inherited from the `ColumnOperators.endswith()` method of `ColumnOperators`

    Implement the ‘endswith’ operator.

    Produces a LIKE expression that tests against a match for the end of a string value:

        column LIKE '%' || <other>

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.endswith("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.endswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.endswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.endswith.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.endswith("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE '%' || :param ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.endswith("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE '%' || :param ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.endswith.autoescape`:

            somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.startswith()`

    `ColumnOperators.contains()`

    `ColumnOperators.like()`

  attribute `sqlalchemy.orm.QueryableAttribute.`expression

    The SQL expression object represented by this `QueryableAttribute`.

    This will typically be an instance of a `ColumnElement` subclass representing a column expression.

  attribute `sqlalchemy.orm.QueryableAttribute.`extension_type = symbol('NOT_EXTENSION')

    inherited from the `InspectionAttr.extension_type` attribute of `InspectionAttr`

    The extension type, if any. Defaults to `NOT_EXTENSION`

    See also

    `HYBRID_METHOD`

    `HYBRID_PROPERTY`

    `ASSOCIATION_PROXY`

  method `sqlalchemy.orm.QueryableAttribute.`has(criterion=None, **kwargs)

    inherited from the `PropComparator.has()` method of `PropComparator`

    Return true if this element references a member which meets the given criterion.

    The usual implementation of `has()` is `Comparator.has()`.

    Parameters:

      - criterion – an optional ClauseElement formulated against the member class’ table or attributes.

      - **kwargs – key/value pairs corresponding to member class attribute names which will be compared via equality to the corresponding values.

  method `sqlalchemy.orm.QueryableAttribute.`ilike(other, escape=None)

    inherited from the `ColumnOperators.ilike()` method of `ColumnOperators`

    Implement the `ilike` operator, e.g. case insensitive LIKE.

    In a column context, produces an expression either of the form:

        lower(a) LIKE lower(other)

    Or on backends that support the ILIKE operator:

        a ILIKE other

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.ilike("%foobar%"))

    Parameters:

      - other – expression to be compared

      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.ilike("foo/%bar", escape="/")

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.QueryableAttribute.`in_(other)

    inherited from the `ColumnOperators.in_()` method of `ColumnOperators`

    Implement the `in` operator.

    In a column context, produces the clause `column IN <other>`.

    The given parameter `other` may be:

    - A list of literal values, e.g.:

          stmt.where(column.in_([1, 2, 3]))

      In this calling form, the list of items is converted to a set of bound parameters the same length as the list given:

          WHERE COL IN (?, ?, ?)

    - A list of tuples may be provided if the comparison is against a `tuple_()` containing multiple expressions:

          from sqlalchemy import tuple_
          stmt.where(tuple_(col1, col2).in_([(1, 10), (2, 20), (3, 30)]))

    - An empty list, e.g.:

          stmt.where(column.in_([]))

      In this calling form, the expression renders an “empty set” expression. These expressions are tailored to individual backends and are generally trying to get an empty SELECT statement as a subquery. Such as on SQLite, the expression is:

          WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

      Changed in version 1.4: empty IN expressions now use an execution-time generated SELECT subquery in all cases.

    - A bound parameter, e.g. `bindparam()`, may be used if it includes the `bindparam.expanding` flag:

          stmt.where(column.in_(bindparam('value', expanding=True)))

      In this calling form, the expression renders a special non-SQL placeholder expression that looks like:

          WHERE COL IN ([EXPANDING_value])

      This placeholder expression is intercepted at statement execution time to be converted into the variable number of bound parameter form illustrated earlier. If the statement were executed as:

          connection.execute(stmt, {"value": [1, 2, 3]})

      The database would be passed a bound parameter for each value:

          WHERE COL IN (?, ?, ?)

      Added in version 1.2: added “expanding” bound parameters

      If an empty list is passed, a special “empty list” expression, which is specific to the database in use, is rendered. On SQLite this would be:

          WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)

      Added in version 1.3: “expanding” bound parameters now support empty lists

    - a `select()` construct, which is usually a correlated scalar select:

          stmt.where(
              column.in_(
                  select(othertable.c.y).
                  where(table.c.x == othertable.c.x)
              )
          )

      In this calling form, `ColumnOperators.in_()` renders as given:

          WHERE COL IN (SELECT othertable.y
          FROM othertable WHERE othertable.x = table.x)

    Parameters:

      other – a list of literals, a `select()` construct, or a `bindparam()` construct that includes the `bindparam.expanding` flag set to True.

  attribute `sqlalchemy.orm.QueryableAttribute.`info

    Return the ‘info’ dictionary for the underlying SQL element.

    The behavior here is as follows:

    - If the attribute is a column-mapped property, i.e. `ColumnProperty`, which is mapped directly to a schema-level `Column` object, this attribute will return the `SchemaItem.info` dictionary associated with the core-level `Column` object.

    - If the attribute is a `ColumnProperty` but is mapped to any other kind of SQL expression other than a `Column`, the attribute will refer to the `MapperProperty.info` dictionary associated directly with the `ColumnProperty`, assuming the SQL expression itself does not have its own `.info` attribute (which should be the case, unless a user-defined SQL construct has defined one).

    - If the attribute refers to any other kind of `MapperProperty`, including `RelationshipProperty`, the attribute will refer to the `MapperProperty.info` dictionary associated with that `MapperProperty`.

    - To access the `MapperProperty.info` dictionary of the `MapperProperty` unconditionally, including for a `ColumnProperty` that’s associated directly with a `Column`, the attribute can be referred to using `QueryableAttribute.property` attribute, as `MyClass.someattribute.property.info`.

    See also

    `SchemaItem.info`

    `MapperProperty.info`

  attribute `sqlalchemy.orm.QueryableAttribute.`inherit_cache = None

    inherited from the `HasCacheKey.inherit_cache` attribute of `HasCacheKey`

    Indicate if this `HasCacheKey` instance should make use of the cache key generation scheme used by its immediate superclass.

    The attribute defaults to `None`, which indicates that a construct has not yet taken into account whether or not its appropriate for it to participate in caching; this is functionally equivalent to setting the value to `False`, except that a warning is also emitted.

    This flag can be set to `True` on a particular class, if the SQL that corresponds to the object does not change based on attributes which are local to this class, and not its superclass.

    See also

    Enabling Caching Support for Custom Constructs - General guideslines for setting the `HasCacheKey.inherit_cache` attribute for third-party or user defined SQL constructs.

  method `sqlalchemy.orm.QueryableAttribute.`is_(other)

    inherited from the `ColumnOperators.is_()` method of `ColumnOperators`

    Implement the `IS` operator.

    Normally, `IS` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS` may be desirable if comparing to boolean values on certain platforms.

    See also

    `ColumnOperators.is_not()`

  attribute `sqlalchemy.orm.QueryableAttribute.`is_aliased_class = False

    inherited from the `InspectionAttr.is_aliased_class` attribute of `InspectionAttr`

    True if this object is an instance of `AliasedClass`.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_attribute = True

    True if this object is a Python descriptor.

    This can refer to one of many types. Usually a `QueryableAttribute` which handles attributes events on behalf of a `MapperProperty`. But can also be an extension type such as `AssociationProxy` or `hybrid_property`. The `InspectionAttr.extension_type` will refer to a constant identifying the specific subtype.

    See also

    `Mapper.all_orm_descriptors`

  attribute `sqlalchemy.orm.QueryableAttribute.`is_bundle = False

    inherited from the `InspectionAttr.is_bundle` attribute of `InspectionAttr`

    True if this object is an instance of `Bundle`.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_clause_element = False

    inherited from the `InspectionAttr.is_clause_element` attribute of `InspectionAttr`

    True if this object is an instance of `ClauseElement`.

  method `sqlalchemy.orm.QueryableAttribute.`is_distinct_from(other)

    inherited from the `ColumnOperators.is_distinct_from()` method of `ColumnOperators`

    Implement the `IS DISTINCT FROM` operator.

    Renders “a IS DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS NOT b”.

    Added in version 1.1.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_instance = False

    inherited from the `InspectionAttr.is_instance` attribute of `InspectionAttr`

    True if this object is an instance of `InstanceState`.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_mapper = False

    inherited from the `InspectionAttr.is_mapper` attribute of `InspectionAttr`

    True if this object is an instance of `Mapper`.

  method `sqlalchemy.orm.QueryableAttribute.`is_not(other)

    inherited from the `ColumnOperators.is_not()` method of `ColumnOperators`

    Implement the `IS NOT` operator.

    Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

    Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.is_()`

  method `sqlalchemy.orm.QueryableAttribute.`is_not_distinct_from(other)

    inherited from the `ColumnOperators.is_not_distinct_from()` method of `ColumnOperators`

    Implement the `IS NOT DISTINCT FROM` operator.

    Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

    Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

    Added in version 1.1.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_property = False

    inherited from the `InspectionAttr.is_property` attribute of `InspectionAttr`

    True if this object is an instance of `MapperProperty`.

  attribute `sqlalchemy.orm.QueryableAttribute.`is_selectable = False

    inherited from the `InspectionAttr.is_selectable` attribute of `InspectionAttr`

    Return True if this object is an instance of `Selectable`.

  method `sqlalchemy.orm.QueryableAttribute.`isnot(other)

    inherited from the `ColumnOperators.isnot()` method of `ColumnOperators`

    Implement the `IS NOT` operator.

    Normally, `IS NOT` is generated automatically when comparing to a value of `None`, which resolves to `NULL`. However, explicit usage of `IS NOT` may be desirable if comparing to boolean values on certain platforms.

    Changed in version 1.4: The `is_not()` operator is renamed from `isnot()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.is_()`

  method `sqlalchemy.orm.QueryableAttribute.`isnot_distinct_from(other)

    inherited from the `ColumnOperators.isnot_distinct_from()` method of `ColumnOperators`

    Implement the `IS NOT DISTINCT FROM` operator.

    Renders “a IS NOT DISTINCT FROM b” on most platforms; on some such as SQLite may render “a IS b”.

    Changed in version 1.4: The `is_not_distinct_from()` operator is renamed from `isnot_distinct_from()` in previous releases. The previous name remains available for backwards compatibility.

    Added in version 1.1.

  method `sqlalchemy.orm.QueryableAttribute.`like(other, escape=None)

    inherited from the `ColumnOperators.like()` method of `ColumnOperators`

    Implement the `like` operator.

    In a column context, produces the expression:

        a LIKE other

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.like("%foobar%"))

    Parameters:

      - other – expression to be compared

      - escape –

        optional escape character, renders the `ESCAPE` keyword, e.g.:

            somecolumn.like("foo/%bar", escape="/")

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.QueryableAttribute.`match(other, **kwargs)

    inherited from the `ColumnOperators.match()` method of `ColumnOperators`

    Implements a database-specific ‘match’ operator.

    `ColumnOperators.match()` attempts to resolve to a MATCH-like function or operator provided by the backend. Examples include:

    - PostgreSQL - renders `x @@ to_tsquery(y)`

    - MySQL - renders `MATCH (x) AGAINST (y IN BOOLEAN MODE)`

      See also

      `match` - MySQL specific construct with additional features.

    - Oracle - renders `CONTAINS(x, y)`

    - other backends may provide special implementations.

    - Backends without any special implementation will emit the operator as “MATCH”. This is compatible with SQLite, for example.

  classmethod `sqlalchemy.orm.QueryableAttribute.`memoized_instancemethod(fn)

    inherited from the `HasMemoized.memoized_instancemethod()` method of `HasMemoized`

    Decorate a method memoize its return value.

  method `sqlalchemy.orm.QueryableAttribute.`not_ilike(other, escape=None)

    inherited from the `ColumnOperators.not_ilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.QueryableAttribute.`not_in(other)

    inherited from the `ColumnOperators.not_in()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

    Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

    Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

    See also

    `ColumnOperators.in_()`

  method `sqlalchemy.orm.QueryableAttribute.`not_like(other, escape=None)

    inherited from the `ColumnOperators.not_like()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.QueryableAttribute.`notilike(other, escape=None)

    inherited from the `ColumnOperators.notilike()` method of `ColumnOperators`

    implement the `NOT ILIKE` operator.

    This is equivalent to using negation with `ColumnOperators.ilike()`, i.e. `~x.ilike(y)`.

    Changed in version 1.4: The `not_ilike()` operator is renamed from `notilike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.ilike()`

  method `sqlalchemy.orm.QueryableAttribute.`notin_(other)

    inherited from the `ColumnOperators.notin_()` method of `ColumnOperators`

    implement the `NOT IN` operator.

    This is equivalent to using negation with `ColumnOperators.in_()`, i.e. `~x.in_(y)`.

    In the case that `other` is an empty sequence, the compiler produces an “empty not in” expression. This defaults to the expression “1 = 1” to produce true in all cases. The `create_engine.empty_in_strategy` may be used to alter this behavior.

    Changed in version 1.4: The `not_in()` operator is renamed from `notin_()` in previous releases. The previous name remains available for backwards compatibility.

    Changed in version 1.2: The `ColumnOperators.in_()` and `ColumnOperators.not_in()` operators now produce a “static” expression for an empty IN sequence by default.

    See also

    `ColumnOperators.in_()`

  method `sqlalchemy.orm.QueryableAttribute.`notlike(other, escape=None)

    inherited from the `ColumnOperators.notlike()` method of `ColumnOperators`

    implement the `NOT LIKE` operator.

    This is equivalent to using negation with `ColumnOperators.like()`, i.e. `~x.like(y)`.

    Changed in version 1.4: The `not_like()` operator is renamed from `notlike()` in previous releases. The previous name remains available for backwards compatibility.

    See also

    `ColumnOperators.like()`

  method `sqlalchemy.orm.QueryableAttribute.`nulls_first()

    inherited from the `ColumnOperators.nulls_first()` method of `ColumnOperators`

    Produce a `nulls_first()` clause against the parent object.

    Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.QueryableAttribute.`nulls_last()

    inherited from the `ColumnOperators.nulls_last()` method of `ColumnOperators`

    Produce a `nulls_last()` clause against the parent object.

    Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.QueryableAttribute.`nullsfirst()

    inherited from the `ColumnOperators.nullsfirst()` method of `ColumnOperators`

    Produce a `nulls_first()` clause against the parent object.

    Changed in version 1.4: The `nulls_first()` operator is renamed from `nullsfirst()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.QueryableAttribute.`nullslast()

    inherited from the `ColumnOperators.nullslast()` method of `ColumnOperators`

    Produce a `nulls_last()` clause against the parent object.

    Changed in version 1.4: The `nulls_last()` operator is renamed from `nullslast()` in previous releases. The previous name remains available for backwards compatibility.

  method `sqlalchemy.orm.QueryableAttribute.`of_type(entity)

    Redefine this object in terms of a polymorphic subclass, `with_polymorphic()` construct, or `aliased()` construct.

    Returns a new PropComparator from which further criterion can be evaluated.

    e.g.:

        query.join(Company.employees.of_type(Engineer)).\
           filter(Engineer.name=='foo')

    Parameters:

      class_ – a class or mapper indicating that criterion will be against this specific subclass.

    See also

    Joins to a Target with an ON Clause - in the ORM Querying Guide

    Referring to specific subtypes on relationships

  method `sqlalchemy.orm.QueryableAttribute.`op(opstring, precedence=0, is_comparison=False, return_type=None)

    inherited from the `Operators.op()` method of `Operators`

    Produce a generic operator function.

    e.g.:

        somecolumn.op("*")(5)

    produces:

        somecolumn * 5

    This function can also be used to make bitwise operators explicit. For example:

        somecolumn.op('&')(0xff)

    is a bitwise AND of the value in `somecolumn`.

    Parameters:

      - operator – a string which will be output as the infix operator between this element and the expression passed to the generated function.

      - precedence –

        precedence which the database is expected to apply to the operator in SQL expressions. This integer value acts as a hint for the SQL compiler to know when explicit parenthesis should be rendered around a particular operation. A lower number will cause the expression to be parenthesized when applied against another operator with higher precedence. The default value of `0` is lower than all operators except for the comma (`,`) and `AS` operators. A value of 100 will be higher or equal to all operators, and -100 will be lower than or equal to all operators.

        See also

        I’m using op() to generate a custom operator and my parenthesis are not coming out correctly - detailed description of how the SQLAlchemy SQL compiler renders parenthesis

      - is_comparison –

        legacy; if True, the operator will be considered as a “comparison” operator, that is which evaluates to a boolean true/false value, like `==`, `>`, etc. This flag is provided so that ORM relationships can establish that the operator is a comparison operator when used in a custom join condition.

        Using the `is_comparison` parameter is superseded by using the `Operators.bool_op()` method instead; this more succinct operator sets this parameter automatically. In SQLAlchemy 2.0 it will also provide for improved typing support.

      - return_type – a `TypeEngine` class or object that will force the return type of an expression produced by this operator to be of that type. By default, operators that specify `Operators.op.is_comparison` will resolve to `Boolean`, and those that do not will be of the same type as the left-hand operand.

    See also

    `Operators.bool_op()`

    Redefining and Creating New Operators

    Using custom operators in join conditions

  method `sqlalchemy.orm.QueryableAttribute.`operate(op, *other, **kwargs)

    Operate on an argument.

    This is the lowest level of operation, raises `NotImplementedError` by default.

    Overriding this on a subclass can allow common behavior to be applied to all operations. For example, overriding `ColumnOperators` to apply `func.lower()` to the left and right side:

        class MyComparator(ColumnOperators):
            def operate(self, op, other, **kwargs):
                return op(func.lower(self), func.lower(other), **kwargs)

    Parameters:

      - op – Operator callable.

      - *other – the ‘other’ side of the operation. Will be a single scalar for most operations.

      - **kwargs – modifiers. These may be passed by special operators such as `ColumnOperators.contains()`.

  attribute `sqlalchemy.orm.QueryableAttribute.`parent

    Return an inspection instance representing the parent.

    This will be either an instance of `Mapper` or `AliasedInsp`, depending upon the nature of the parent entity which this attribute is associated with.

  attribute `sqlalchemy.orm.QueryableAttribute.`property

    Return the `MapperProperty` associated with this `QueryableAttribute`.

    Return values here will commonly be instances of `ColumnProperty` or `RelationshipProperty`.

  method `sqlalchemy.orm.QueryableAttribute.`regexp_match(pattern, flags=None)

    inherited from the `ColumnOperators.regexp_match()` method of `ColumnOperators`

    Implements a database-specific ‘regexp match’ operator.

    E.g.:

        stmt = select(table.c.some_column).where(
            table.c.some_column.regexp_match('^(b|c)')
        )

    `ColumnOperators.regexp_match()` attempts to resolve to a REGEXP-like function or operator provided by the backend, however the specific regular expression syntax and flags available are not backend agnostic.

    Examples include:

    - PostgreSQL - renders `x ~ y` or `x !~ y` when negated.

    - Oracle - renders `REGEXP_LIKE(x, y)`

    - SQLite - uses SQLite’s `REGEXP` placeholder operator and calls into the Python `re.match()` builtin.

    - other backends may provide special implementations.

    - Backends without any special implementation will emit the operator as “REGEXP” or “NOT REGEXP”. This is compatible with SQLite and MySQL, for example.

    Regular expression support is currently implemented for Oracle, PostgreSQL, MySQL and MariaDB. Partial support is available for SQLite. Support among third-party dialects may vary.

    Parameters:

      - pattern – The regular expression pattern string or column clause.

      - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern. When using the ignore case flag ‘i’ in PostgreSQL, the ignore case regexp match operator `~*` or `!~*` will be used.

    Added in version 1.4.

    Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

    See also

    `ColumnOperators.regexp_replace()`

  method `sqlalchemy.orm.QueryableAttribute.`regexp_replace(pattern, replacement, flags=None)

    inherited from the `ColumnOperators.regexp_replace()` method of `ColumnOperators`

    Implements a database-specific ‘regexp replace’ operator.

    E.g.:

        stmt = select(
            table.c.some_column.regexp_replace(
                'b(..)',
                'XY',
                flags='g'
            )
        )

    `ColumnOperators.regexp_replace()` attempts to resolve to a REGEXP_REPLACE-like function provided by the backend, that usually emit the function `REGEXP_REPLACE()`. However, the specific regular expression syntax and flags available are not backend agnostic.

    Regular expression replacement support is currently implemented for Oracle, PostgreSQL, MySQL 8 or greater and MariaDB. Support among third-party dialects may vary.

    Parameters:

      - pattern – The regular expression pattern string or column clause.

      - pattern – The replacement string or column clause.

      - flags – Any regular expression string flags to apply, passed as plain Python string only. These flags are backend specific. Some backends, like PostgreSQL and MariaDB, may alternatively specify the flags as part of the pattern.

    Added in version 1.4.

    Changed in version 1.4.48,: 2.0.18 Note that due to an implementation error, the “flags” parameter previously accepted SQL expression objects such as column expressions in addition to plain Python strings. This implementation did not work correctly with caching and was removed; strings only should be passed for the “flags” parameter, as these flags are rendered as literal inline values within SQL expressions.

    See also

    `ColumnOperators.regexp_match()`

  method `sqlalchemy.orm.QueryableAttribute.`reverse_operate(op, other, **kwargs)

    Reverse operate on an argument.

    Usage is the same as `operate()`.

  method `sqlalchemy.orm.QueryableAttribute.`startswith(other, **kwargs)

    inherited from the `ColumnOperators.startswith()` method of `ColumnOperators`

    Implement the `startswith` operator.

    Produces a LIKE expression that tests against a match for the start of a string value:

        column LIKE <other> || '%'

    E.g.:

        stmt = select(sometable).\
            where(sometable.c.column.startswith("foobar"))

    Since the operator uses `LIKE`, wildcard characters `"%"` and `"_"` that are present inside the <other> expression will behave like wildcards as well. For literal string values, the `ColumnOperators.startswith.autoescape` flag may be set to `True` to apply escaping to occurrences of these characters within the string value so that they match as themselves and not as wildcard characters. Alternatively, the `ColumnOperators.startswith.escape` parameter will establish a given character as an escape character which can be of use when the target expression is not a literal string.

    Parameters:

      - other – expression to be compared. This is usually a plain string value, but can also be an arbitrary SQL expression. LIKE wildcard characters `%` and `_` are not escaped by default unless the `ColumnOperators.startswith.autoescape` flag is set to True.

      - autoescape –

        boolean; when True, establishes an escape character within the LIKE expression, then applies it to all occurrences of `"%"`, `"_"` and the escape character itself within the comparison value, which is assumed to be a literal string and not a SQL expression.

        An expression such as:

            somecolumn.startswith("foo%bar", autoescape=True)

        Will render as:

            somecolumn LIKE :param || '%' ESCAPE '/'

        With the value of `:param` as `"foo/%bar"`.

      - escape –

        a character which when given will render with the `ESCAPE` keyword to establish that character as the escape character. This character can then be placed preceding occurrences of `%` and `_` to allow them to act as themselves and not wildcard characters.

        An expression such as:

            somecolumn.startswith("foo/%bar", escape="^")

        Will render as:

            somecolumn LIKE :param || '%' ESCAPE '^'

        The parameter may also be combined with `ColumnOperators.startswith.autoescape`:

            somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)

        Where above, the given literal parameter will be converted to `"foo^%bar^^bat"` before being passed to the database.

    See also

    `ColumnOperators.endswith()`

    `ColumnOperators.contains()`

    `ColumnOperators.like()`

  attribute `sqlalchemy.orm.QueryableAttribute.`timetuple = None

    inherited from the `ColumnOperators.timetuple` attribute of `ColumnOperators`

    Hack, allows datetime objects to be compared on the LHS.

class sqlalchemy.orm.UOWTransaction(session)
  method `sqlalchemy.orm.UOWTransaction.`filter_states_for_dep(dep, states)

    Filter the given list of InstanceStates to those relevant to the given DependencyProcessor.

  method `sqlalchemy.orm.UOWTransaction.`finalize_flush_changes()

    Mark processed objects as clean / deleted after a successful flush().

    This method is called within the flush() method after the execute() method has succeeded and the transaction has been committed.

  method `sqlalchemy.orm.UOWTransaction.`get_attribute_history(state, key, passive=symbol('PASSIVE_NO_INITIALIZE'))

    Facade to attributes.get_state_history(), including caching of results.

  method `sqlalchemy.orm.UOWTransaction.`is_deleted(state)

    Return `True` if the given state is marked as deleted within this uowtransaction.

  method `sqlalchemy.orm.UOWTransaction.`remove_state_actions(state)

    Remove pending actions for a state from the uowtransaction.

  Members

  filter_states_for_dep(), finalize_flush_changes(), get_attribute_history(), is_deleted(), remove_state_actions(), was_already_deleted()

  method `sqlalchemy.orm.UOWTransaction.`was_already_deleted(state)

    Return `True` if the given state is expired and was deleted previously.