ORM 内部结构¶

create_row_processor（）、columns_to_assign、declarative_scan（）、do_init（）、get_history（）、instrument_class（）mapper_property_to_assign

类签名

类 sqlalchemy.orm.ColumnProperty.Comparator （ sqlalchemy.util.langhelpers.MemoizedSlots ， sqlalchemy.orm.PropComparator）

属性 sqlalchemy.orm.ColumnProperty.Comparator. 表达式： Sequence[NamedColumn[Any]]¶

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

在 1.3.17 版本加入.

另请参阅

将类映射到多个表 - 用法示例

method sqlalchemy.orm.ColumnProperty.Comparator. operate（op： OperatorType， *other： Any， **kwargs： Any→ ColumnElement （列元素）[任意]¶

对参数进行作。

这是最低级别的作，加注 NotImplementedError 的 MethodS 错误。

在子类上覆盖 this 可以允许将通用行为应用于所有作。例如，重写 ColumnOperators 要将 func.lower（） 应用于左侧和右侧：

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

参数

op¶- 运算符可调用。
other¶ ——作的 'other' 端。对于大多数作，将是单个标量。
**kwargs¶ —— 修饰符。这些可以通过特殊运算符（如 ColumnOperators.contains（）））传递。

方法 sqlalchemy.orm.ColumnProperty.Comparator. reverse_operate（op： OperatorType， other： Any， **kwargs： Any→ ColumnElement[任意]¶

Reverse 对参数进行作。

用法与 operate（） 相同。

属性 sqlalchemy.orm.ColumnProperty. columns_to_assign¶

方法 sqlalchemy.orm.ColumnProperty. declarative_scan（decl_scan：_ClassScanMapperConfig，注册表：_RegistryType，cls：类型 [Any]， originating_module：strNone， key： str， mapped_container：Type[Mapped[Any]]None， annotation：_AnnotationScanTypeNone， extracted_mapped_annotation：_AnnotationScanTypeNone， is_dataclass_field： bool）→ 无¶: 在早期声明性扫描时执行特定于类的初始化。

2.0 版的新Function。

方法 sqlalchemy.orm.ColumnProperty. do_init（）→ 无¶

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

这是 MapperProperty 调用的模板方法 Object 的 init（）方法。

属性 sqlalchemy.orm.ColumnProperty. 表达式¶

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

例如：

class File(Base):
    # ...

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

另请参阅

在映射时根据列属性进行撰写

方法 sqlalchemy.orm.ColumnProperty. instrument_class（mapper： Mapper[Any]）→ 无¶

Mapper 调用属性的 Hook，以启动由此 MapperProperty 管理的类属性的检测。

这里的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

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

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

属性 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]）→ 无¶: 合并此 MapperProperty 表示的属性 from source to destination 对象。

类 sqlalchemy.orm 中。复合¶

CompositeProperty 的声明兼容前端类。

Public 构造函数是 composite（） 函数。

在 2.0 版更改：添加了 Composite 作为 CompositeProperty 的声明性兼容子类。

另请参阅

复合列类型

类签名

类 sqlalchemy.orm.Composite （ sqlalchemy.orm.descriptor_props.CompositeProperty ， sqlalchemy.orm.base._DeclarativeMapped ）

类 sqlalchemy.orm 中。CompositeProperty（复合属性）¶

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

CompositeProperty 是使用 composite（） 构造的功能。

另请参阅

复合列类型

成员

类签名

类 sqlalchemy.orm.CompositeProperty （sqlalchemy.orm._MapsColumns， sqlalchemy.orm._IntrospectsAnnotations ， sqlalchemy.orm.descriptor_props.DescriptorProperty ）

类 Comparator¶

生成 boolean、comparison 和其他运算符 复合属性。

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

另请参阅

PropComparator （属性比较器）

Mapper.all_orm_descriptors

类签名

类 sqlalchemy.orm.CompositeProperty.Comparator （sqlalchemy.orm.PropComparator）

类 CompositeBundle¶

类签名

类 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[[行[任意]]，任意]¶

为此 Bundle 生成 “row processing” 函数。

可以被子类覆盖，以便在获取结果时提供自定义行为。该方法在查询执行时传递 statement 对象和一组“row processor”函数;当给定 result 行时，这些处理器函数将返回单个属性值，然后可以将其调整为任何类型的 return 数据结构。

下面的示例说明了如何替换通常的 Row return 结构：

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"])

属性 sqlalchemy.orm.CompositeProperty. columns_to_assign¶

方法 sqlalchemy.orm.CompositeProperty. declarative_scan（decl_scan：_ClassScanMapperConfig，注册表：_RegistryType，cls：类型 [Any]， originating_module：strNone， key： str， mapped_container：Type[Mapped[Any]]None， annotation：_AnnotationScanTypeNone， extracted_mapped_annotation：_AnnotationScanTypeNone， is_dataclass_field： bool）→ 无¶: 在早期声明性扫描时执行特定于类的初始化。

2.0 版的新Function。

方法 sqlalchemy.orm.CompositeProperty. do_init（）→ 无¶: 在 Composite 之后发生的初始化已与其父映射器关联。

方法 sqlalchemy.orm.CompositeProperty. get_history（state： InstanceState[Any]， dict_： _InstanceDict， passive： PassiveFlag = symbol（'PASSIVE_OFF'））→ 历史¶: 为使用 attributes.get_history（）的用户空间代码提供。

方法 sqlalchemy.orm.CompositeProperty. instrument_class（mapper： Mapper[Any]）→ 无¶

Mapper 调用属性的 Hook，以启动由此 MapperProperty 管理的类属性的检测。

这里的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

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

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

属性 sqlalchemy.orm.CompositeProperty. mapper_property_to_assign¶

类 sqlalchemy.orm 中。AttributeEventToken（属性事件令牌）¶

在属性事件链的整个过程中传播的标记。

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

Event 对象在处理 AttributeEvents.append（） 等事件时作为发起方参数发送。 AttributeEvents.set（） 和 AttributeEvents.remove（）的 AttributeEvents.remove（） 进行设置。

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

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

属性 impl：: AttributeImpl 是当前事件发起方。
属性 op：: 符号 OP_APPEND， OP_REMOVE， OP_REPLACE 或 OP_BULK_REPLACE，指示源作。

类 sqlalchemy.orm 中。身份映射¶

成员

check_modified（）

方法 sqlalchemy.orm.IdentityMap 中。check_modified（）→ bool ¶: 如果存在任何 InstanceStates 已标记为 'modified'，则返回 True。

类 sqlalchemy.orm 中。InspectionAttr 的

一个基类，应用于与 inspect（） 函数可以返回的事物相关的所有 ORM 对象和属性。

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

成员

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

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

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

另请参阅

HybridExtensionType

AssociationProxyExtensionType

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

属性 sqlalchemy.orm.InspectionAttr. is_attribute = False¶

如果此对象是 Python 描述符，则为 True。

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

另请参阅

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

属性 sqlalchemy.orm.InspectionAttr. is_clause_element = False¶: 如果此对象是 ClauseElement 的 ClauseElement。

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

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

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

属性 sqlalchemy.orm.InspectionAttr. is_selectable = False¶: 如果此对象是 可选。

类 sqlalchemy.orm 中。InspectionAttrInfo¶

将 .info 属性添加到 InspectionAttr。

InspectionAttr 与 InspectionAttrInfo 的基本原理是前者作为指定 __slots__;这实质上是一个实现工件。

成员

信息

类签名

类 sqlalchemy.orm.InspectionAttrInfo （ sqlalchemy.orm.base.InspectionAttr ）

属性 sqlalchemy.orm.InspectionAttrInfo. 信息¶

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

字典是在首次访问时生成的。或者它可以指定为 column_property（）、relationship（） 或 复合（） 功能。

另请参阅

QueryableAttribute.info

InstanceState.async_session

类 sqlalchemy.orm 中。实例状态¶

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

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

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'])

另请参阅

检查 Map 实例

成员

async_session、attrs、callables、deleted、detached、dict、expired、expired_attributes、has_identity、identity、identity_key、is_instance、mapper、modified、object、待处理、持久、会话、瞬态、已卸载、 unloaded_expirable、未修改、 unmodified_intersection（）、 was_deleted

类签名

class sqlalchemy.orm.InstanceState （ sqlalchemy.orm.base.InspectionAttrInfo ， typing.通用）

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。async_session¶

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

仅当 sqlalchemy.ext.asyncio API 用于此 ORM 对象。返回的 AsyncSession 对象将是 Session 对象，该对象将从 InstanceState.session 属性 InstanceState 的 InstanceState 中。

在 1.4.18 版本加入.

另请参阅

异步 I/O （asyncio）

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。属性¶

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

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。可调用对象： Dict[str， Callable[[InstanceState[_O]， PassiveFlag]， Any]] = {}¶

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

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

以前，callables 还用于通过在此字典中存储指向 InstanceState 本身的链接来指示过期的属性。此角色现在由 expired_attributes 集处理。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。已删除¶

如果对象已删除，则返回 True。

保证处于 deleted 状态的对象不在其父对象的Session.identity_map内 会话;但是，如果 Session 的事务被回滚，则对象将恢复到 Persistent 状态和 Identity Map。

注意

InstanceState.deleted 属性是指对象在 “persistent” 和 “detached” 状态之间出现的特定状态;分离对象后， InstanceState.deleted 属性不再返回正确;为了检测状态已被删除，无论对象是否与 Session 中，请使用 InstanceState.was_deleted 访问。

另请参阅

对象状态 Quickie 简介

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。detached（分离）¶: 如果对象已分离，则返回 True。

另请参阅

对象状态 Quickie 简介

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。dict¶

返回对象使用的实例 dict。

在正常情况下，这始终与 Map 对象的 __dict__ 属性同义，除非已配置替代 instrumentation system。

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。过期：bool = False¶: 当 True 时，对象已过期。

另请参阅

刷新 / 过期

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。expired_attributes： Set[str]¶

由 manager 的延迟标量加载器加载的 '过期' 键集，假设没有待处理的更改。

另请参阅在发生刷新作时与此集相交的未修改集合。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。has_identity¶

如果此对象具有身份密钥，则返回 True。

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。身份¶

返回映射对象的映射标识。这是 ORM 保留的主键身份它总是可以直接传递给 Query.get（） 的

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

注意

临时或待处理的对象在刷新之前没有映射的身份，即使其属性包括主键值也是如此。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。identity_key¶

返回映射对象的身份键。

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

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。映射器¶: 返回用于此映射对象的 Mapper。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。修改： bool = False¶: 如果为 True，则对象被修改。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。对象¶

返回 this 表示的映射对象 InstanceState 的 InstanceState 中。

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。待处理¶: 如果对象处于待处理状态，则返回 True。

另请参阅

对象状态 Quickie 简介

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。持久化¶

如果对象是持久性的，则返回 True。

处于持久状态的对象保证在其父对象的Session.identity_map内 会话。

另请参阅

对象状态 Quickie 简介

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。会话¶

返回此实例的拥有会话，如果没有可用，则返回 None。

请注意，在某些情况下，此处的结果可能会有所不同来自 OBJ 在 Session 中的记录;已删除的对象将报告为 Not in session，但是如果事务仍在进行中，则此属性仍将引用该会话。在正常情况下，只有当事务完成时，对象才会完全分离。

另请参阅

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。瞬态¶: 如果对象是瞬态的，则返回 True。

另请参阅

对象状态 Quickie 简介

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。unloaded（已卸载）¶

返回没有 loaded 值的键集。

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

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。unloaded_expirable¶

与 InstanceState.unloaded 同义。

2.0 版后已移除：该 InstanceState.unloaded_expirable 属性已弃用。请使用 InstanceState.unloaded。

此属性在某个时候作为特定于 implementation-detail 添加，应被视为私有。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。未修改¶: 返回没有未提交更改的键集

方法 sqlalchemy.orm.InstanceState 的 InstanceState 中。unmodified_intersection（键： Iterable[str]）→ Set[str]¶: 返回 self.unmodified.intersection（keys）。

属性 sqlalchemy.orm.InstanceState 的 InstanceState 中。was_deleted¶

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

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

另请参阅

InstanceState.deleted - 引用“已删除”状态

was_deleted（） - 独立函数

对象状态 Quickie 简介

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

另请参阅

InstrumentedAttribute （检测属性）

Mapper属性

Mapper.all_orm_descriptors

Mapper.attrs

类签名

类 sqlalchemy.orm.InstrumentedAttribute （ sqlalchemy.orm.QueryableAttribute ）

类 sqlalchemy.orm 中。LoaderCallableStatus 状态¶

一个枚举。

成员

ATTR_EMPTY、ATTR_WAS_SET、NEVER_SET、NO_VALUE、PASSIVE_CLASS_MISMATCH PASSIVE_NO_RESULT

类签名

class sqlalchemy.orm.LoaderCallableStatus （enum.枚举）

属性 sqlalchemy.orm.LoaderCallableStatus. ATTR_EMPTY = 3¶: 内部使用的 symbol 表示属性没有可调用对象。

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

属性 sqlalchemy.orm.LoaderCallableStatus. NEVER_SET = 4¶: NO_VALUE 的同义词

在 1.4 版本发生变更： NEVER_SET 与 NO_VALUE 合并

属性 sqlalchemy.orm.LoaderCallableStatus. NO_VALUE = 4¶: 可以作为属性的“上一个”值放置的符号，表示在修改属性时没有为属性加载任何值，标志表示我们不应加载它。

属性 sqlalchemy.orm.LoaderCallableStatus. PASSIVE_CLASS_MISMATCH = 1¶: 表示对象在本地存在给定主键标识，但它不属于请求的类的符号。因此，返回值为 None，不应发出任何 SQL。

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

类 sqlalchemy.orm 中。映射¶

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

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

Mapped 最突出的用途是 Mapper 配置的声明式 Mapping 形式，其中显式使用它驱动 ORM 属性的配置，例如 mapped_class（） 和 relationship（）的 Relationship（） 进行匹配。

另请参阅

使用声明性基类

使用 mapped_column（）的声明式表

提示

Mapped 类表示由 Mapper 类直接处理的属性。它不包括其他作为扩展提供的 Python 描述符类，包括 Hybrid Attributes 和 Association Proxy 的 Alpha S S S Alpha S虽然这些系统仍然使用特定于 ORM 的超类和结构，但它们没有由 Mapper 的 Mapper 中，而是在类上访问它们时提供自己的功能。

在 1.4 版本加入.

类签名

类 sqlalchemy.orm.Mapped （ sqlalchemy.orm.base.SQLORMExpression ， sqlalchemy.orm.base.ORMDescriptor ， sqlalchemy.orm.base._MappedAnnotationBase sqlalchemy.sql.roles.DDLConstraintColumnRole ，）

类 sqlalchemy.orm 中。MappedColumn¶

映射类上的单个 Column。

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

要构造 MappedColumn 对象，请使用 mapped_column（） 构造函数。

2.0 版的新Function。

类签名

类 sqlalchemy.orm.MappedColumn （ sqlalchemy.orm._IntrospectsAnnotations ， sqlalchemy.orm._MapsColumns， sqlalchemy.orm.base._DeclarativeMapped ）

类 sqlalchemy.orm 中。MapperProperty（映射器属性）¶

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

MapperProperty 最常见的出现是映射的 Column，它在映射中表示为 ColumnProperty 的实例，以及对 relationship（） 生成的另一个类的引用。在 Map 中表示为 关系。

成员

cascade_iterator（）， class_attribute，比较器， create_row_processor（）， do_init（）， doc， info， init（）， instrument_class（）， is_property， key， merge（）， parent， post_instrument_class（）、set_parent（）、setup（）

类签名

类 sqlalchemy.orm.MapperProperty （ sqlalchemy.sql.cache_key.HasCacheKey ， sqlalchemy.orm._DCAttributeOptions sqlalchemy.orm.base._MappedAttribute sqlalchemy.orm.base.InspectionAttrInfo sqlalchemy.util.langhelpers.MemoizedSlots ）

方法 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 开始，遍历与特定 'cascade' 的给定实例相关的实例。

返回一个 iterator3 元组（instance， mapper， state）。

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

此方法通常仅适用于 Relationship。

属性 sqlalchemy.orm.MapperProperty. class_attribute¶

返回与 this 对应的类绑定 Descriptors MapperProperty 的 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

属性 sqlalchemy.orm.MapperProperty. 比较器： PropComparator[_T]¶: 代表此映射属性实现 SQL 表达式构造的 PropComparator 实例。

方法 sqlalchemy.orm.MapperProperty. create_row_processor（context： ORMCompileState， query_entity： _MapperEntity， path： AbstractEntityRegistry， mapper： Mapper[Any]， result： Result[Any]， adapter：ORMAdapterNone， 填充器： _PopulatorDict）→ 无¶: 生成行处理函数并追加到给定的填充器列表集。

方法 sqlalchemy.orm.MapperProperty. do_init（）→ 无¶

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

这是 MapperProperty 调用的模板方法 Object 的 init（）方法。

attribute sqlalchemy.orm.MapperProperty. doc：strNone¶: 可选文档字符串

属性 sqlalchemy.orm.MapperProperty. 信息：_InfoType¶

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

字典是在首次访问时生成的。或者它可以指定为 column_property（）、relationship（） 或 composite（） 功能。

另请参阅

QueryableAttribute.info

方法 sqlalchemy.orm.MapperProperty. init（）→ None¶: 创建所有映射器后调用，以组合映射器之间的关系并执行其他映射器创建后初始化步骤。

方法 sqlalchemy.orm.MapperProperty. instrument_class（mapper： Mapper[Any]）→ 无¶

Mapper 调用属性的 Hook，以启动由此 MapperProperty 管理的类属性的检测。

这里的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

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

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

属性 sqlalchemy.orm.MapperProperty. is_property = True¶: InspectionAttr 接口的一部分;表示此对象是 Mapper 属性。

属性 sqlalchemy.orm.MapperProperty. 键：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]）→ 无¶: 合并此 MapperProperty 表示的属性 from source to destination 对象。

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

方法 sqlalchemy.orm.MapperProperty. post_instrument_class（mapper： Mapper[Any]）→ 无¶

执行需要在 init（）完成后进行的插桩调整。

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

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

方法 sqlalchemy.orm.MapperProperty. set_parent（parent： Mapper[Any]， init： bool）→ 无¶

设置引用此 MapperProperty 的父映射器。

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

方法 sqlalchemy.orm.MapperProperty. setup（context： ORMCompileState， query_entity： _MapperEntity， path： AbstractEntityRegistry， adapter：ORMAdapterNone， **kwargs： Any）→ None¶

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

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

类 sqlalchemy.orm 中。MappedSQLExpression¶

ColumnProperty 类的声明性前端。

Public 构造函数是 column_property（） 函数。

在 2.0 版更改：添加了 MappedSQLExpression 作为 ColumnProperty 的声明性兼容子类。

另请参阅

MappedColumn

类签名

类 sqlalchemy.orm.MappedSQLExpression （ sqlalchemy.orm.properties.ColumnProperty ， sqlalchemy.orm.base._DeclarativeMapped ）

类 sqlalchemy.orm 中。InspectionAttrExtensionType¶: 指示 a InspectionAttr 是其中的一部分。

类签名

class sqlalchemy.orm.InspectionAttrExtensionType （enum.枚举）

类 sqlalchemy.orm 中。NotExtension¶

一个枚举。

成员

NOT_EXTENSION

类签名

类 sqlalchemy.orm.NotExtension （） sqlalchemy.orm.base.InspectionAttrExtensionType

属性 sqlalchemy.orm.NotExtension 的 API API NOT_EXTENSION = 'not_extension'¶

指示不属于 sqlalchemy.ext 的 InspectionAttr 的符号。

分配给 InspectionAttr.extension_type 属性。

函数 sqlalchemy.orm 中。merge_result（query： Query[Any]， iterator：FrozenResultIterable[Sequence[Any]]Iterable[object]， load： bool = True）→FrozenResultIterable[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（） 。

函数 sqlalchemy.orm 中。merge_frozen_result（会话、语句、frozen_result、load=True）¶

将 FrozenResult 合并回 Session，返回具有持久性的新 Result 对象对象。

有关示例，请参阅 Re-Executing Statements 部分。

另请参阅

重新执行语句

结果.freeze（）

FrozenResult

类 sqlalchemy.orm 中。PropComparator （属性比较器）¶

定义 ORM 映射属性的 SQL作。

SQLAlchemy 允许在 Core 和 ORM 级别重新定义运算符。PropComparator （属性比较器） 是 ORM 级作的运算符重新定义的基类，包括 ColumnProperty 的 ColumnProperty 的 ColumnProperty 的 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.startswith（）

成员

__eq__（）， __le__（）， __lt__（）， __ne__（）， adapt_to_entity（），适配器， all_（）， and_（）， any（）， any_（）， asc（）， between（）， bitwise_and（）， bitwise_lshift（）， bitwise_not（）， bitwise_or（）， bitwise_rshift（）， bitwise_xor（）， bool_op（）， collate（）， concat（）， contains（）， desc（）， distinct（）， endswith（）， has（）， icontains（）， iendswith （）， ilike（）、in_（）、is_（）、is_distinct_from（）、is_not（）、is_not_distinct_from（）、isnot（）、isnot_distinct_from（）、istartwith（）、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 sqlalchemy.orm.PropComparator （ sqlalchemy.orm.base.SQLORMOperations ， typing.通用、 sqlalchemy.sql.expression.ColumnOperators ）

方法 sqlalchemy.orm.PropComparator. __eq__（other： Any）→ ColumnOperators¶

继承自 sqlalchemy.sql.expression.ColumnOperators.__eq__ ColumnOperators 的方法

实现 == 运算符。

在列上下文中，生成子句 a = b。如果目标是 None，则生成 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，则生成 IS NOT NULL。

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

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

方法 sqlalchemy.orm.PropComparator. all_（）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.all_（） 方法

针对父对象生成 all_（） 子句。

有关示例，请参阅 all_（） 的文档。

注意

一定不要混淆较新的 ColumnOperators.all_（） 方法替换为旧版版本，则 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 标准组合在一起

将 Criteria 添加到 loader 选项

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 的 ColumnOperators.any_（） 方法

针对父对象生成 any_（） 子句。

有关示例，请参阅 any_（） 的文档。

注意

一定不要混淆较新的 ColumnOperators.any_（） 方法替换为旧版版本，则 Comparator.any（） 方法，它使用不同的调用样式。

方法 sqlalchemy.orm.PropComparator. asc（）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.asc（） 方法

针对父对象生成 asc（） 子句。

method sqlalchemy.orm.PropComparator. between（cleft：任意， cright：任意， 对称： bool = False）→ ColumnOperators¶: 继承自 ColumnOperators 的 ColumnOperators.between（）方法

在给定下限和上限范围的情况下，针对父对象生成一个 between（） 子句。

方法 sqlalchemy.orm.PropComparator. bitwise_and（other： Any）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.bitwise_and（） 方法

产生一个按位的 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 的 ColumnOperators.bitwise_not（） 方法

产生一个按位的 NOT 运算，通常通过 ~ 算子。

2.0.2 新版功能.

另请参阅

按位运算符

方法 sqlalchemy.orm.PropComparator. bitwise_or（other： Any）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.bitwise_or（） 方法

生成按位 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 的 ColumnOperators.bitwise_xor（） 方法

生成按位 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.op（） 并将 Operators.op.is_comparison flag 替换为 True。使用 Operators.bool_op（） 的主要优势是，当使用列构造时，返回的 expression 将用于 PEP 484 目的。

另请参阅

运算符.op（）

方法 sqlalchemy.orm.PropComparator. collate（collation： str）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.collate（）方法

给定排序规则字符串，针对父对象生成 collate（） 子句。

另请参阅

collate（）

method sqlalchemy.orm.PropComparator. concat（other： Any）→ ColumnOperators¶

继承自 ColumnOperators 的 ColumnOperators.concat（） 方法

实现 'concat' 运算符。

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

method sqlalchemy.orm.PropComparator. contains（other： Any， **kw： Any）→ ColumnOperators¶

继承自 ColumnOperators 的 ColumnOperators.contains（）方法

实现 'contains' 运算符。

生成一个 LIKE 表达式，该表达式针对字符串值中间的匹配项进行测试：

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

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.contains.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.contains.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.contains.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.contains("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE '%' || :param || '%' ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

表达式，例如：
```
somecolumn.contains("foo/%bar", escape="^")
```
将渲染为：
```
somecolumn LIKE '%' || :param || '%' ESCAPE '^'
```
该参数也可以与 ColumnOperators.contains.autoescape ：
```
somecolumn.contains("foo%bar^bat", escape="^", autoescape=True)
```
在上面，给定的 literal 参数将被转换为 “foo^%bar^^bat” 在传递到数据库之前。

另请参阅

ColumnOperators.endswith（）

ColumnOperators.startswith（）

方法 sqlalchemy.orm.PropComparator. desc（）→ ColumnOperators¶: 继承自 ColumnOperators 的 ColumnOperators.desc（） 方法

针对父对象生成 desc（） 子句。

method sqlalchemy.orm.PropComparator. distinct（）→ 列运算符¶: 继承自ColumnOperators 的 ColumnOperators.distinct（）方法

针对父对象生成 distinct（） 子句。

method sqlalchemy.orm.PropComparator. endswith（other： Any， escape：strNone=None， autoescape： bool = False）→ 列运算符¶

继承自 ColumnOperators 的 ColumnOperators.endswith（）方法

实现 'endswith' 运算符。

生成一个 LIKE 表达式，该表达式针对字符串值末尾的匹配项进行测试：

column LIKE '%' || <other>

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.endswith.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.endswith.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.endswith.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.endswith("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE '%' || :param ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

表达式，例如：
```
somecolumn.endswith("foo/%bar", escape="^")
```
将渲染为：
```
somecolumn LIKE '%' || :param ESCAPE '^'
```
该参数也可以与 ColumnOperators.endswith.autoescape ：
```
somecolumn.endswith("foo%bar^bat", escape="^", autoescape=True)
```
在上面，给定的 literal 参数将被转换为 “foo^%bar^^bat” 在传递到数据库之前。

另请参阅

ColumnOperators.contains（）

ColumnOperators.contains（）

method 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 的 ColumnOperators.icontains（） 方法

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

生成一个 LIKE 表达式，该表达式针对字符串值中间的不敏感匹配项进行测试：

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

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.icontains.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.icontains.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.icontains.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.icontains("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) || '%' ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

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

另请参阅

method sqlalchemy.orm.PropComparator. iendswith（other： Any， escape：strNone=None， autoescape： bool = False）→ 列运算符¶

继承自 ColumnOperators 的 ColumnOperators.iendswith（）方法

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

生成一个 LIKE 表达式，该表达式针对字符串值末尾的不敏感匹配项进行测试：

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

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.iendswith.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.iendswith.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.iendswith.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.iendswith("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE '%' || lower(:param) ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

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

另请参阅

ColumnOperators.endswith（）

方法 sqlalchemy.orm.PropComparator. ilike（other： Any， escape：strNone=None）→ 列运算符¶

继承自ColumnOperators 的 ColumnOperators.ilike（） 方法

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

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

lower(a) LIKE lower(other)

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

a ILIKE other

例如：

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

参数

other¶ – 要比较的表达式
转义¶ –

可选的转义字符，将 ESCAPE 关键字，例如：
```
somecolumn.ilike("foo/%bar", escape="/")
```

另请参阅

ColumnOperators.is_not（）

方法 sqlalchemy.orm.PropComparator. in_（other： Any）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.in_（） 方法

实现 in 运算符。

在列上下文中，生成子句列 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_([]))
```
在此调用形式中，表达式呈现 “empty set” 表达式。这些表达式是针对各个后端量身定制的，通常尝试获取空的 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 版本加入：添加了 “expanding” 绑定参数

如果传递了空列表，则会呈现特定于正在使用的数据库的特殊“空列表”表达式。在 SQLite 上，这将是：
```
WHERE COL IN (SELECT 1 FROM (SELECT 1) WHERE 1!=1)
```
在 1.3 版本加入： “expanding” 绑定参数现在支持空列表

select（） 结构，通常是相关的标量 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.expanding 标志设置为 True。

方法 sqlalchemy.orm.PropComparator. is_（other： Any）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.is_（） 方法

实现 IS 运算符。

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

另请参阅

方法 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”。

方法 sqlalchemy.orm.PropComparator. is_not（other： Any）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.is_not（） 方法

实现 IS NOT 运算符。

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

在 1.4 版本发生变更： is_not（） 运算符已从 isnot（）的 API 中。以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.is_（）

方法 sqlalchemy.orm.PropComparator. is_not_distinct_from（other： Any）→ ColumnOperators¶

继承自 ColumnOperators.is_not_distinct_from() ColumnOperators 的方法

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现 “a IS NOT DISTINCT WITH b”;在某些（例如 SQLite）上可能会呈现“a IS b”。

在 1.4 版本发生变更： is_not_distinct_from（） 运算符已从早期版本中的 isnot_distinct_from（） 重命名。以前的名称仍然可用于向后兼容。

method sqlalchemy.orm.PropComparator. isnot（other： Any）→ 列运算符¶

继承自ColumnOperators 的 ColumnOperators.isnot（） 方法

实现 IS NOT 运算符。

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

在 1.4 版本发生变更： is_not（） 运算符已从 isnot（）的 API 中。以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.is_（）

方法 sqlalchemy.orm.PropComparator. isnot_distinct_from（other： Any）→ ColumnOperators¶

继承自 ColumnOperators.isnot_distinct_from() ColumnOperators 的方法

实现 IS NOT DISTINCT FROM 运算符。

在大多数平台上呈现 “a IS NOT DISTINCT WITH b”;在某些（例如 SQLite）上可能会呈现“a IS b”。

在 1.4 版本发生变更： is_not_distinct_from（） 运算符已从早期版本中的 isnot_distinct_from（） 重命名。以前的名称仍然可用于向后兼容。

方法 sqlalchemy.orm.PropComparator. istartswith（other： Any， escape：strNone=None， autoescape： bool = False）→ 列运算符¶

继承自ColumnOperators 的 ColumnOperators.istartswith（）方法

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

生成一个 LIKE 表达式，该表达式针对字符串值开头的不敏感匹配项进行测试：

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

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.istartswith.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.istartswith.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.istartswith.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.istartswith("foo%bar", autoescape=True)
```
将渲染为：
```
lower(somecolumn) LIKE lower(:param) || '%' ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

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

另请参阅

ColumnOperators.startswith（）

method sqlalchemy.orm.PropComparator. like（other： Any， escape：strNone=None）→ 列运算符¶

继承自 ColumnOperators 的 ColumnOperators.like（） 方法

实现 like 运算符。

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

a LIKE other

例如：

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

参数

other¶ – 要比较的表达式
转义¶ –

可选的转义字符，将 ESCAPE 关键字，例如：
```
somecolumn.like("foo/%bar", escape="/")
```

另请参阅

ColumnOperators.ilike（）

method sqlalchemy.orm.PropComparator. match（other： Any， **kwargs： Any）→ ColumnOperators¶

继承自 ColumnOperators 的 ColumnOperators.match（）方法

实现特定于数据库的 '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 数据库 - 呈现 CONTAINS（x， y）
其他后端可能会提供特殊的实现。
没有任何特殊实现的后端会将运算符发出为 “MATCH”。例如，这与 SQLite 兼容。

方法 sqlalchemy.orm.PropComparator. not_ilike（other： Any， escape：strNone=None）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.not_ilike（） 方法

实现 NOT ILIKE 运算符。

这相当于使用 ColumnOperators.ilike（）的 ColumnOperators.ilike（）中，即 ~x.ilike（y）。

在 1.4 版本发生变更： not_ilike（） 运算符已从 notilike（） 的 intent 函数。以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike（）

方法 sqlalchemy.orm.PropComparator. not_in（other： Any）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.not_in（） 方法

实现 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 序列生成 “static” 表达式。

另请参阅

ColumnOperators.in_（）

方法 sqlalchemy.orm.PropComparator. not_like（other： Any， escape：strNone=None）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.not_like（） 方法

实现 NOT LIKE 运算符。

这相当于使用 ColumnOperators.like（）的 ColumnOperators.like（）中，即 ~x.like（y）。

在 1.4 版本发生变更： not_like（） 运算符已从 notlike（） 的以前的名称仍然可用于向后兼容。

另请参阅

ColumnOperators.ilike（）

method sqlalchemy.orm.PropComparator. notilike（other： Any， escape：strNone=None）→ 列运算符¶

继承自ColumnOperators 的 ColumnOperators.notilike（） 方法

实现 NOT ILIKE 运算符。

这相当于使用 ColumnOperators.ilike（）的 ColumnOperators.ilike（）中，即 ~x.ilike（y）。

在 1.4 版本发生变更： not_ilike（） 运算符已从 notilike（） 的 intent 函数。以前的名称仍然可用于向后兼容。

另请参阅

方法 sqlalchemy.orm.PropComparator. notin_（other： Any）→ ColumnOperators¶

继承自ColumnOperators 的 ColumnOperators.notin_（） 方法

实现 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 序列生成 “static” 表达式。

另请参阅

ColumnOperators.in_（）

method sqlalchemy.orm.PropComparator. notlike（other： Any， escape：strNone=None）→ 列运算符¶

继承自ColumnOperators 的 ColumnOperators.notlike（） 方法

实现 NOT LIKE 运算符。

这相当于使用 ColumnOperators.like（）的 ColumnOperators.like（）中，即 ~x.like（y）。

在 1.4 版本发生变更： not_like（） 运算符已从 notlike（） 的以前的名称仍然可用于向后兼容。

另请参阅

使用 Relationship 在别名目标之间联接 - 在 ORM 查询指南

方法 sqlalchemy.orm.PropComparator. nulls_first（）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.nulls_first（） 方法

针对父对象生成 nulls_first（） 子句。

在 1.4 版本发生变更： nulls_first（） 运算符已从以前版本中的 nullsfirst（） 重命名。以前的名称仍然可用于向后兼容。

方法 sqlalchemy.orm.PropComparator. nulls_last（）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.nulls_last（） 方法

针对父对象生成 nulls_last（） 子句。

在 1.4 版本发生变更： nulls_last（） 运算符已从以前版本中的 nullslast（） 重命名。以前的名称仍然可用于向后兼容。

方法 sqlalchemy.orm.PropComparator. nullsfirst（）→ ColumnOperators¶: 继承自ColumnOperators 的 ColumnOperators.nullsfirst（） 方法

针对父对象生成 nulls_first（） 子句。

在 1.4 版本发生变更： nulls_first（） 运算符已从以前版本中的 nullsfirst（） 重命名。以前的名称仍然可用于向后兼容。

方法 sqlalchemy.orm.PropComparator. nullslast（）→ ColumnOperators¶: 继承自 ColumnOperators 的 ColumnOperators.nullslast（）方法

针对父对象生成 nulls_last（） 子句。

在 1.4 版本发生变更： nulls_last（） 运算符已从以前版本中的 nullslast（） 重命名。以前的名称仍然可用于向后兼容。

方法 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_¶ —— 一个类或映射器，指示该标准将针对这个特定的子类。

另请参阅

联接到特定子类型或 with_polymorphic（）实体

方法 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 的 Operators.op（） 方法

生成泛型运算符函数。

例如：

somecolumn.op("*")(5)

生产：

somecolumn * 5

此函数还可用于使按位运算符显式。例如：

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

是 somecolumn 中值的按位 AND。

参数

opstring¶ – 一个字符串，将作为此元素和传递给生成函数的表达式之间的中缀运算符输出。
优先级¶ –

优先级，数据库应应用于 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 类或对象，它将 force 此运算符生成的表达式的返回类型属于该类型。默认情况下，指定 Operators.op.is_comparison将解析为 Boolean 的 Boolean 和那些不 boolean 的 Boolean 将与左侧作数的类型相同。
python_impl¶ –

一个可选的 Python 函数，该函数可以计算两个 Python 值，其工作方式与此运算符在数据库服务器上运行时的工作方式相同。对于 Python 内部 SQL 表达式评估函数（例如 ORM 混合属性）以及用于在多行更新或删除后匹配会话中的对象的 ORM“评估器”非常有用。

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

另请参阅

Operators.bool_op（）

ColumnOperators.regexp_replace()

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

method sqlalchemy.orm.PropComparator. operate（op： OperatorType， *other： Any， **kwargs： Any→ 运营商¶

继承自Operators 的 Operators.operate（） 方法

对参数进行作。

这是最低级别的作，加注 NotImplementedError 的 MethodS 错误。

在子类上覆盖 this 可以允许将通用行为应用于所有作。例如，重写 ColumnOperators 要将 func.lower（） 应用于左侧和右侧：

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

参数

op¶- 运算符可调用。
other¶ ——作的 'other' 端。对于大多数作，将是单个标量。
**kwargs¶ —— 修饰符。这些可以通过特殊运算符（如 ColumnOperators.contains（）））传递。

attribute sqlalchemy.orm.PropComparator. 属性¶

返回与此关联的 MapperProperty PropComparator 的 PropComparator 中。

此处的返回值通常是 ColumnProperty 或 Relationship 的 ColumnProperty 或 Relationship 创建。

方法 sqlalchemy.orm.PropComparator. regexp_match（pattern： Any， flags：strNone=None）→ ColumnOperators¶

继承自 ColumnOperators.regexp_match() ColumnOperators 的方法

实现特定于数据库的 'regexp match' 运算符。

例如：

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 Database、PostgreSQL、MySQL 和 MariaDB 实施正则表达式支持。SQLite 提供部分支持。第三方方言之间的支持可能会有所不同。

参数

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

在 1.4 版本加入.

在 1.4.48 版本发生变更： 2.0.18 请注意，由于实现错误，除了纯 Python 字符串之外，“flags”参数以前还接受 SQL 表达式对象，例如列表达式。此实现无法正确使用缓存，因此已被删除;只应为 “flags” 参数传递字符串，因为这些标志在 SQL 表达式中呈现为文本内联值。

另请参阅

方法 sqlalchemy.orm.PropComparator. regexp_replace（pattern： Any， replacement： Any， flags：strNone=None）→ ColumnOperators¶

继承自 ColumnOperators.regexp_replace() ColumnOperators 的方法

实现特定于数据库的 'regexp replace' 运算符。

例如：

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

ColumnOperators.regexp_replace() 尝试解析为后端提供的类似 REGEXP_REPLACE 的函数，该函数通常会发出函数 REGEXP_REPLACE（）。 然而可用的特定正则表达式语法和标志包括 不是后端不可知的。

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

参数

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

在 1.4 版本加入.

在 1.4.48 版本发生变更： 2.0.18 请注意，由于实现错误，除了纯 Python 字符串之外，“flags”参数以前还接受 SQL 表达式对象，例如列表达式。此实现无法正确使用缓存，因此已被删除;只应为 “flags” 参数传递字符串，因为这些标志在 SQL 表达式中呈现为文本内联值。

另请参阅

ColumnOperators.regexp_match()

方法 sqlalchemy.orm.PropComparator. reverse_operate（op： OperatorType， other： Any， **kwargs： Any）→ 运算符¶

继承自Operators 的 Operators.reverse_operate（） 方法

Reverse 对参数进行作。

用法与 operate（） 相同。

方法 sqlalchemy.orm.PropComparator. startswith（other： Any， escape：strNone=None， autoescape： bool = False）→ 列运算符¶

继承自 ColumnOperators 的 ColumnOperators.startswith（）方法

实现 startswith 运算符。

生成一个 LIKE 表达式，该表达式针对字符串值开头的匹配项进行测试：

column LIKE <other> || '%'

例如：

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

由于运算符使用 LIKE、通配符存在于 <other> 表达式中的 “%” 和 “_” 的行为也类似于通配符。对于 Literals 字符串值，可以将 ColumnOperators.startswith.autoescape 该标志设置为 True 以对出现这些值字符，以便它们与自身匹配而不是通配符。或者， ColumnOperators.startswith.escape parameter 将给定字符建立为转义字符，当目标表达式不是文本字符串时，该字符可能很有用。

参数

other¶ —— 要比较的表达式。这通常是一个纯字符串值，但也可以是任意 SQL 表达式。默认情况下，除非标志 ColumnOperators.startswith.autoescape 设置为 True，否则不会对 LIKE 通配符 % 和 _ 进行转义。
自动转义¶ –

布尔;当 True 时，建立转义字符，然后将其应用于 “%”、“_” 和比较值中的转义字符本身，该值假定为文本字符串，而不是 SQL 表达式。

表达式，例如：
```
somecolumn.startswith("foo%bar", autoescape=True)
```
将渲染为：
```
somecolumn LIKE :param || '%' ESCAPE '/'
```
:p aram 的值为 “foo/%bar”。
转义¶ –

一个字符，当给定时，它将使用 ESCAPE 关键字将该字符建立为转义字符。然后，可以将此字符放在 % 和 _ 的出现之前，以允许它们充当自身，而不是通配符。

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

另请参阅

ColumnOperators.endswith（）

ColumnOperators.contains（）

MANYTOMANY、MANYTOONE、ONETOMANY

属性 sqlalchemy.orm.PropComparator. timetuple： Literal[None] = None¶: 继承自ColumnOperators 的 ColumnOperators.timetuple属性

Hack 允许在 LHS 上比较日期时间对象。

类 sqlalchemy.orm 中。关系¶

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

Public constructor 是 relationship（） 函数。

另请参阅

关系配置

在 2.0 版更改：添加了 Relationship 作为 RelationshipProperty 的声明性兼容子类。

类签名

类 sqlalchemy.orm.Relationship （ sqlalchemy.orm.RelationshipProperty ， sqlalchemy.orm.base._DeclarativeMapped ）

类 sqlalchemy.orm 中。RelationshipDirection（关系方向）¶

枚举，它指示 RelationshipProperty 的 RelationshipProperty 中。

RelationshipDirection 可从 Relationship.direction 属性 RelationshipProperty 的 RelationshipProperty 中。

成员

类签名

class sqlalchemy.orm.RelationshipDirection （enum.枚举）

属性 sqlalchemy.orm.RelationshipDirection. MANYTOMANY = 3¶

指示 relationship（） 的多对多方向。

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

属性 sqlalchemy.orm.RelationshipDirection. MANYTOONE = 2¶

指示 relationship（） 的多对一方向。

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

属性 sqlalchemy.orm.RelationshipDirection. ONETOMANY = 1¶

指示 relationship（） 的一对多方向。

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

类 sqlalchemy.orm 中。RelationshipProperty¶

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

Public constructor 是 relationship（） 函数。

另请参阅

关系配置

成员

__eq__（）， __init__（）， __ne__（）， adapt_to_entity（）， and_（）， any（）， contains（）， entity， has（）， in_（）， mapper， of_type（）， cascade， cascade_iterator（）， declarative_scan（）、do_init（）、实体、instrument_class（）、映射器、merge（）

类签名

类 sqlalchemy.orm.RelationshipProperty （ sqlalchemy.orm._IntrospectsAnnotations ， sqlalchemy.orm.StrategizedProperty ， sqlalchemy.log.已识别）

类 Comparator¶

生成 boolean、comparison 和其他运算符 RelationshipProperty 属性。

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

另请参阅

PropComparator （属性比较器）

比较仪

QueryableAttribute.info

类签名

类 sqlalchemy.orm.RelationshipProperty.Comparator （ sqlalchemy.util.langhelpers.MemoizedSlots ， sqlalchemy.orm.PropComparator）

方法 sqlalchemy.orm.RelationshipProperty.Comparator. __eq__（other： Any）→ ColumnElement[bool]¶

实现 == 运算符。

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

MyClass.some_prop == <some object>

这通常会产生如下子句：

mytable.related_id == <some id>

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

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

不支持与集合进行比较。使用 Comparator.contains（）。
与标量一对多相比，将生成一个子句，该子句将父级中的目标列与给定目标进行比较。
与标量多对多相比，别名关联表将呈现为嗯，形成一个自然联接，这是 main body 的查询。这不适用于超出比较，例如使用 OR 的比较。用 explicit joins、outerjoins 或 Comparator.has（） 进行更全面的非多对一标量隶属度测试。
与在一对多或多对多上下文中给出的 None 进行比较会生成 NOT EXISTS 子句。

方法 sqlalchemy.orm.RelationshipProperty.Comparator. __init__（prop： RelationshipProperty[_PT]， parentmapper： _InternalEntityType[Any]， adapt_to_entity：AliasedInsp[Any]None=无， of_type：_EntityType[_PT]None=无， extra_criteria： Tuple[ColumnElement[bool]， ...] = （））¶: 比较器的构造是 ORM 属性机制的内部。

方法 sqlalchemy.orm.RelationshipProperty.Comparator. __ne__（other： Any）→ ColumnElement[bool]¶

实现 ！= 运算符。

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

MyClass.some_prop != <some object>

这通常会生成如下子句：

mytable.related_id != <some id>

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

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

不支持与集合进行比较。用 比较器.contains（） 与 not_（） 结合使用。
与标量一对多相比，将生成一个子句，该子句将父级中的目标列与给定目标进行比较。
与标量多对多相比，别名关联表将呈现为嗯，形成一个自然联接，这是 main body 的查询。这不适用于超出比较，例如使用 OR 的比较。用 explicit joins、outerjoins 或 Comparator.has（） 与 not_（） 结合使用，以进行更全面的非多对一标量隶属度测试。
与一对多或多对多上下文中给出的 None 进行比较会生成 EXISTS 子句。

方法 sqlalchemy.orm.RelationshipProperty.Comparator. adapt_to_entity（adapt_to_entity： AliasedInsp[Any]）→ RelationshipProperty.Comparator[Any]¶: 返回此 PropComparator 的副本，该副本将使用给定的 AliasedInsp 生成相应的表达式。

方法 sqlalchemy.orm.RelationshipProperty.Comparator. and_（*criteria： _ColumnExpressionArgument[bool]）→ PropComparator[Any]¶

添加 AND 标准。

有关示例，请参阅 PropComparator.and_（） 。

在 1.4 版本加入.

方法 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 上的外键属性的值，它引用主 key 的 key 中。由此可知 Comparator.contains（） 在与简单的一对多作一起使用时非常有用。

对于多对多作， 比较器.contains（） 有更多的警告。关联表将为在语句中呈现，产生一个 “implicit” join，即在 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> 将是 其他。从上面可以清楚地看出 比较器.contains（） 不适用于多对多集合用于超越简单 AND 的查询连词，例如 multiple 比较器.contains（） 由 OR 连接的表达式。在这种情况下，子查询或需要改用显式的 “outer joins”。有关使用 EXISTS 的较低性能的替代方案，请参阅 Comparator.any（） ，或参考 Query.outerjoin（） 以及 Joins 了解有关构造外部联接的更多详细信息。

kwargs 可以被此运算符忽略，但对于 API 一致性是必需的。

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

此引用的目标实体 比较器。

这是 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（）。

方法 sqlalchemy.orm.RelationshipProperty.Comparator. in_（other： Any）→ NoReturn¶: 生成 IN 子句 - 目前不为基于 relationship（） 的属性实现此子句。

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

此引用的目标 Mapper 比较器。

这是 relationship（） 的

方法 sqlalchemy.orm.RelationshipProperty.Comparator. of_type（class_： _EntityType[Any]）→ PropComparator[_PT]¶

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

有关示例，请参阅 PropComparator.of_type（） 。

属性 sqlalchemy.orm.RelationshipProperty. 级联¶: 返回此的当前级联设置 RelationshipProperty 的 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 开始，遍历与特定 'cascade' 的给定实例相关的实例。

返回一个 iterator3 元组（instance， mapper， state）。

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

此方法通常仅适用于 Relationship。

方法 sqlalchemy.orm.RelationshipProperty. declarative_scan（decl_scan：_ClassScanMapperConfig，注册表：_RegistryType，cls：类型 [Any]， originating_module：strNone， key： str， mapped_container：Type[Mapped[Any]]None， annotation：_AnnotationScanTypeNone， extracted_mapped_annotation：_AnnotationScanTypeNone， is_dataclass_field： bool）→ 无¶: 在早期声明性扫描时执行特定于类的初始化。

2.0 版的新Function。

方法 sqlalchemy.orm.RelationshipProperty. do_init（）→ 无¶

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

这是 MapperProperty 调用的模板方法 Object 的 init（）方法。

attribute sqlalchemy.orm.RelationshipProperty. 实体¶: 返回目标映射实体，它是 class 或由 this 引用的别名类 RelationshipProperty 的 RelationshipProperty 中。

方法 sqlalchemy.orm.RelationshipProperty. instrument_class（mapper： Mapper[Any]）→ 无¶

Mapper 调用属性的 Hook，以启动由此 MapperProperty 管理的类属性的检测。

这里的 MapperProperty 通常会调用 attributes 模块来设置 InstrumentedAttribute。

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

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

属性 sqlalchemy.orm.RelationshipProperty. 映射器¶: 返回此目标 Mapper RelationshipProperty 的 RelationshipProperty 中。

method 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]）→ 无¶: 合并此 MapperProperty 表示的属性 from source to destination 对象。

类 sqlalchemy.orm 中。SQLORMExpression¶

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

SQLORMExpression 从核心 SQLColumnExpression 添加特定于 ORM 的其他 SQL 方法，例如 PropComparator.of_type（），并且是 InstrumentedAttribute 的基础的一部分。它可以在 PEP 484 类型中用于指示应表现为 ORM 级属性表达式的参数或返回值。

2.0.0b4 版本的新Function。

类签名

类 sqlalchemy.orm.SQLORMExpression （ sqlalchemy.orm.base.SQLORMOperations ， sqlalchemy.sql.expression.SQLColumnExpression ， sqlalchemy.util.langhelpers.TypingOnly ）

类 sqlalchemy.orm 中。同义词¶

SynonymProperty 类的声明性前端。

Public constructor 是 synonym（） 函数。

在 2.0 版更改：添加了 Synonym 作为 SynonymProperty 的声明性兼容子类

另请参阅

同义词 - 同义词概述

类签名

类 sqlalchemy.orm.同义词 （ sqlalchemy.orm.descriptor_props.SynonymProperty ， sqlalchemy.orm.base._DeclarativeMapped ）

类 sqlalchemy.orm 中。SynonymProperty（同义词属性）¶

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

同义词是使用 synonym（） 构建的功能。

另请参阅

同义词 - 同义词概述

成员

doc、info、key、parent、set_parent（） uses_objects

类签名

类 sqlalchemy.orm.SynonymProperty （ sqlalchemy.orm.descriptor_props.DescriptorProperty ）

attribute sqlalchemy.orm.SynonymProperty. doc：strNone¶: 继承自DescriptorProperty 的 DescriptorProperty.doc属性

可选文档字符串

属性 sqlalchemy.orm.SynonymProperty. 信息：_InfoType¶

继承自MapperProperty 的 MapperProperty.info属性

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

字典是在首次访问时生成的。或者它可以指定为 column_property（）、relationship（） 或 composite（） 功能。

另请参阅

InstrumentedAttribute （检测属性）

属性 sqlalchemy.orm.SynonymProperty. 键：str¶: 继承自MapperProperty 的 MapperProperty.key属性

类属性的名称

attribute sqlalchemy.orm.SynonymProperty. parent： Mapper[Any]¶: 继承自MapperProperty 的 MapperProperty.parent属性

管理此属性的 Mapper 。

方法 sqlalchemy.orm.SynonymProperty. set_parent（parent： Mapper[Any]， init： bool）→ 无¶

设置引用此 MapperProperty 的父映射器。

此方法被一些子类覆盖，以便在首次知道 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 拦截属性事件的描述符对象的基类对象。实际的 MapperProperty 可以通过 QueryableAttribute.property 访问属性。

另请参阅

Mapper属性

Mapper.all_orm_descriptors

Mapper.attrs

成员

adapt_to_entity（）， and_（），表达式，信息， is_attribute， of_type（）， operate（），父级， 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 标准组合在一起

将 Criteria 添加到 loader 选项

with_loader_criteria（）

属性 sqlalchemy.orm.QueryableAttribute. 表达式： ColumnElement[_T_co]¶

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

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

属性 sqlalchemy.orm.QueryableAttribute. 信息¶

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

此处的行为如下：

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

另请参阅