SQLAlchemy 2.0 文档

在映射时从 Column Properties 组合

类签名

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

attribute sqlalchemy.orm.ColumnProperty.Comparator.expressions: Sequence[NamedColumn[Any]]¶

此属性引用的完整列序列: 属性，针对正在进行的任何别名调整。

1.3.17 版本新增。

另请参阅

Mapping a Class against Multiple Tables - 用法示例

method sqlalchemy.orm.ColumnProperty.Comparator.operate(op: OperatorType, *other: Any, **kwargs: Any) → ColumnElement[Any]¶

对参数执行操作。

这是最低级别的操作，默认情况下引发 NotImplementedError。

在子类上重写此方法可以允许将通用行为应用于所有操作。例如，重写 ColumnOperators 以将 func.lower() 应用于左侧和右侧

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

参数：

op¶ – 运算符可调用对象。
*other¶ – 操作的“另一侧”。对于大多数操作，将是单个标量。
**kwargs¶ – 修饰符。这些可以通过特殊运算符传递，例如 ColumnOperators.contains()。

method sqlalchemy.orm.ColumnProperty.Comparator.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → ColumnElement[Any]¶

对参数执行反向操作。

用法与 operate() 相同。

attribute sqlalchemy.orm.ColumnProperty.columns_to_assign¶

method sqlalchemy.orm.ColumnProperty.declarative_scan(decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: str | None, key: str, mapped_container: Type[Mapped[Any]] | None, annotation: _AnnotationScanType | None, extracted_mapped_annotation: _AnnotationScanType | None, is_dataclass_field: bool) → None¶: 在早期声明式扫描时执行特定于类的初始化。

2.0 版本新增。

method sqlalchemy.orm.ColumnProperty.do_init() → None¶

执行子类特定的初始化，mapper 创建后的步骤。

这是一个由 MapperProperty 对象的 init() 方法调用的模板方法。

attribute sqlalchemy.orm.ColumnProperty.expression¶

返回此 ColumnProperty 的主列或表达式。

例如：

class File(Base):
    # ...

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

另请参阅

method sqlalchemy.orm.ColumnProperty.instrument_class(mapper: Mapper[Any]) → None¶

Mapper 调用的钩子，用于初始化由此 MapperProperty 管理的类属性的 instrumentation。

此处的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

此步骤是设置 InstrumentedAttribute 的两个步骤中的第一步，并在 mapper 设置过程的早期调用。

第二步通常是 init_class_attribute 步骤，通过 post_instrument_class() 钩子从 StrategizedProperty 调用。此步骤将额外的状态分配给 InstrumentedAttribute（特别是“impl”），这在 MapperProperty 确定它需要执行哪种持久性管理（例如，标量、对象、集合等）之后确定。

attribute sqlalchemy.orm.ColumnProperty.mapper_property_to_assign¶

method sqlalchemy.orm.ColumnProperty.merge(session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object]) → None¶: 将此 MapperProperty 表示的属性从源对象合并到目标对象。

class sqlalchemy.orm.Composite¶

与声明式兼容的 CompositeProperty 类的前端。

公共构造函数是 composite() 函数。

在版本 2.0 中变更：添加了 Composite 作为 CompositeProperty 的声明式兼容子类。

另请参阅

复合列类型

类签名

class sqlalchemy.orm.Composite (sqlalchemy.orm.descriptor_props.CompositeProperty, sqlalchemy.orm.base._DeclarativeMapped)

class sqlalchemy.orm.CompositeProperty¶

定义一个“复合”映射属性，将列的集合表示为一个属性。

CompositeProperty 是使用 composite() 函数构造的。

另请参阅

复合列类型

成员

create_row_processor(), columns_to_assign, declarative_scan(), do_init(), get_history(), instrument_class(), mapper_property_to_assign

类签名

class sqlalchemy.orm.CompositeProperty (sqlalchemy.orm._MapsColumns, sqlalchemy.orm._IntrospectsAnnotations, sqlalchemy.orm.descriptor_props.DescriptorProperty)

class Comparator¶

为 Composite 属性生成布尔运算符、比较运算符和其他运算符。

有关用法概述，请参阅为复合类型重新定义比较操作中的示例，以及 PropComparator 的文档。

另请参阅

PropComparator

ColumnOperators

Mapper.all_orm_descriptors

类签名

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

class CompositeBundle¶

类签名

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

method sqlalchemy.orm.CompositeProperty.CompositeBundle.create_row_processor(query: Select[Any], procs: Sequence[Callable[[Row[Any]], Any]], labels: Sequence[str]) → Callable[[Row[Any]], Any]¶

为此 Bundle 生成“行处理”函数。

子类可以重写此方法，以便在获取结果时提供自定义行为。在查询执行时，该方法会传递语句对象和一组“行处理器”函数；这些处理器函数在给定结果行时将返回单个属性值，然后可以将其调整为任何类型的返回数据结构。

下面的示例说明了如何使用简单的 Python 字典替换通常的 Row 返回结构

from sqlalchemy.orm import Bundle


class DictBundle(Bundle):
    def create_row_processor(self, query, procs, labels):
        "Override create_row_processor to return values as dictionaries"

        def proc(row):
            return dict(zip(labels, (proc(row) for proc in procs)))

        return proc

来自上述 Bundle 的结果将返回字典值

bn = DictBundle("mybundle", MyClass.data1, MyClass.data2)
for row in session.execute(select(bn)).where(bn.c.data1 == "d1"):
    print(row.mybundle["data1"], row.mybundle["data2"])

attribute sqlalchemy.orm.CompositeProperty.columns_to_assign¶

method sqlalchemy.orm.CompositeProperty.declarative_scan(decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: str | None, key: str, mapped_container: Type[Mapped[Any]] | None, annotation: _AnnotationScanType | None, extracted_mapped_annotation: _AnnotationScanType | None, is_dataclass_field: bool) → None¶: 在早期声明式扫描时执行特定于类的初始化。

2.0 版本新增。

method sqlalchemy.orm.CompositeProperty.do_init() → None¶: 在 Composite 与其父 mapper 关联后发生的初始化。

method sqlalchemy.orm.CompositeProperty.get_history(state: InstanceState[Any], dict_: _InstanceDict, passive: PassiveFlag = symbol('PASSIVE_OFF')) → History¶: 为使用 attributes.get_history() 的用户代码提供。

method sqlalchemy.orm.CompositeProperty.instrument_class(mapper: Mapper[Any]) → None¶

Mapper 调用的钩子，用于初始化由此 MapperProperty 管理的类属性的 instrumentation。

此处的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

此步骤是设置 InstrumentedAttribute 的两个步骤中的第一步，并在 mapper 设置过程的早期调用。

第二步通常是 init_class_attribute 步骤，通过 post_instrument_class() 钩子从 StrategizedProperty 调用。此步骤将额外的状态分配给 InstrumentedAttribute（特别是“impl”），这在 MapperProperty 确定它需要执行哪种持久性管理（例如，标量、对象、集合等）之后确定。

attribute sqlalchemy.orm.CompositeProperty.mapper_property_to_assign¶

class sqlalchemy.orm.AttributeEventToken¶

在属性事件链过程中传播的令牌。

用作事件源的指示符，并提供一种控制跨属性操作链传播的方法。

当处理诸如 AttributeEvents.append()、AttributeEvents.set() 和 AttributeEvents.remove() 等事件时，Event 对象作为 initiator 参数发送。

Event 对象当前由 backref 事件处理程序解释，并用于控制跨两个相互依赖的属性的操作传播。

在版本 2.0 中变更：将名称从 AttributeEvent 更改为 AttributeEventToken。

属性 impl:: 作为当前事件发起者的 AttributeImpl。
属性 op:: 符号 OP_APPEND、OP_REMOVE、OP_REPLACE 或 OP_BULK_REPLACE，指示源操作。

class sqlalchemy.orm.IdentityMap¶

成员

check_modified()

method sqlalchemy.orm.IdentityMap.check_modified() → bool¶: 如果存在的任何 InstanceState 已被标记为“modified”，则返回 True。

class sqlalchemy.orm.InspectionAttr¶

应用于所有 ORM 对象和属性的基类，这些对象和属性与 inspect() 函数可以返回的事物相关。

此处定义的属性允许使用简单的布尔检查来测试关于返回对象的基本事实。

成员

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

虽然这里的布尔检查与使用 Python 的 isinstance() 函数基本相同，但这里的标志可以在不需要导入所有这些类的情况下使用，并且 SQLAlchemy 类系统可以更改，同时保持此处的标志完整以实现向前兼容性。

attribute sqlalchemy.orm.InspectionAttr.extension_type: InspectionAttrExtensionType = 'not_extension'¶: 扩展类型（如果有）。默认为 NotExtension.NOT_EXTENSION

另请参阅

HybridExtensionType

AssociationProxyExtensionType

attribute sqlalchemy.orm.InspectionAttr.is_aliased_class = False¶: 如果此对象是 AliasedClass 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_attribute = False¶

如果此对象是 Python descriptor，则为 True。

这可以指多种类型之一。通常是 QueryableAttribute，它代表 MapperProperty 处理属性事件。但也可能是一个扩展类型，例如 AssociationProxy 或 hybrid_property。InspectionAttr.extension_type 将引用标识特定子类型的常量。

另请参阅

attribute sqlalchemy.orm.InspectionAttr.is_bundle = False¶: 如果此对象是 Bundle 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_clause_element = False¶: 如果此对象是 ClauseElement 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_instance = False¶: 如果此对象是 InstanceState 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_mapper = False¶: 如果此对象是 Mapper 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_property = False¶: 如果此对象是 MapperProperty 的实例，则为 True。

attribute sqlalchemy.orm.InspectionAttr.is_selectable = False¶: 如果此对象是 Selectable 的实例，则返回 True。

class sqlalchemy.orm.InspectionAttrInfo¶

将 .info 属性添加到 InspectionAttr。

InspectionAttr 与 InspectionAttrInfo 的基本原理是，前者可以作为 mixin 兼容指定 __slots__ 的类；这本质上是一个实现工件。

成员

info

类签名

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

attribute sqlalchemy.orm.InspectionAttrInfo.info¶

与对象关联的信息字典，允许用户定义的数据与此 InspectionAttr 关联。

该字典在首次访问时生成。或者，它可以作为构造函数参数指定给 column_property()、relationship() 或 composite() 函数。

另请参阅

QueryableAttribute.info

InstanceState.async_session

class sqlalchemy.orm.InstanceState¶

在实例级别跟踪状态信息。

InstanceState 是 SQLAlchemy ORM 使用的关键对象，用于跟踪对象的状态；它在对象实例化时创建，通常是 SQLAlchemy 应用于类的 __init__() 方法的instrumentation（检测）的结果。

InstanceState 也是一个半公开对象，可用于运行时检查映射实例的状态，包括其在特定 Session 中的当前状态以及关于各个属性数据的详细信息。获取 InstanceState 对象的公共 API 是使用 inspect() 系统。

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

另请参阅

映射实例的检测

类签名

class sqlalchemy.orm.InstanceState (sqlalchemy.orm.base.InspectionAttrInfo, typing.Generic)

attribute sqlalchemy.orm.InstanceState.async_session¶

返回此实例所属的 AsyncSession，如果没有则返回 None。

仅当此 ORM 对象使用 sqlalchemy.ext.asyncio API 时，此属性才不为 None。返回的 AsyncSession 对象将是 Session 对象的代理，该对象将从此 InstanceState 的 InstanceState.session 属性返回。

1.4.18 版本新增。

另请参阅

异步 I/O (asyncio)

attribute sqlalchemy.orm.InstanceState.attrs¶

返回表示映射对象上每个属性的命名空间，包括其当前值和历史记录。

返回的对象是 AttributeState 的实例。此对象允许检查属性中的当前数据以及自上次刷新以来的属性历史记录。

attribute sqlalchemy.orm.InstanceState.callables: Dict[str, Callable[[InstanceState[_O], PassiveFlag], Any]] = {}¶

一个命名空间，可以在其中关联每个状态的加载器可调用对象。

在 SQLAlchemy 1.0 中，这仅用于通过查询选项设置的惰性加载器/延迟加载器。

以前，callables 也用于指示过期的属性，方法是在此字典中存储指向 InstanceState 自身的链接。此角色现在由 expired_attributes 集合处理。

attribute sqlalchemy.orm.InstanceState.deleted¶

如果对象处于 deleted（已删除）状态，则返回 True。

处于 deleted 状态的对象保证不在其父 Session 的 Session.identity_map（标识映射）中；但是，如果会话的事务回滚，则对象将恢复为 persistent 状态和标识映射。

注意

InstanceState.deleted 属性指的是对象在 “persistent”（持久）和 “detached”（分离）状态之间发生的特定状态；一旦对象 detached，InstanceState.deleted 属性不再返回 True；为了检测状态是否已被删除，无论对象是否与 Session 关联，请使用 InstanceState.was_deleted 访问器。

另请参阅

对象状态快速入门

attribute sqlalchemy.orm.InstanceState.detached¶: 如果对象处于 detached（分离）状态，则返回 True。

另请参阅

对象状态快速入门

attribute sqlalchemy.orm.InstanceState.dict¶

返回对象使用的实例字典。

在正常情况下，这始终与映射对象的 __dict__ 属性同义，除非配置了替代的检测系统。

如果实际对象已被垃圾回收，则此访问器返回一个空白字典。

attribute sqlalchemy.orm.InstanceState.expired: bool = False¶: 当 True 时，对象处于 expired（过期）状态。

另请参阅

刷新/过期

attribute sqlalchemy.orm.InstanceState.expired_attributes: Set[str]¶

假设没有挂起的更改，则管理器延迟标量加载器要加载的“过期”键的集合。

另请参阅 unmodified 集合，在刷新操作发生时，该集合会与此集合相交。

attribute sqlalchemy.orm.InstanceState.has_identity¶

如果此对象具有标识键，则返回 True。

这应始终与表达式 state.persistent 或 state.detached 的值相同。

attribute sqlalchemy.orm.InstanceState.identity¶

返回映射对象的映射标识。这是 ORM 持久化的主键标识，始终可以直接传递给 Query.get()。

如果对象没有主键标识，则返回 None。

注意

即使 transient（瞬态）或 pending（待定）的对象，即使其属性包含主键值，在刷新之前也不具有映射标识。

attribute sqlalchemy.orm.InstanceState.identity_key¶

返回映射对象的标识键。

这是用于在 Session.identity_map 映射中查找对象的键。它包含 identity 返回的标识。

attribute sqlalchemy.orm.InstanceState.is_instance: bool = True¶: 如果此对象是 InstanceState 的实例，则为 True。

attribute sqlalchemy.orm.InstanceState.mapper¶: 返回用于此映射对象的 Mapper。

attribute sqlalchemy.orm.InstanceState.modified: bool = False¶: 当 True 时，对象已被修改。

attribute sqlalchemy.orm.InstanceState.object¶

返回由此 InstanceState 表示的映射对象。

如果对象已被垃圾回收，则返回 None

attribute sqlalchemy.orm.InstanceState.pending¶: 如果对象处于 pending（待定）状态，则返回 True。

另请参阅

对象状态快速入门

attribute sqlalchemy.orm.InstanceState.persistent¶

如果对象处于 persistent（持久）状态，则返回 True。

处于 persistent 状态的对象保证在其父 Session 的 Session.identity_map（标识映射）中。

另请参阅

对象状态快速入门

attribute sqlalchemy.orm.InstanceState.session¶

返回此实例所属的 Session，如果没有则返回 None。

请注意，此处的结果在某些情况下可能与 obj in session 的结果不同；已被删除的对象将报告为不 in session，但是如果事务仍在进行中，则此属性仍将引用该会话。只有当事务完成后，对象在正常情况下才会完全分离。

另请参阅

attribute sqlalchemy.orm.InstanceState.transient¶: 如果对象处于 transient（瞬态）状态，则返回 True。

另请参阅

对象状态快速入门

attribute sqlalchemy.orm.InstanceState.unloaded¶

返回不具有已加载值的键的集合。

这包括过期的属性以及任何其他从未填充或修改过的属性。

attribute sqlalchemy.orm.InstanceState.unloaded_expirable¶

与 InstanceState.unloaded 同义。

Deprecated since version 2.0: InstanceState.unloaded_expirable 属性已弃用。请使用 InstanceState.unloaded。

此属性在某个时候作为特定于实现的细节添加，应被视为私有属性。

attribute sqlalchemy.orm.InstanceState.unmodified¶: 返回没有未提交更改的键的集合。

method sqlalchemy.orm.InstanceState.unmodified_intersection(keys: Iterable[str]) → Set[str]¶: 返回 self.unmodified.intersection(keys)。

attribute sqlalchemy.orm.InstanceState.was_deleted¶

如果此对象当前或之前处于 “deleted” 状态且尚未恢复为 persistent 状态，则返回 True。

一旦对象在 flush 中被删除，此标志将返回 True。当对象从会话中显式或通过事务提交移除并进入 “detached” 状态时，此标志将继续报告 True。

另请参阅

InstanceState.deleted - 指的是 “deleted” 状态

was_deleted() - 独立函数

对象状态快速入门

class sqlalchemy.orm.InstrumentedAttribute¶: 代表 MapperProperty 对象拦截属性事件的 descriptor 对象基类。实际的 MapperProperty 可通过 QueryableAttribute.property 属性访问。

另请参阅

InstrumentedAttribute

MapperProperty

Mapper.all_orm_descriptors

Mapper.attrs

类签名

class sqlalchemy.orm.InstrumentedAttribute (sqlalchemy.orm.QueryableAttribute)

class sqlalchemy.orm.LoaderCallableStatus¶

一个枚举。

成员

ATTR_EMPTY, ATTR_WAS_SET, NEVER_SET, NO_VALUE, PASSIVE_CLASS_MISMATCH, PASSIVE_NO_RESULT

类签名

class sqlalchemy.orm.LoaderCallableStatus (enum.Enum)

attribute sqlalchemy.orm.LoaderCallableStatus.ATTR_EMPTY = 3¶: 内部使用的符号，用于指示属性没有可调用对象。

attribute sqlalchemy.orm.LoaderCallableStatus.ATTR_WAS_SET = 2¶: 加载器可调用对象返回的符号，指示检索到的值（或多个值）已分配给目标对象上的属性。

attribute sqlalchemy.orm.LoaderCallableStatus.NEVER_SET = 4¶: 与 NO_VALUE 同义

Changed in version 1.4: NEVER_SET 与 NO_VALUE 合并

attribute sqlalchemy.orm.LoaderCallableStatus.NO_VALUE = 4¶: 可以作为属性的“previous”（先前）值放置的符号，指示在修改属性时未加载任何值，并且标志指示我们不加载它。

attribute sqlalchemy.orm.LoaderCallableStatus.PASSIVE_CLASS_MISMATCH = 1¶: 符号，指示对象在本地存在给定的主键标识，但它不是请求的类。因此，返回值是 None，并且不应发出 SQL。

attribute sqlalchemy.orm.LoaderCallableStatus.PASSIVE_NO_RESULT = 0¶: 当基于加载器可调用标志无法确定值时，加载器可调用对象或其他属性/历史记录检索操作返回的符号。

class sqlalchemy.orm.Mapped¶

表示映射类上的 ORM 映射属性。

此类表示任何类属性的完整描述符接口，这些类属性将通过 ORM Mapper 类进行 instrumented（检测）。为 pylance 和 mypy 等类型检查器提供适当的信息，以便正确键入 ORM 映射的属性。

Mapped 最突出的用途是在 Mapper 配置的声明式映射形式中，其中显式使用它来驱动 ORM 属性的配置，例如 mapped_class() 和 relationship()。

另请参阅

使用声明式基类

带有 mapped_column() 的声明式表

提示

Mapped 类表示由 Mapper 类直接处理的属性。它不包括作为扩展提供的其他 Python 描述符类，包括混合属性和关联代理。虽然这些系统仍然使用 ORM 特定的超类和结构，但它们不是由 Mapper instrumented（检测）的，而是在类上访问它们时提供自己的功能。

1.4 版本新增。

类签名

class sqlalchemy.orm.Mapped (sqlalchemy.orm.base.SQLORMExpression, sqlalchemy.orm.base.ORMDescriptor, sqlalchemy.orm.base._MappedAnnotationBase, sqlalchemy.sql.roles.DDLConstraintColumnRole)

class sqlalchemy.orm.MappedColumn¶

将类上的单个 Column 映射。

MappedColumn 是 ColumnProperty 类的特化，并且面向声明式配置。

要构造 MappedColumn 对象，请使用 mapped_column() 构造函数。

2.0 版本新增。

类签名

class sqlalchemy.orm.MappedColumn (sqlalchemy.orm._IntrospectsAnnotations, sqlalchemy.orm._MapsColumns, sqlalchemy.orm.base._DeclarativeMapped)

class sqlalchemy.orm.MapperProperty¶

表示由 Mapper 映射的特定类属性。

最常见的 MapperProperty 出现形式是映射的 Column，在映射中表示为 ColumnProperty 的实例，以及由 relationship() 生成的对另一个类的引用，在映射中表示为 Relationship 的实例。

成员

cascade_iterator(), class_attribute, comparator, create_row_processor(), do_init(), doc, info, init(), instrument_class(), is_property, key, merge(), parent, post_instrument_class(), set_parent(), setup()

类签名

class sqlalchemy.orm.MapperProperty (sqlalchemy.sql.cache_key.HasCacheKey, sqlalchemy.orm._DCAttributeOptions, sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.base.InspectionAttrInfo, sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.orm.MapperProperty.cascade_iterator(type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Callable[[InstanceState[Any]], bool] | None = None) → Iterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]]¶

迭代处理与给定实例相关的实例，以进行特定的“级联”操作，从这个 MapperProperty 开始。

返回一个迭代器，包含 3 元组 (instance, mapper, state)。

请注意，在调用 cascade_iterator 之前，首先检查此 MapperProperty 上的“cascade”集合是否为给定类型。

此方法通常仅适用于 Relationship。

attribute sqlalchemy.orm.MapperProperty.class_attribute¶

返回与此 MapperProperty 对应的类绑定描述符。

这基本上是一个 getattr() 调用。

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

例如，如果此 MapperProperty 被命名为 addresses，并且它映射到的类是 User，则以下序列是可能的：

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

attribute sqlalchemy.orm.MapperProperty.comparator: PropComparator[_T]¶: PropComparator 实例，它代表此映射属性实现 SQL 表达式的构建。

method sqlalchemy.orm.MapperProperty.create_row_processor(context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, mapper: Mapper[Any], result: Result[Any], adapter: ORMAdapter | None, populators: _PopulatorDict) → None¶: 生成行处理函数，并追加到给定的 populators 列表集合。

method sqlalchemy.orm.MapperProperty.do_init() → None¶

执行子类特定的初始化，mapper 创建后的步骤。

这是一个由 MapperProperty 对象的 init() 方法调用的模板方法。

attribute sqlalchemy.orm.MapperProperty.doc: str | None¶: 可选的文档字符串

attribute sqlalchemy.orm.MapperProperty.info: _InfoType¶

与对象关联的信息字典，允许用户定义的数据与此 InspectionAttr 关联。

该字典在首次访问时生成。或者，它可以作为构造函数参数指定给 column_property()、relationship() 或 composite() 函数。

另请参阅

QueryableAttribute.info

method sqlalchemy.orm.MapperProperty.init() → None¶: 在创建所有 mapper 后调用，以组装 mapper 之间的关系并执行其他 mapper 创建后的初始化步骤。

method sqlalchemy.orm.MapperProperty.instrument_class(mapper: Mapper[Any]) → None¶

Mapper 调用的钩子，用于初始化由此 MapperProperty 管理的类属性的 instrumentation。

此处的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

此步骤是设置 InstrumentedAttribute 的两个步骤中的第一步，并在 mapper 设置过程的早期调用。

第二步通常是 init_class_attribute 步骤，通过 post_instrument_class() 钩子从 StrategizedProperty 调用。此步骤将额外的状态分配给 InstrumentedAttribute（特别是“impl”），这在 MapperProperty 确定它需要执行哪种持久性管理（例如，标量、对象、集合等）之后确定。

attribute sqlalchemy.orm.MapperProperty.is_property = True¶: InspectionAttr 接口的一部分；声明此对象是 mapper 属性。

attribute sqlalchemy.orm.MapperProperty.key: str¶: 类属性的名称

method sqlalchemy.orm.MapperProperty.merge(session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object]) → None¶: 将此 MapperProperty 表示的属性从源对象合并到目标对象。

attribute sqlalchemy.orm.MapperProperty.parent: Mapper[Any]¶: 管理此属性的 Mapper。

method sqlalchemy.orm.MapperProperty.post_instrument_class(mapper: Mapper[Any]) → None¶

执行在 init() 完成后需要进行的 instrumentation 调整。

给定的 Mapper 是调用操作的 Mapper，它可能与继承场景中的 self.parent 不是同一个 Mapper；但是，Mapper 始终至少是 self.parent 的子 mapper。

此方法通常由 StrategizedProperty 使用，它将其委托给 LoaderStrategy.init_class_attribute()，以对类绑定的 InstrumentedAttribute 执行最终设置。

method sqlalchemy.orm.MapperProperty.set_parent(parent: Mapper[Any], init: bool) → None¶

设置引用此 MapperProperty 的父 mapper。

某些子类会覆盖此方法，以在首次知道 mapper 时执行额外的设置。

method sqlalchemy.orm.MapperProperty.setup(context: ORMCompileState, query_entity: _MapperEntity, path: AbstractEntityRegistry, adapter: ORMAdapter | None, **kwargs: Any) → None¶

由 Query 调用，用于构造 SQL 语句。

与目标 mapper 关联的每个 MapperProperty 处理查询上下文引用的语句，并根据需要添加列和/或条件。

class sqlalchemy.orm.MappedSQLExpression¶

ColumnProperty 类的声明式前端。

公共构造函数是 column_property() 函数。

在版本 2.0 中更改: 添加了 MappedSQLExpression 作为 ColumnProperty 的声明式兼容子类。

另请参阅

MappedColumn

类签名

class sqlalchemy.orm.MappedSQLExpression (sqlalchemy.orm.properties.ColumnProperty, sqlalchemy.orm.base._DeclarativeMapped)

class sqlalchemy.orm.InspectionAttrExtensionType¶: 指示 InspectionAttr 所属扩展类型的符号。

类签名

class sqlalchemy.orm.InspectionAttrExtensionType (enum.Enum)

class sqlalchemy.orm.NotExtension¶

一个枚举。

成员

NOT_EXTENSION

类签名

class sqlalchemy.orm.NotExtension (sqlalchemy.orm.base.InspectionAttrExtensionType)

attribute sqlalchemy.orm.NotExtension.NOT_EXTENSION = 'not_extension'¶

指示 InspectionAttr 不是 sqlalchemy.ext 的一部分的符号。

分配给 InspectionAttr.extension_type 属性。

function sqlalchemy.orm.merge_result(query: Query[Any], iterator: FrozenResult | Iterable[Sequence[Any]] | Iterable[object], load: bool = True) → FrozenResult | Iterable[Any]¶

将结果合并到给定 Query 对象的 Session 中。

自版本 2.0 起已弃用: merge_result() 函数从 SQLAlchemy 1.x 系列版本开始被认为是遗留功能，并在 2.0 版本中成为遗留构造。此函数以及 Query 上的方法已被 merge_frozen_result() 函数取代。（关于 SQLAlchemy 2.0 的背景信息：SQLAlchemy 2.0 - 主要迁移指南）

有关此函数的顶层文档，请参阅 Query.merge_result()。

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

将 FrozenResult 合并回 Session，返回一个包含 persistent 对象的新 Result 对象。

有关示例，请参阅重新执行语句部分。

另请参阅

重新执行语句

Result.freeze()

FrozenResult

class sqlalchemy.orm.PropComparator¶

为 ORM 映射属性定义 SQL 操作。

SQLAlchemy 允许在 Core 和 ORM 级别重新定义运算符。PropComparator 是 ORM 级别操作（包括 ColumnProperty、Relationship 和 Composite 的操作）的运算符重定义的基类。

可以创建 PropComparator 的用户定义子类。内置的 Python 比较和数学运算符方法，例如 ColumnOperators.__eq__()、ColumnOperators.__lt__() 和 ColumnOperators.__add__()，可以被覆盖以提供新的运算符行为。自定义的 PropComparator 通过 comparator_factory 参数传递给 MapperProperty 实例。在每种情况下，都应使用 PropComparator 的适当子类。

# definition of custom PropComparator subclasses

from sqlalchemy.orm.properties import (
    ColumnProperty,
    Composite,
    Relationship,
)


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


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


class MyCompositeComparator(Composite.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,
    )

请注意，对于列级别的运算符重定义，通常更简单的方法是在 Core 级别使用 TypeEngine.comparator_factory 属性定义运算符。有关更多详细信息，请参阅重新定义和创建新运算符。

另请参阅

比较器

ColumnOperators

ColumnOperators.startswith()

类签名

class sqlalchemy.orm.PropComparator (sqlalchemy.orm.base.SQLORMOperations, typing.Generic, sqlalchemy.sql.expression.ColumnOperators)

方法 sqlalchemy.orm.PropComparator.__eq__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ 方法，源自 ColumnOperators

实现 == 运算符。

在列上下文中，生成子句 a = b。如果目标为 None，则生成 a IS NULL。

方法 sqlalchemy.orm.PropComparator.__le__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__le__ 方法，源自 ColumnOperators

实现 <= 运算符。

在列上下文中，生成子句 a <= b。

方法 sqlalchemy.orm.PropComparator.__lt__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__lt__ 方法，源自 ColumnOperators

实现 < 运算符。

在列上下文中，生成子句 a < b。

方法 sqlalchemy.orm.PropComparator.__ne__(other: Any) → ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__ne__ 方法，源自 ColumnOperators

实现 != 运算符。

在列上下文中，生成子句 a != b。如果目标为 None，则生成 a IS NOT NULL。

方法 sqlalchemy.orm.PropComparator.adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → PropComparator[_T_co]¶: 返回此 PropComparator 的副本，该副本将使用给定的 AliasedInsp 来生成相应的表达式。

属性 sqlalchemy.orm.PropComparator.adapter¶: 生成一个可调用对象，该对象调整列表达式以适应此比较器的别名版本。

方法 sqlalchemy.orm.PropComparator.all_() → ColumnOperators¶

继承自 ColumnOperators.all_() 方法，源自 ColumnOperators

针对父对象生成 all_() 子句。

有关示例，请参阅 all_() 的文档。

注意

请务必不要将较新的 ColumnOperators.all_() 方法与此方法的旧版混淆，即特定于 ARRAY 的 Comparator.all() 方法，后者使用不同的调用样式。

方法 sqlalchemy.orm.PropComparator.and_(*criteria: _ColumnExpressionArgument[bool]) → PropComparator[bool]¶

为此关系属性表示的 ON 子句添加其他条件。

例如：

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

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

1.4 版本新增。

另请参阅

将关系与自定义 ON 条件结合使用

向加载器选项添加条件

with_loader_criteria()

方法 sqlalchemy.orm.PropComparator.any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]¶

如果此元素引用的成员满足给定条件，则返回表示 true 的 SQL 表达式。

any() 的常用实现是 Comparator.any()。

参数：

criterion¶ – 可选的 ClauseElement，针对成员类的表或属性制定。
**kwargs¶ – 键/值对，对应于成员类属性名称，这些名称将通过相等性与相应的值进行比较。

方法 sqlalchemy.orm.PropComparator.any_() → ColumnOperators¶

继承自 ColumnOperators.any_() 方法，源自 ColumnOperators

针对父对象生成 any_() 子句。

有关示例，请参阅 any_() 的文档。

注意

请务必不要将较新的 ColumnOperators.any_() 方法与此方法的旧版混淆，即特定于 ARRAY 的 Comparator.any() 方法，后者使用不同的调用样式。

方法 sqlalchemy.orm.PropComparator.asc() → ColumnOperators¶: 继承自 ColumnOperators.asc() 方法，源自 ColumnOperators

针对父对象生成 asc() 子句。

方法 sqlalchemy.orm.PropComparator.between(cleft: Any, cright: Any, symmetric: bool = False) → ColumnOperators¶: 继承自 ColumnOperators.between() 方法，源自 ColumnOperators

给定下限和上限范围，针对父对象生成 between() 子句。

方法 sqlalchemy.orm.PropComparator.bitwise_and(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_and() 方法，源自 ColumnOperators

生成按位 AND 运算，通常通过 & 运算符实现。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bitwise_lshift(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_lshift() 方法，源自 ColumnOperators

生成按位 LSHIFT 运算，通常通过 << 运算符实现。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bitwise_not() → ColumnOperators¶: 继承自 ColumnOperators.bitwise_not() 方法，源自 ColumnOperators

生成按位 NOT 运算，通常通过 ~ 运算符实现。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bitwise_or(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_or() 方法，源自 ColumnOperators

生成按位 OR 运算，通常通过 | 运算符实现。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bitwise_rshift(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_rshift() 方法，源自 ColumnOperators

生成按位 RSHIFT 运算，通常通过 >> 运算符实现。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bitwise_xor(other: Any) → ColumnOperators¶: 继承自 ColumnOperators.bitwise_xor() 方法，源自 ColumnOperators

生成按位 XOR 运算，通常通过 ^ 运算符实现，PostgreSQL 中为 # 运算符。

2.0.2 版本新增功能。

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator.bool_op(opstring: str, precedence: int = 0, python_impl: Callable[[...], Any] | None = None) → Callable[[Any], Operators]¶

继承自 Operators.bool_op() 方法，源自 Operators

返回自定义布尔运算符。

此方法是调用 Operators.op() 并传递 Operators.op.is_comparison 标志为 True 的简写形式。使用 Operators.bool_op() 的一个主要优点是，当使用列构造时，返回表达式的“布尔”性质将出于 PEP 484 的目的而呈现。

另请参阅

Operators.op()

方法 sqlalchemy.orm.PropComparator.collate(collation: str) → ColumnOperators¶: 继承自 ColumnOperators.collate() 方法，源自 ColumnOperators

针对父对象生成一个 collate() 子句，给定排序规则字符串。

另请参阅

collate()

方法 sqlalchemy.orm.PropComparator.concat(other: Any) → ColumnOperators¶

继承自 ColumnOperators.concat() 方法，源自 ColumnOperators

实现 ‘concat’ 运算符。

在列上下文中，生成子句 a || b，或者在 MySQL 上使用 concat() 运算符。

方法 sqlalchemy.orm.PropComparator.contains(other: Any, **kw: Any) → ColumnOperators¶

继承自 ColumnOperators.contains() 方法，源自 ColumnOperators

实现 ‘contains’ 运算符。

生成一个 LIKE 表达式，用于测试字符串值中间部分是否匹配。

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

例如：

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

由于该运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，可以将 ColumnOperators.contains.autoescape 标志设置为 True，以转义字符串值中出现的这些字符，以便它们作为自身匹配，而不是作为通配符匹配。或者，ColumnOperators.contains.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.contains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.contains("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.contains("foo/%bar", escape="^")
```
将渲染为：
```
somecolumn LIKE '%' || :param || '%' ESCAPE '^'
```
此参数也可以与 ColumnOperators.contains.autoescape 结合使用。
```
somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

ColumnOperators.startswith()

方法 sqlalchemy.orm.PropComparator.desc() → ColumnOperators¶: 继承自 ColumnOperators.desc() 方法，源自 ColumnOperators

针对父对象生成一个 desc() 子句。

方法 sqlalchemy.orm.PropComparator.distinct() → ColumnOperators¶: 继承自 ColumnOperators.distinct() 方法，源自 ColumnOperators

针对父对象生成一个 distinct() 子句。

方法 sqlalchemy.orm.PropComparator.endswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators¶

继承自 ColumnOperators.endswith() 方法，源自 ColumnOperators

实现 ‘endswith’ 运算符。

生成一个 LIKE 表达式，用于测试字符串值结尾部分是否匹配。

column LIKE '%' || <other>

例如：

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

由于该运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，可以将 ColumnOperators.endswith.autoescape 标志设置为 True，以转义字符串值中出现的这些字符，以便它们作为自身匹配，而不是作为通配符匹配。或者，ColumnOperators.endswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.endswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.endswith("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE '%' || :param ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.endswith("foo/%bar", escape="^")
```
将渲染为：
```
somecolumn LIKE '%' || :param ESCAPE '^'
```
此参数也可以与 ColumnOperators.endswith.autoescape 结合使用。
```
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.contains()

ColumnOperators.contains()

方法 sqlalchemy.orm.PropComparator.has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]¶

如果此元素引用的成员满足给定条件，则返回表示 true 的 SQL 表达式。

has() 的常用实现是 Comparator.has()。

参数：

criterion¶ – 一个可选的 ClauseElement，根据成员类的表或属性制定。
**kwargs¶ – 键/值对，对应于成员类属性名称，这些名称将通过相等性与对应的值进行比较。

方法 sqlalchemy.orm.PropComparator.icontains(other: Any, **kw: Any) → ColumnOperators¶

继承自 ColumnOperators.icontains() 方法，源自 ColumnOperators

实现 icontains 运算符，例如 ColumnOperators.contains() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值中间部分是否不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>) || '%'

例如：

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

由于该运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，可以将 ColumnOperators.icontains.autoescape 标志设置为 True，以转义字符串值中出现的这些字符，以便它们作为自身匹配，而不是作为通配符匹配。或者，ColumnOperators.icontains.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.icontains.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.icontains("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.icontains("foo/%bar", escape="^")
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '^'
```
此参数也可以与 ColumnOperators.contains.autoescape 结合使用。
```
somecolumn.icontains("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

方法 sqlalchemy.orm.PropComparator.iendswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators¶

继承自 ColumnOperators.iendswith() 方法，源自 ColumnOperators

实现 iendswith 运算符，例如 ColumnOperators.endswith() 的不区分大小写版本。

生成一个 LIKE 表达式，用于测试字符串值结尾部分是否不区分大小写匹配。

lower(column) LIKE '%' || lower(<other>)

例如：

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

由于该运算符使用 LIKE，因此 <other> 表达式中存在的通配符 "%" 和 "_" 也将表现为通配符。对于字面字符串值，可以将 ColumnOperators.iendswith.autoescape 标志设置为 True，以转义字符串值中出现的这些字符，以便它们作为自身匹配，而不是作为通配符匹配。或者，ColumnOperators.iendswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.iendswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.iendswith("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.iendswith("foo/%bar", escape="^")
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '^'
```
此参数也可以与 ColumnOperators.iendswith.autoescape 结合使用。
```
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

方法 sqlalchemy.orm.PropComparator.ilike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.ilike() 方法，源自 ColumnOperators

实现 ilike 运算符，例如不区分大小写的 LIKE。

在列上下文中，生成以下形式的表达式：

lower(a) LIKE lower(other)

或者在支持 ILIKE 运算符的后端上：

a ILIKE other

例如：

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

参数：

other¶ – 要比较的表达式。
escape¶ –
可选的转义字符，渲染 ESCAPE 关键字，例如：
```
somecolumn.ilike("foo/%bar", escape="/")
```

另请参阅

ColumnOperators.is_not()

方法 sqlalchemy.orm.PropComparator.in_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.in_() 方法，源自 ColumnOperators

实现 in 运算符。

在列上下文中，生成子句 column IN <other>。

给定的参数 other 可以是：

字面值列表，例如：
```
stmt.where(column.in_([1, 2, 3]))
```
在这种调用形式中，项目列表将转换为一组绑定参数，其长度与给定的列表相同。
```
WHERE COL IN (?, ?, ?)
```

如果比较是针对包含多个表达式的 tuple_()，则可以提供元组列表。

from sqlalchemy import tuple_

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

一个空列表，例如：
```
stmt.where(column.in_([]))
```
在这种调用形式中，该表达式渲染一个“空集”表达式。这些表达式是为各个后端量身定制的，并且通常尝试获取一个空的 SELECT 语句作为子查询。例如，在 SQLite 上，该表达式为：
```
WHERE col IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
```
在 1.4 版本中变更：空的 IN 表达式现在在所有情况下都使用执行时生成的 SELECT 子查询。
如果绑定参数包含 bindparam.expanding 标志，则可以使用绑定参数，例如 bindparam()。
```
stmt.where(column.in_(bindparam("value", expanding=True)))
```
在这种调用形式中，表达式会渲染一个特殊的非 SQL 占位符表达式，其形式如下：
```
WHERE COL IN ([EXPANDING_value])
```
这个占位符表达式在语句执行时被拦截，并转换为之前说明的可变数量的绑定参数形式。如果语句执行如下：
```
connection.execute(stmt, {"value": [1, 2, 3]})
```
数据库将为每个值传递一个绑定参数
```
WHERE COL IN (?, ?, ?)
```
1.2 版本新增: 添加了“扩展”绑定参数

如果传递的是一个空列表，则会渲染一个特殊的“空列表”表达式，该表达式特定于正在使用的数据库。在 SQLite 上，这将是：
```
WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
```
1.3 版本新增: “扩展”绑定参数现在支持空列表

一个 select() 构造，通常是关联标量选择

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

在这种调用形式中，ColumnOperators.in_() 渲染如下：

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

参数：: other¶ – 字面量列表，select() 构造，或者 bindparam() 构造，其中包含设置为 True 的 bindparam.expanding 标志。

method sqlalchemy.orm.PropComparator.is_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.is_() 方法，属于 ColumnOperators

实现 IS 运算符。

通常，当与 None 值比较时，会自动生成 IS，它解析为 NULL。但是，如果要在某些平台上与布尔值进行比较，则显式使用 IS 可能是可取的。

另请参阅

method sqlalchemy.orm.PropComparator.is_distinct_from(other: Any) → ColumnOperators¶

继承自 ColumnOperators.is_distinct_from() 方法，属于 ColumnOperators

实现 IS DISTINCT FROM 运算符。

在大多数平台上渲染 “a IS DISTINCT FROM b”；在某些平台（如 SQLite）上可能渲染 “a IS NOT b”。

method sqlalchemy.orm.PropComparator.is_not(other: Any) → ColumnOperators¶

继承自 ColumnOperators.is_not() 方法，属于 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 值比较时，会自动生成 IS NOT，它解析为 NULL。但是，如果要在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能是可取的。

1.4 版本更改: is_not() 运算符在之前的版本中被重命名为 isnot()。之前的名称为了向后兼容仍然可用。

另请参阅

ColumnOperators.is_()

method sqlalchemy.orm.PropComparator.is_not_distinct_from(other: Any) → ColumnOperators¶

继承自 ColumnOperators.is_not_distinct_from() 方法，属于 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上渲染 “a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能渲染 “a IS b”。

1.4 版本更改: is_not_distinct_from() 运算符在之前的版本中被重命名为 isnot_distinct_from()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.isnot(other: Any) → ColumnOperators¶

继承自 ColumnOperators.isnot() 方法，属于 ColumnOperators

实现 IS NOT 运算符。

通常，当与 None 值比较时，会自动生成 IS NOT，它解析为 NULL。但是，如果要在某些平台上与布尔值进行比较，则显式使用 IS NOT 可能是可取的。

1.4 版本更改: is_not() 运算符在之前的版本中被重命名为 isnot()。之前的名称为了向后兼容仍然可用。

另请参阅

ColumnOperators.is_()

method sqlalchemy.orm.PropComparator.isnot_distinct_from(other: Any) → ColumnOperators¶

继承自 ColumnOperators.isnot_distinct_from() 方法，属于 ColumnOperators

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上渲染 “a IS NOT DISTINCT FROM b”；在某些平台（如 SQLite）上可能渲染 “a IS b”。

1.4 版本更改: is_not_distinct_from() 运算符在之前的版本中被重命名为 isnot_distinct_from()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.istartswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators¶

继承自 ColumnOperators.istartswith() 方法，属于 ColumnOperators

实现 istartswith 运算符，例如不区分大小写的 ColumnOperators.startswith() 版本。

生成一个 LIKE 表达式，该表达式针对字符串值的开头进行不区分大小写的匹配测试

lower(column) LIKE lower(<other>) || '%'

例如：

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

由于该运算符使用 LIKE，因此 "%" 和 "_" 通配符如果出现在 <other> 表达式中，也将表现得像通配符。对于文字字符串值，可以将 ColumnOperators.istartswith.autoescape 标志设置为 True，以对字符串值中出现的这些字符应用转义，以便它们匹配自身而不是作为通配符。或者，ColumnOperators.istartswith.escape 参数将建立给定的字符作为转义字符，当目标表达式不是文字字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。除非将 ColumnOperators.istartswith.autoescape 标志设置为 True，否则默认情况下不会转义 LIKE 通配符 % 和 _。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.istartswith("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.istartswith("foo/%bar", escape="^")
```
将渲染为：
```
lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '^'
```
该参数也可以与 ColumnOperators.istartswith.autoescape 结合使用
```
somecolumn.istartswith("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.startswith()

method sqlalchemy.orm.PropComparator.like(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.like() 方法，属于 ColumnOperators

实现 like 运算符。

在列上下文中，生成表达式

a LIKE other

例如：

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

参数：

other¶ – 要比较的表达式
escape¶ –
可选的转义字符，渲染 ESCAPE 关键字，例如：
```
somecolumn.like("foo/%bar", escape="/")
```

另请参阅

ColumnOperators.ilike()

method sqlalchemy.orm.PropComparator.match(other: Any, **kwargs: Any) → ColumnOperators¶

继承自 ColumnOperators.match() 方法，属于 ColumnOperators

实现数据库特定的 ‘match’ 运算符。

ColumnOperators.match() 尝试解析为后端提供的类似 MATCH 的函数或运算符。示例包括：

PostgreSQL - 渲染 x @@ plainto_tsquery(y)

2.0 版本更改: 现在 PostgreSQL 使用 plainto_tsquery() 而不是 to_tsquery()；为了与其他形式兼容，请参阅全文搜索。
MySQL - 渲染 MATCH (x) AGAINST (y IN BOOLEAN MODE)

另请参阅

match - MySQL 特定构造，具有其他功能。
Oracle Database - 渲染 CONTAINS(x, y)
其他后端可能会提供特殊的实现。
没有任何特殊实现的后端将运算符作为 “MATCH” 发出。例如，这与 SQLite 兼容。

method sqlalchemy.orm.PropComparator.not_ilike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.not_ilike() 方法，属于 ColumnOperators

实现 NOT ILIKE 运算符。

这等效于将否定与 ColumnOperators.ilike() 结合使用，即 ~x.ilike(y)。

1.4 版本更改: not_ilike() 运算符在之前的版本中被重命名为 notilike()。之前的名称为了向后兼容仍然可用。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.orm.PropComparator.not_in(other: Any) → ColumnOperators¶

继承自 ColumnOperators.not_in() 方法，属于 ColumnOperators

实现 NOT IN 运算符。

这等效于将否定与 ColumnOperators.in_() 结合使用，即 ~x.in_(y)。

如果 other 是一个空序列，则编译器会生成一个 “empty not in” 表达式。这默认为表达式 “1 = 1”，在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

1.4 版本更改: not_in() 运算符在之前的版本中被重命名为 notin_()。之前的名称为了向后兼容仍然可用。

1.2 版本更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.orm.PropComparator.not_like(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.not_like() 方法，属于 ColumnOperators

实现 NOT LIKE 运算符。

这等效于将否定与 ColumnOperators.like() 结合使用，即 ~x.like(y)。

1.4 版本更改: not_like() 运算符在之前的版本中被重命名为 notlike()。之前的名称为了向后兼容仍然可用。

另请参阅

ColumnOperators.ilike()

method sqlalchemy.orm.PropComparator.notilike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.notilike() 方法，属于 ColumnOperators

实现 NOT ILIKE 运算符。

这等效于将否定与 ColumnOperators.ilike() 结合使用，即 ~x.ilike(y)。

1.4 版本更改: not_ilike() 运算符在之前的版本中被重命名为 notilike()。之前的名称为了向后兼容仍然可用。

另请参阅

method sqlalchemy.orm.PropComparator.notin_(other: Any) → ColumnOperators¶

继承自 ColumnOperators.notin_() 方法，属于 ColumnOperators

实现 NOT IN 运算符。

这等效于将否定与 ColumnOperators.in_() 结合使用，即 ~x.in_(y)。

如果 other 是一个空序列，则编译器会生成一个 “empty not in” 表达式。这默认为表达式 “1 = 1”，在所有情况下都产生 true。 create_engine.empty_in_strategy 可用于更改此行为。

1.4 版本更改: not_in() 运算符在之前的版本中被重命名为 notin_()。之前的名称为了向后兼容仍然可用。

1.2 版本更改: ColumnOperators.in_() 和 ColumnOperators.not_in() 运算符现在默认情况下为空 IN 序列生成 “静态” 表达式。

另请参阅

ColumnOperators.in_()

method sqlalchemy.orm.PropComparator.notlike(other: Any, escape: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.notlike() 方法，源自 ColumnOperators

实现 NOT LIKE 运算符。

这等效于将否定与 ColumnOperators.like() 结合使用，即 ~x.like(y)。

1.4 版本更改: not_like() 运算符在之前的版本中被重命名为 notlike()。之前的名称为了向后兼容仍然可用。

另请参阅

连接到特定的子类型或 with_polymorphic() 实体

method sqlalchemy.orm.PropComparator.nulls_first() → ColumnOperators¶: 继承自 ColumnOperators.nulls_first() 方法，源自 ColumnOperators

生成一个针对父对象的 nulls_first() 子句。

在 1.4 版本中变更：nulls_first() 操作符在之前的版本中被重命名为 nullsfirst()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.nulls_last() → ColumnOperators¶: 继承自 ColumnOperators.nulls_last() 方法，源自 ColumnOperators

生成一个针对父对象的 nulls_last() 子句。

在 1.4 版本中变更：nulls_last() 操作符在之前的版本中被重命名为 nullslast()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.nullsfirst() → ColumnOperators¶: 继承自 ColumnOperators.nullsfirst() 方法，源自 ColumnOperators

生成一个针对父对象的 nulls_first() 子句。

在 1.4 版本中变更：nulls_first() 操作符在之前的版本中被重命名为 nullsfirst()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.nullslast() → ColumnOperators¶: 继承自 ColumnOperators.nullslast() 方法，源自 ColumnOperators

生成一个针对父对象的 nulls_last() 子句。

在 1.4 版本中变更：nulls_last() 操作符在之前的版本中被重命名为 nullslast()。之前的名称为了向后兼容仍然可用。

method sqlalchemy.orm.PropComparator.of_type(class_: _EntityType[Any]) → PropComparator[_T_co]¶

根据多态子类、with_polymorphic() 构造或 aliased() 构造重新定义此对象。

返回一个新的 PropComparator，可以从中评估进一步的条件。

例如：

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

参数：: class_¶ – 一个类或映射器，指示条件将针对此特定的子类。

另请参阅

使用关系在别名目标之间进行连接 - 在 ORM 查询指南中

method sqlalchemy.orm.PropComparator.op(opstring: str, precedence: int = 0, is_comparison: bool = False, return_type: Type[TypeEngine[Any]] | TypeEngine[Any] | None = None, python_impl: Callable[..., Any] | None = None) → Callable[[Any], Operators]¶

继承自 Operators.op() 方法，源自 Operators

生成一个通用操作符函数。

例如：

somecolumn.op("*")(5)

生成

somecolumn * 5

此函数也可用于显式地创建位运算符。例如：

somecolumn.op("&")(0xFF)

是 somecolumn 中的值的按位与。

参数：

opstring¶ – 一个字符串，它将作为此元素和传递给生成函数的表达式之间的中缀运算符输出。
precedence¶ –
数据库预期应用于 SQL 表达式中运算符的优先级。此整数值充当 SQL 编译器知道何时应在特定操作周围呈现显式括号的提示。当应用于另一个具有更高优先级的运算符时，较低的数字将导致表达式被括在括号中。默认值 0 低于除逗号 (,) 和 AS 运算符之外的所有运算符。值 100 将高于或等于所有运算符，而 -100 将低于或等于所有运算符。

另请参阅

我正在使用 op() 生成自定义运算符，但我的括号没有正确显示 - 关于 SQLAlchemy SQL 编译器如何呈现括号的详细描述
is_comparison¶ –
遗留参数；如果为 True，则该运算符将被视为“比较”运算符，即评估为布尔值 true/false 的运算符，例如 ==、> 等。提供此标志是为了使 ORM 关系可以在自定义连接条件中使用时确定该运算符是比较运算符。

使用 is_comparison 参数已被使用 Operators.bool_op() 方法所取代；这个更简洁的运算符会自动设置此参数，但也提供正确的 PEP 484 类型支持，因为返回的对象将表达“布尔”数据类型，即 BinaryExpression[bool]。
return_type¶ – 一个 TypeEngine 类或对象，它将强制此运算符生成的表达式的返回类型为该类型。默认情况下，指定了 Operators.op.is_comparison 的运算符将解析为 Boolean，而未指定的运算符将与左侧操作数的类型相同。
python_impl¶ –
一个可选的 Python 函数，可以以与此运算符在数据库服务器上运行时相同的方式评估两个 Python 值。对于 Python 内 SQL 表达式求值函数（例如 ORM 混合属性）以及用于在多行更新或删除后匹配会话中对象的 ORM “求值器”非常有用。

例如：
```
>>> expr = column("x").op("+", python_impl=lambda a, b: a + b)("y")
```
上述表达式的运算符也适用于非 SQL 左侧和右侧对象
```
>>> expr.operator(5, 10)
15
```
2.0 版本新增。

另请参阅

Operators.bool_op()

ColumnOperators.regexp_replace()

在连接条件中使用自定义运算符

method sqlalchemy.orm.PropComparator.operate(op: OperatorType, *other: Any, **kwargs: Any) → Operators¶

继承自 Operators.operate() 方法，源自 Operators

对参数执行操作。

这是最低级别的操作，默认情况下引发 NotImplementedError。

在子类上重写此方法可以允许将通用行为应用于所有操作。例如，重写 ColumnOperators 以将 func.lower() 应用于左侧和右侧

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

参数：

op¶ – 操作符可调用对象。
*other¶ – 操作的“另一侧”。对于大多数操作，将是单个标量。
**kwargs¶ – 修饰符。这些可以通过特殊运算符传递，例如 ColumnOperators.contains()。

attribute sqlalchemy.orm.PropComparator.property¶

返回与此 PropComparator 关联的 MapperProperty。

此处的返回值通常是 ColumnProperty 或 Relationship 的实例。

method sqlalchemy.orm.PropComparator.regexp_match(pattern: Any, flags: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.regexp_match() 方法，源自 ColumnOperators

实现数据库特定的“正则表达式匹配”运算符。

例如：

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

ColumnOperators.regexp_match() 尝试解析为后端提供的类似 REGEXP 的函数或运算符，但是可用的特定正则表达式语法和标志并非后端无关。

示例包括：

PostgreSQL - 渲染 x ~ y 或 x !~ y （当否定时）。
Oracle 数据库 - 渲染 REGEXP_LIKE(x, y)
SQLite - 使用 SQLite 的 REGEXP 占位符运算符并调用 Python re.match() 内置函数。
其他后端可能会提供特殊的实现。
没有任何特殊实现的后端将把运算符作为“REGEXP”或“NOT REGEXP”发出。这与 SQLite 和 MySQL 等兼容。

正则表达式支持目前已为 Oracle 数据库、PostgreSQL、MySQL 和 MariaDB 实现。SQLite 提供部分支持。第三方方言之间的支持可能会有所不同。

参数：

pattern¶ – 正则表达式模式字符串或列子句。
flags¶ – 要应用的任何正则表达式字符串标志，仅作为纯 Python 字符串传递。这些标志是后端特定的。某些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。在 PostgreSQL 中使用忽略大小写标志“i”时，将使用忽略大小写的正则表达式匹配运算符 ~* 或 !~*。

1.4 版本新增。

在 1.4.48 版本中变更，2.0.18：请注意，由于实现错误，“flags”参数以前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法正确处理缓存，并且已被删除；对于“flags”参数，应仅传递字符串，因为这些标志呈现为 SQL 表达式内的文字内联值。

另请参阅

method sqlalchemy.orm.PropComparator.regexp_replace(pattern: Any, replacement: Any, flags: str | None = None) → ColumnOperators¶

继承自 ColumnOperators.regexp_replace() 方法，源自 ColumnOperators

实现数据库特定的“正则表达式替换”运算符。

例如：

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

ColumnOperators.regexp_replace() 尝试解析为后端提供的类似 REGEXP_REPLACE 的函数，通常发出函数 REGEXP_REPLACE()。但是，可用的特定正则表达式语法和标志并非后端无关。

正则表达式替换支持目前已为 Oracle 数据库、PostgreSQL、MySQL 8 或更高版本以及 MariaDB 实现。第三方方言之间的支持可能会有所不同。

参数：

pattern¶ – 正则表达式模式字符串或列子句。
pattern¶ – 替换字符串或列子句。
flags¶ – 要应用的任何正则表达式字符串标志，仅作为纯 Python 字符串传递。这些标志是后端特定的。某些后端（如 PostgreSQL 和 MariaDB）可以选择将标志指定为模式的一部分。

1.4 版本新增。

在 1.4.48 版本中变更，2.0.18：请注意，由于实现错误，“flags”参数以前接受 SQL 表达式对象（例如列表达式）以及纯 Python 字符串。此实现无法正确处理缓存，并且已被删除；对于“flags”参数，应仅传递字符串，因为这些标志呈现为 SQL 表达式内的文字内联值。

另请参阅

ColumnOperators.regexp_match()

method sqlalchemy.orm.PropComparator.reverse_operate(op: OperatorType, other: Any, **kwargs: Any) → Operators¶

继承自 Operators.reverse_operate() 方法，源自 Operators

对参数执行反向操作。

用法与 operate() 相同。

method sqlalchemy.orm.PropComparator.startswith(other: Any, escape: str | None = None, autoescape: bool = False) → ColumnOperators¶

继承自 ColumnOperators.startswith() 方法，源自 ColumnOperators

实现 startswith 运算符。

生成一个 LIKE 表达式，用于测试字符串值开头的匹配项

column LIKE <other> || '%'

例如：

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

由于操作符使用 LIKE，通配符 "%" 和 "_" 如果出现在表达式中，也会表现得像通配符一样。对于字面字符串值，可以设置 ColumnOperators.startswith.autoescape 标志为 True，以便对字符串值中出现的这些字符应用转义，使其作为普通字符匹配，而不是作为通配符。或者，ColumnOperators.startswith.escape 参数将建立一个给定的字符作为转义字符，当目标表达式不是字面字符串时，这可能很有用。

参数：

other¶ – 要比较的表达式。这通常是一个纯字符串值，但也可能是一个任意的 SQL 表达式。LIKE 通配符 % 和 _ 默认情况下不会被转义，除非 ColumnOperators.startswith.autoescape 标志设置为 True。
autoescape¶ –
布尔值；当为 True 时，在 LIKE 表达式中建立一个转义字符，然后将其应用于比较值中所有出现的 "%"、"_" 和转义字符本身，比较值被假定为字面字符串而不是 SQL 表达式。

例如，以下表达式：
```
somecolumn.startswith("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE :param || '%' ESCAPE '/'
```
参数 :param 的值为 "foo/%bar"。
escape¶ –
一个字符，当给定该字符时，将使用 ESCAPE 关键字进行渲染，以将该字符建立为转义字符。然后可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身而不是通配符。

例如，以下表达式：
```
somecolumn.startswith("foo/%bar", escape="^")
```
将渲染为：
```
somecolumn LIKE :param || '%' ESCAPE '^'
```
该参数也可以与 ColumnOperators.startswith.autoescape 结合使用
```
somecolumn.startswith("foo%bar^bat", escape="^", autoescape=True)
```
在上述示例中，给定的字面参数将在传递到数据库之前转换为 "foo^%bar^^bat"。

另请参阅

ColumnOperators.endswith()

ColumnOperators.contains()

attribute sqlalchemy.orm.PropComparator.timetuple: Literal[None] = None¶: 继承自 ColumnOperators.timetuple 属性，该属性属于 ColumnOperators

Hack，允许在 LHS 上比较 datetime 对象。

class sqlalchemy.orm.Relationship¶

描述一个对象属性，该属性包含与相关数据库表对应的单个项或项列表。

公共构造函数是 relationship() 函数。

另请参阅

关系配置

在版本 2.0 中变更：添加了 Relationship 作为 RelationshipProperty 的声明式兼容子类。

类签名

class sqlalchemy.orm.Relationship (sqlalchemy.orm.RelationshipProperty, sqlalchemy.orm.base._DeclarativeMapped)

class sqlalchemy.orm.RelationshipDirection¶

枚举，指示 RelationshipProperty 的“方向”。

RelationshipDirection 可以从 RelationshipProperty 的 Relationship.direction 属性访问。

成员

MANYTOMANY, MANYTOONE, ONETOMANY

类签名

class sqlalchemy.orm.RelationshipDirection (enum.Enum)

attribute sqlalchemy.orm.RelationshipDirection.MANYTOMANY = 3¶

表示 relationship() 的多对多方向。

此符号通常由内部使用，但也可能在某些 API 功能中公开。

attribute sqlalchemy.orm.RelationshipDirection.MANYTOONE = 2¶

表示 relationship() 的多对一方向。

此符号通常由内部使用，但也可能在某些 API 功能中公开。

attribute sqlalchemy.orm.RelationshipDirection.ONETOMANY = 1¶

表示 relationship() 的一对多方向。

此符号通常由内部使用，但也可能在某些 API 功能中公开。

class sqlalchemy.orm.RelationshipProperty¶

描述一个对象属性，该属性包含与相关数据库表对应的单个项或项列表。

公共构造函数是 relationship() 函数。

另请参阅

关系配置

成员

__eq__(), __init__(), __ne__(), adapt_to_entity(), and_(), any(), contains(), entity, has(), in_(), mapper, of_type(), cascade, cascade_iterator(), declarative_scan(), do_init(), entity, instrument_class(), mapper, merge()

类签名

class sqlalchemy.orm.RelationshipProperty (sqlalchemy.orm._IntrospectsAnnotations, sqlalchemy.orm.StrategizedProperty, sqlalchemy.log.Identified)

class Comparator¶

为 RelationshipProperty 属性生成布尔值、比较和其它运算符。

有关 ORM 级别运算符定义的简要概述，请参阅 PropComparator 的文档。

另请参阅

QueryableAttribute.info

类签名

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

method sqlalchemy.orm.RelationshipProperty.Comparator.__eq__(other: Any) → ColumnElement[bool]¶

实现 == 运算符。

在多对一的上下文中，例如

MyClass.some_prop == <some object>

这将通常生成如下子句：

mytable.related_id == <some id>

其中 <some id> 是给定对象的主键。

== 运算符为非多对一比较提供部分功能

不支持与集合进行比较。请使用 Comparator.contains()。
与标量一对多比较时，将生成一个子句，该子句将父对象中的目标列与给定的目标进行比较。
与标量多对多比较时，关联表的别名也将被呈现，形成自然连接，该连接是查询主体的组成部分。这不适用于超出简单 AND 连接的比较查询，例如使用 OR 的查询。对于更全面的非多对一标量成员资格测试，请使用显式连接、外连接或 Comparator.has()。
在一对多或多对多上下文中，与 None 进行比较会生成 NOT EXISTS 子句。

method sqlalchemy.orm.RelationshipProperty.Comparator.__init__(prop: RelationshipProperty[_PT], parentmapper: _InternalEntityType[Any], adapt_to_entity: AliasedInsp[Any] | None = None, of_type: _EntityType[_PT] | None = None, extra_criteria: Tuple[ColumnElement[bool], ...] = ())¶: Comparator 的构造是 ORM 属性机制的内部操作。

method sqlalchemy.orm.RelationshipProperty.Comparator.__ne__(other: Any) → ColumnElement[bool]¶

实现 != 运算符。

在多对一的上下文中，例如

MyClass.some_prop != <some object>

这将通常生成如下子句：

mytable.related_id != <some id>

其中 <some id> 是给定对象的主键。

!= 运算符为非多对一比较提供部分功能

不支持与集合进行比较。请结合 not_() 使用 Comparator.contains()。
与标量一对多比较时，将生成一个子句，该子句将父对象中的目标列与给定的目标进行比较。
与标量多对多比较时，关联表的别名也将被呈现，形成自然连接，该连接是查询主体的组成部分。这不适用于超出简单 AND 连接的比较查询，例如使用 OR 的查询。对于更全面的非多对一标量成员资格测试，请结合 not_() 使用显式连接、外连接或 Comparator.has()。
在一对多或多对多上下文中，与 None 进行比较会生成 EXISTS 子句。

method sqlalchemy.orm.RelationshipProperty.Comparator.adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → RelationshipProperty.Comparator[Any]¶: 返回此 PropComparator 的副本，该副本将使用给定的 AliasedInsp 来生成相应的表达式。

method sqlalchemy.orm.RelationshipProperty.Comparator.and_(*criteria: _ColumnExpressionArgument[bool]) → PropComparator[Any]¶

添加 AND 条件。

有关示例，请参阅 PropComparator.and_()。

1.4 版本新增。

method sqlalchemy.orm.RelationshipProperty.Comparator.any(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]¶

生成一个表达式，该表达式使用 EXISTS 根据特定条件测试集合。

如下表达式：

session.query(MyClass).filter(
    MyClass.somereference.any(SomeRelated.x == 2)
)

将生成如下查询：

SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE related.my_id=my_table.id
AND related.x=2)

由于 Comparator.any() 使用关联子查询，因此当与大型目标表进行比较时，其性能远不如使用连接。

Comparator.any() 特别适用于测试空集合

session.query(MyClass).filter(~MyClass.somereference.any())

将生成

SELECT * FROM my_table WHERE
NOT (EXISTS (SELECT 1 FROM related WHERE
related.my_id=my_table.id))

Comparator.any() 仅对集合有效，即 relationship() 设置了 uselist=True。对于标量引用，请使用 Comparator.has()。

method sqlalchemy.orm.RelationshipProperty.Comparator.contains(other: _ColumnExpressionArgument[Any], **kwargs: Any) → ColumnElement[bool]¶

返回一个简单表达式，用于测试集合是否包含特定项。

Comparator.contains() 仅对集合有效，即 relationship() 实现了一对多或多对多关系，并设置了 uselist=True。

在简单的一对多上下文中，如下表达式：

MyClass.contains(other)

生成如下子句：

mytable.id == <some id>

其中 <some id> 是 other 上外键属性的值，它引用其父对象的主键。由此可见，Comparator.contains() 在与简单的一对多操作一起使用时非常有用。

对于多对多操作，Comparator.contains() 的行为有更多注意事项。关联表将在语句中呈现，产生“隐式”连接，即在 FROM 子句中包含多个表，这些表在 WHERE 子句中被等同

query(MyClass).filter(MyClass.contains(other))

生成如下查询：

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>

其中 <some id> 将是 other 的主键。从上面可以看出，当用于超出简单 AND 连接的查询（例如由 OR 连接的多个 Comparator.contains() 表达式）时，Comparator.contains() 将不适用于多对多集合。在这种情况下，需要使用子查询或显式“外连接”来代替。有关性能较低的替代方案，请参阅 Comparator.any()（使用 EXISTS），或参阅 Query.outerjoin() 以及连接，以获取有关构造外连接的更多详细信息。

kwargs 可能会被此运算符忽略，但 API 一致性需要它。

attribute sqlalchemy.orm.RelationshipProperty.Comparator.entity: _InternalEntityType[_PT]¶

此 Comparator 引用的目标实体。

这可以是 Mapper 或 AliasedInsp 对象。

这是 relationship() 的“目标”或“远程”端。

method sqlalchemy.orm.RelationshipProperty.Comparator.has(criterion: _ColumnExpressionArgument[bool] | None = None, **kwargs: Any) → ColumnElement[bool]¶

生成一个表达式，该表达式使用 EXISTS 根据特定条件测试标量引用。

如下表达式：

session.query(MyClass).filter(
    MyClass.somereference.has(SomeRelated.x == 2)
)

将生成如下查询：

SELECT * FROM my_table WHERE
EXISTS (SELECT 1 FROM related WHERE
related.id==my_table.related_id AND related.x=2)

由于 Comparator.has() 使用关联子查询，因此当与大型目标表进行比较时，其性能远不如使用连接。

Comparator.has() 仅对标量引用有效，即 relationship() 设置了 uselist=False。对于集合引用，请使用 Comparator.any()。

method sqlalchemy.orm.RelationshipProperty.Comparator.in_(other: Any) → NoReturn¶: 生成 IN 子句 - 目前尚未为基于 relationship() 的属性实现此功能。

attribute sqlalchemy.orm.RelationshipProperty.Comparator.mapper: Mapper[_PT]¶

此 Comparator 引用的目标 Mapper。

这是 relationship() 的“目标”或“远程”端。

method sqlalchemy.orm.RelationshipProperty.Comparator.of_type(class_: _EntityType[Any]) → PropComparator[_PT]¶

根据多态子类重新定义此对象。

有关示例，请参阅 PropComparator.of_type()。

attribute sqlalchemy.orm.RelationshipProperty.cascade¶: 返回此 RelationshipProperty 的当前级联设置。

方法 sqlalchemy.orm.RelationshipProperty.cascade_iterator(type_: str, state: InstanceState[Any], dict_: _InstanceDict, visited_states: Set[InstanceState[Any]], halt_on: Callable[[InstanceState[Any]], bool] | None = None) → Iterator[Tuple[Any, Mapper[Any], InstanceState[Any], _InstanceDict]]¶

迭代处理与给定实例相关的实例，以进行特定的“级联”操作，从这个 MapperProperty 开始。

返回一个迭代器，包含 3 元组 (instance, mapper, state)。

请注意，在调用 cascade_iterator 之前，首先检查此 MapperProperty 上的“cascade”集合是否为给定类型。

此方法通常仅适用于 Relationship。

方法 sqlalchemy.orm.RelationshipProperty.declarative_scan(decl_scan: _ClassScanMapperConfig, registry: _RegistryType, cls: Type[Any], originating_module: str | None, key: str, mapped_container: Type[Mapped[Any]] | None, annotation: _AnnotationScanType | None, extracted_mapped_annotation: _AnnotationScanType | None, is_dataclass_field: bool) → None¶: 在早期声明式扫描时执行特定于类的初始化。

2.0 版本新增。

方法 sqlalchemy.orm.RelationshipProperty.do_init() → None¶

执行子类特定的初始化，mapper 创建后的步骤。

这是一个由 MapperProperty 对象的 init() 方法调用的模板方法。

属性 sqlalchemy.orm.RelationshipProperty.entity¶: 返回目标映射实体，它是指由此 RelationshipProperty 引用的类或别名类的 inspect()。

方法 sqlalchemy.orm.RelationshipProperty.instrument_class(mapper: Mapper[Any]) → None¶

Mapper 调用的钩子，用于初始化由此 MapperProperty 管理的类属性的 instrumentation。

此处的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

此步骤是设置 InstrumentedAttribute 的两个步骤中的第一步，并在 mapper 设置过程的早期调用。

第二步通常是 init_class_attribute 步骤，通过 post_instrument_class() 钩子从 StrategizedProperty 调用。此步骤将额外的状态分配给 InstrumentedAttribute（特别是“impl”），这在 MapperProperty 确定它需要执行哪种持久性管理（例如，标量、对象、集合等）之后确定。

属性 sqlalchemy.orm.RelationshipProperty.mapper¶: 返回此 RelationshipProperty 的目标 Mapper。

方法 sqlalchemy.orm.RelationshipProperty.merge(session: Session, source_state: InstanceState[Any], source_dict: _InstanceDict, dest_state: InstanceState[Any], dest_dict: _InstanceDict, load: bool, _recursive: Dict[Any, object], _resolve_conflict_map: Dict[_IdentityKeyType[Any], object]) → None¶: 将此 MapperProperty 表示的属性从源对象合并到目标对象。

类 sqlalchemy.orm.SQLORMExpression¶

一种类型，可用于指示在 SQL 表达式构造的上下文中，任何 ORM 级别的属性或对象来代替另一个。

SQLORMExpression 扩展自 Core SQLColumnExpression，添加了 ORM 特定的额外 SQL 方法，例如 PropComparator.of_type()，并且是 InstrumentedAttribute 基类的一部分。它可以在 PEP 484 类型提示中使用，以指示应表现为 ORM 级别属性表达式的参数或返回值。

2.0.0b4 版本新增。

类签名

类 sqlalchemy.orm.SQLORMExpression (sqlalchemy.orm.base.SQLORMOperations, sqlalchemy.sql.expression.SQLColumnExpression, sqlalchemy.util.langhelpers.TypingOnly)

类 sqlalchemy.orm.Synonym¶

SynonymProperty 类的声明式前端。

公共构造函数是 synonym() 函数。

在 2.0 版本中变更: 添加 Synonym 作为 SynonymProperty 的声明式兼容子类

另请参阅

同义词 - 同义词概述

类签名

类 sqlalchemy.orm.Synonym (sqlalchemy.orm.descriptor_props.SynonymProperty, sqlalchemy.orm.base._DeclarativeMapped)

类 sqlalchemy.orm.SynonymProperty¶

将属性名称表示为映射属性的同义词，这样该属性将镜像另一个属性的值和表达式行为。

Synonym 是使用 synonym() 函数构造的。

另请参阅

同义词 - 同义词概述

成员

doc, info, key, parent, set_parent(), uses_objects

类签名

类 sqlalchemy.orm.SynonymProperty (sqlalchemy.orm.descriptor_props.DescriptorProperty)

属性 sqlalchemy.orm.SynonymProperty.doc: str | None¶: 继承自 DescriptorProperty.doc 属性，来自 DescriptorProperty

可选的文档字符串

属性 sqlalchemy.orm.SynonymProperty.info: _InfoType¶

继承自 MapperProperty.info 属性，来自 MapperProperty

与对象关联的信息字典，允许用户定义的数据与此 InspectionAttr 关联。

该字典在首次访问时生成。或者，它可以作为构造函数参数指定给 column_property()、relationship() 或 composite() 函数。

另请参阅

Mapper.all_orm_descriptors

属性 sqlalchemy.orm.SynonymProperty.key: str¶: 继承自 MapperProperty.key 属性，来自 MapperProperty

类属性的名称

属性 sqlalchemy.orm.SynonymProperty.parent: Mapper[Any]¶: 继承自 MapperProperty.parent 属性，来自 MapperProperty

管理此属性的 Mapper。

方法 sqlalchemy.orm.SynonymProperty.set_parent(parent: Mapper[Any], init: bool) → None¶

设置引用此 MapperProperty 的父 mapper。

某些子类会覆盖此方法，以在首次知道 mapper 时执行额外的设置。

属性 sqlalchemy.orm.SynonymProperty.uses_objects¶

类 sqlalchemy.orm.QueryContext¶

类 default_load_options¶: 类签名

类 sqlalchemy.orm.QueryContext.default_load_options (sqlalchemy.sql.expression.Options)

类 sqlalchemy.orm.QueryableAttribute¶

代表 MapperProperty 对象拦截属性事件的 descriptor 对象基类。实际的 MapperProperty 可通过 QueryableAttribute.property 属性访问。

另请参阅

InstrumentedAttribute

MapperProperty

Mapper.attrs

成员

adapt_to_entity(), and_(), expression, info, is_attribute, of_type(), operate(), parent, reverse_operate()

类签名

类 sqlalchemy.orm.QueryableAttribute (sqlalchemy.orm.base._DeclarativeMapped, sqlalchemy.orm.base.SQLORMExpression, sqlalchemy.orm.base.InspectionAttr, sqlalchemy.orm.PropComparator, sqlalchemy.sql.roles.JoinTargetRole, sqlalchemy.sql.roles.OnClauseRole, sqlalchemy.sql.expression.Immutable, sqlalchemy.sql.cache_key.SlotsMemoizedHasCacheKey, sqlalchemy.util.langhelpers.MemoizedSlots, sqlalchemy.event.registry.EventTarget)

方法 sqlalchemy.orm.QueryableAttribute.adapt_to_entity(adapt_to_entity: AliasedInsp[Any]) → Self¶: 返回此 PropComparator 的副本，该副本将使用给定的 AliasedInsp 来生成相应的表达式。

方法 sqlalchemy.orm.QueryableAttribute.and_(*clauses: _ColumnExpressionArgument[bool]) → QueryableAttribute[bool]¶

为此关系属性表示的 ON 子句添加其他条件。

例如：

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

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

1.4 版本新增。

另请参阅

将关系与自定义 ON 条件结合使用

向加载器选项添加条件

with_loader_criteria()

属性 sqlalchemy.orm.QueryableAttribute.expression: ColumnElement[_T_co]¶

由此 QueryableAttribute 表示的 SQL 表达式对象。

这通常是 ColumnElement 子类的实例，表示列表达式。

属性 sqlalchemy.orm.QueryableAttribute.info¶

返回底层 SQL 元素的 ‘info’ 字典。

此处的行为如下

如果属性是列映射属性，即 ColumnProperty，它直接映射到模式级别的 Column 对象，则此属性将返回与核心级别的 Column 对象关联的 SchemaItem.info 字典。
如果属性是 ColumnProperty，但映射到除 Column 之外的任何其他类型的 SQL 表达式，则该属性将引用直接与 ColumnProperty 关联的 MapperProperty.info 字典，假设 SQL 表达式本身没有自己的 .info 属性（除非用户定义的 SQL 构造定义了一个）。
如果属性引用任何其他类型的 MapperProperty，包括 Relationship，则该属性将引用与该 MapperProperty 关联的 MapperProperty.info 字典。
要无条件地访问 MapperProperty.info 字典，包括对于直接与 Column 关联的 ColumnProperty，可以使用 QueryableAttribute.property 属性引用该属性，如 MyClass.someattribute.property.info。

另请参阅