查询 API

本节介绍ORM的API参考 Query 对象。有关如何使用此对象的演练，请参见 对象关系教程（1.x API） .

查询对象

Query 是根据给定的 Session ，使用 Session.query() 方法：

q = session.query(SomeMappedClass)

下面是 Query 对象。

class sqlalchemy.orm.Query(entities, session=None)

Object Name	Description
aliased(element[, alias, name, flat, ...])	生成给定元素的别名，通常是 AliasedClass 实例。
AliasedClass	表示用于查询的映射类的“别名”形式。
AliasedInsp	为 AliasedClass 对象。
Bundle	由返回的一组SQL表达式 Query 在一个命名空间下。
join(left, right[, onclause, isouter, ...])	在左子句和右子句之间生成内部联接。
Load	表示修改 Query 以影响各种映射属性的加载方式。
outerjoin(left, right[, onclause, full, ...])	在左子句和右子句之间生成左外部联接。
with_loader_criteria(entity_or_base, where_criteria[, loader_only, include_aliases, ...])	将其他WHERE条件添加到特定实体的所有引用的加载中。
with_parent(instance, prop[, from_entity])	使用已建立的筛选条件，创建将此查询的主实体与给定的相关实例关联的筛选条件 relationship() 配置。

function sqlalchemy.orm.aliased(element, alias=None, name=None, flat=False, adapt_on_names=False)¶

生成给定元素的别名，通常是 AliasedClass 实例。

例如。：：

my_alias = aliased(MyClass)

session.query(MyClass, my_alias).filter(MyClass.id > my_alias.id)

这个 aliased() 函数用于创建映射类到新可选对象的即席映射。默认情况下，从通常映射的可选对象（通常为 Table ）使用 FromClause.alias() 方法。然而， aliased() 也可用于将类链接到新的 select() 声明。还有，这个 with_polymorphic() 函数是 aliased() 这是为了指定一个所谓的“多态可选择的”，它对应于同时合并的几个继承子类的联合。

为了方便起见， aliased() 函数也接受普通 FromClause 构造，例如 Table 或 select() 构建。在这些情况下， FromClause.alias() 对对象和新的 Alias 返回了对象。归还的人 Alias 在这种情况下不是ORM映射。

参见

ORM实体别名 - in the SQLAlchemy 1.4/2.0教程

选择ORM别名 - in the ORM查询指南

使用别名 - in the legacy 对象关系教程（1.x API）

参数

• element¶ -- 要别名的元素。通常是映射类，但为了方便起见，也可以是 FromClause 元素。

• alias¶ -- 要将元素映射到的可选单位。这通常用于将对象链接到子查询，并且应该是从 Query.subquery() 方法或 Select.subquery() 或 Select.alias() 方法 select() 构造。

• name¶ -- 要用于别名的可选字符串名称（如果不是由 alias 参数。除其他外，名称形成了属性名，可以通过由 Query 对象。创建别名时不支持 Join 物体。

• flat¶ -- 布尔值，将传递给 FromClause.alias() 调用以便 Join 对象将对联接内的各个表进行别名，而不是创建子查询。对于右嵌套联接，这通常由所有现代数据库支持，并且通常生成更高效的查询。

• adapt_on_names¶ -- 如果为真，则在将ORM实体的映射列映射到给定可选项的列时将使用更自由的“匹配”。如果给定可选项没有对应于实体上的列，则将执行基于名称的匹配。此方法的用例是将实体与某些派生可选项（如使用聚合函数的实体：：Class UnitPrice（Base））关联时： __tablename__ ='单价'…Unit_id=column（integer）price=column（numeric）aggregated_unity_price=session.query（func.sum（unit price.price.label（'price'））.group_by（unit price.unit_id）.subquery（）aggregated_unity_price=aliased（unit price，alias=aggregated_unity_price，adapt_on_name=true）以上，功能开启 aggregated_unit_price 指的是 .price 将返回 func.sum(UnitPrice.price).label('price') 列，因为它与名称“price”匹配。通常，“price”函数与实际 UnitPrice.price 列，因为它不是原始列的代理。

class sqlalchemy.orm.util.AliasedClass(mapped_class_or_ac, alias=None, name=None, flat=False, adapt_on_names=False, with_polymorphic_mappers=(), with_polymorphic_discriminator=None, base_alias=None, use_mapper_path=False, represents_outer_join=False)¶

表示用于查询的映射类的“别名”形式。

ORM等价于 alias() 构造，此对象使用 __getattr__ 设计并维护对 Alias 对象。

主要目的是 AliasedClass 在ORM生成的SQL语句中充当替代项，以便现有的映射实体可以在多个上下文中使用。一个简单的例子：

# find all pairs of users with the same name
user_alias = aliased(User)
session.query(User, user_alias).\
                join((user_alias, User.id > user_alias.id)).\
                filter(User.name == user_alias.name)

AliasedClass 也可以将现有的映射类映射到全新的可选对象，前提是该可选对象与现有的映射可选对象列兼容，并且还可以在映射中配置为 relationship() . 有关示例，请参见下面的链接。

这个 AliasedClass 对象通常使用 aliased() 功能。当使用 with_polymorphic() 功能。

结果对象是 AliasedClass . 此对象实现一个属性方案，该方案生成与原始映射类相同的属性和方法接口，允许 AliasedClass 与在原始类上工作的任何属性技术兼容，包括混合属性（请参见 混合属性 ）

这个 AliasedClass 可以检查其基础 Mapper ，别名可选，以及使用 inspect() ：：

from sqlalchemy import inspect
my_alias = aliased(MyClass)
insp = inspect(my_alias)

结果检验对象是 AliasedInsp .

参见

aliased()

with_polymorphic()

与别名类的关系

与窗口函数的行限制关系

class sqlalchemy.orm.util.AliasedInsp(entity, inspected, selectable, name, with_polymorphic_mappers, polymorphic_on, _base_alias, _use_mapper_path, adapt_on_names, represents_outer_join)¶

为 AliasedClass 对象。

这个 AliasedInsp 如果给定 AliasedClass 使用 inspect() 功能：

from sqlalchemy import inspect
from sqlalchemy.orm import aliased

my_alias = aliased(MyMappedClass)
insp = inspect(my_alias)

属性对 AliasedInsp 包括：

• entity - AliasedClass 代表。

• mapper - Mapper 映射基础类。

• selectable - Alias 最终表示别名的构造 Table 或 Select 构造。

• name -别名的名称。当从返回结果元组时，也用作属性名 Query .

• with_polymorphic_mappers -收藏 Mapper 对象，指示在 AliasedClass .

• polymorphic_on -将用作多态加载的“鉴别器”的备用列或SQL表达式。

参见

运行时检查API

类签名

class sqlalchemy.orm.AliasedInsp (sqlalchemy.orm.ORMEntityColumnsClauseRole, sqlalchemy.orm.ORMFromClauseRole, sqlalchemy.sql.traversals.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr)

class sqlalchemy.orm.Bundle(name, *exprs, **kw)¶

由返回的一组SQL表达式 Query 在一个命名空间下。

这个 Bundle 基本上允许嵌套面向列返回的基于元组的结果 Query 对象。它还可以通过简单的子类化进行扩展，其中重写的主要功能是如何返回表达式集，允许后处理和自定义返回类型，而不涉及ORM标识映射类。

0.9.0 新版功能.

参见

列束

类签名

class sqlalchemy.orm.Bundle (sqlalchemy.orm.ORMColumnsClauseRole, sqlalchemy.sql.annotation.SupportsCloneAnnotations, sqlalchemy.sql.traversals.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr)

method sqlalchemy.orm.Bundle.__init__(name, *exprs, **kw)¶

构建新的 Bundle .

例如。：：

bn = Bundle("mybundle", MyClass.x, MyClass.y)

for row in session.query(bn).filter(
        bn.c.x == 5).filter(bn.c.y == 4):
    print(row.mybundle.x, row.mybundle.y)

参数

• name¶ -- 包的名称。

• *exprs¶ -- 包含束的列或SQL表达式。

• single_entity=False¶ -- 如果为真，则为该行 Bundle 可以作为“单个实体”在任何封闭元组之外以与映射实体相同的方式返回。

attribute sqlalchemy.orm.Bundle.c = None¶

的别名 Bundle.columns .

attribute sqlalchemy.orm.Bundle.columns = None¶

此引用的SQL表达式的命名空间 Bundle .

例如。：：

bn = Bundle("mybundle", MyClass.x, MyClass.y)

q = sess.query(bn).filter(bn.c.x == 5)

还支持捆绑包的嵌套：：

b1 = Bundle("b1",
        Bundle('b2', MyClass.a, MyClass.b),
        Bundle('b3', MyClass.x, MyClass.y)
    )

q = sess.query(b1).filter(
    b1.c.b2.c.a == 5).filter(b1.c.b3.c.y == 9)

参见

Bundle.c

method sqlalchemy.orm.Bundle.create_row_processor(query, procs, labels)¶

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

可以被子类重写。

参见

列束 -包括子类化的示例。

method sqlalchemy.orm.Bundle.label(name)¶

提供此的副本 Bundle 传递新标签。

attribute sqlalchemy.orm.Bundle.single_entity = False¶

如果为true，则对单个绑定的查询将作为单个实体返回，而不是作为键控元组中的元素返回。

class sqlalchemy.orm.Load(entity)¶

表示修改 Query 以影响各种映射属性的加载方式。

这个 Load 在大多数情况下，当使用类似 joinedload() ， defer() 或类似。然而， Load 对象也可以直接使用，在某些情况下是有用的。

使用 Load 直接用目标映射类作为参数实例化它。这种用法在处理 Query 有多个实体：

myopt = Load(MyClass).joinedload("widgets")

以上 myopt 现在可用于 Query.options() ，仅对 MyClass 单位：

session.query(MyClass, MyOtherClass).options(myopt)

其中一例 Load 当指定仅对特定类生效的“通配符”选项时，公共API非常有用：

session.query(Order).options(Load(Order).lazyload('*'))

上面，所有关系 Order 将被延迟加载，但这些子对象上的其他属性将使用它们的常规加载策略进行加载。

参见

延迟的列加载程序查询选项

跨多个实体延迟加载

与加载程序选项的关系加载

类签名

class sqlalchemy.orm.Load (sqlalchemy.sql.expression.Generative, sqlalchemy.orm.LoaderOption)

method sqlalchemy.orm.Load.baked_lazyload(attr)¶

产生新的 Load 对象与 baked_lazyload() 选项应用。

见 baked_lazyload() 用于示例。

method sqlalchemy.orm.Load.contains_eager(attr, alias=None)¶

产生新的 Load 对象与 contains_eager() 选项应用。

见 contains_eager() 用于示例。

method sqlalchemy.orm.Load.defaultload(attr)¶

产生新的 Load 对象与 defaultload() 选项应用。

见 defaultload() 用于示例。

method sqlalchemy.orm.Load.defer(key, raiseload=False)¶

产生新的 Load 对象与 defer() 选项应用。

见 defer() 用于示例。

method sqlalchemy.orm.Load.immediateload(attr)¶

产生新的 Load 对象与 immediateload() 选项应用。

见 immediateload() 用于示例。

method sqlalchemy.orm.Load.joinedload(attr, innerjoin=None)¶

产生新的 Load 对象与 joinedload() 选项应用。

见 joinedload() 用于示例。

method sqlalchemy.orm.Load.lazyload(attr)¶

产生新的 Load 对象与 lazyload() 选项应用。

见 lazyload() 用于示例。

method sqlalchemy.orm.Load.load_only(*attrs)¶

产生新的 Load 对象与 load_only() 选项应用。

见 load_only() 用于示例。

method sqlalchemy.orm.Load.noload(attr)¶

产生新的 Load 对象与 noload() 选项应用。

见 noload() 用于示例。

method sqlalchemy.orm.Load.options(*opts)¶

将一系列选项作为子选项应用于此 Load 对象。

例如。：：

query = session.query(Author)
query = query.options(
            joinedload(Author.book).options(
                load_only(Book.summary, Book.excerpt),
                joinedload(Book.citations).options(
                    joinedload(Citation.author)
                )
            )
        )

参数

*opts¶ -- 一系列加载程序选项对象（最终 Load 对象），应应用于 Load 对象。

1.3.6 新版功能.

参见

defaultload()

与加载程序选项的关系加载

跨多个实体延迟加载

method sqlalchemy.orm.Load.process_compile_state(compile_state)¶

对给定的 CompileState .

method sqlalchemy.orm.Load.process_compile_state_replaced_entities(compile_state, mapper_entities)¶

将修改应用于给定的 CompileState ，给定被替换为WITH_ONLY_COLUMNS()或WITH_ENTITIES()的实体。

1.4.19 新版功能.

method sqlalchemy.orm.Load.raiseload(attr, sql_only=False)¶

产生新的 Load 对象与 raiseload() 选项应用。

见 raiseload() 用于示例。

method sqlalchemy.orm.Load.selectin_polymorphic(classes)¶

产生新的 Load 对象与 selectin_polymorphic() 选项应用。

见 selectin_polymorphic() 用于示例。

method sqlalchemy.orm.Load.selectinload(attr)¶

产生新的 Load 对象与 selectinload() 选项应用。

见 selectinload() 用于示例。

method sqlalchemy.orm.Load.subqueryload(attr)¶

产生新的 Load 对象与 subqueryload() 选项应用。

见 subqueryload() 用于示例。

method sqlalchemy.orm.Load.undefer(key)¶

产生新的 Load 对象与 undefer() 选项应用。

见 undefer() 用于示例。

method sqlalchemy.orm.Load.undefer_group(name)¶

产生新的 Load 对象与 undefer_group() 选项应用。

见 undefer_group() 用于示例。

method sqlalchemy.orm.Load.with_expression(key, expression)¶

产生新的 Load 对象与 with_expression() 选项应用。

见 with_expression() 用于示例。

function sqlalchemy.orm.with_loader_criteria(entity_or_base, where_criteria, loader_only=False, include_aliases=False, propagate_to_loaders=True, track_closure_variables=True)¶

将其他WHERE条件添加到特定实体的所有引用的加载中。

1.4 新版功能.

这个 with_loader_criteria() 选项用于向查询中的特定类型的实体添加限制条件， 全球地 ，这意味着它将应用于在SELECT查询中以及任何子查询、连接条件和关系加载（包括eager和lazy loader）中出现的实体，而无需在查询的任何特定部分指定它。呈现逻辑使用单表继承所使用的相同系统来确保将某个鉴别器应用于表。

E、 g.，使用 2.0-style 查询时，我们可以限制 User.addresses 无论使用何种加载方式，都将加载集合：

from sqlalchemy.orm import with_loader_criteria

stmt = select(User).options(
    selectinload(User.addresses),
    with_loader_criteria(Address, Address.email_address != 'foo'))
)

上面的“selectinload”用于 User.addresses 将应用WHERE筛选条件。

另一个例子，其中过滤将应用于join的ON子句，在这个示例中使用 1.x style 查询：

q = session.query(User).outerjoin(User.addresses).options(
    with_loader_criteria(Address, Address.email_address != 'foo'))
)

主要目的 with_loader_criteria() 就是在 SessionEvents.do_orm_execute() 事件处理程序，以确保以特定方式筛选特定实体的所有实例，例如筛选访问控制角色。它还可以用于对关系加载应用条件。在下面的示例中，我们可以将一组特定的规则应用于 Session ：：

session = Session(bind=engine)

@event.listens_for("do_orm_execute", session)
def _add_filtering_criteria(execute_state):

    if (
        execute_state.is_select
        and not execute_state.is_column_load
        and not execute_state.is_relationship_load
    ):
        execute_state.statement = execute_state.statement.options(
            with_loader_criteria(
                SecurityRole,
                lambda cls: cls.role.in_(['some_role']),
                include_aliases=True
            )
        )

在上面的示例中， SessionEvents.do_orm_execute() 事件将截获使用 Session 。对于那些是SELECT语句且不是属性或关系的查询，会加载自定义 with_loader_criteria() 选项添加到查询中。这个 with_loader_criteria() 选项将在给定语句中使用，并且还将自动传播到从此查询派生的所有关系加载。

给出的条件参数是 lambda 它接受一个 cls 论点。给定的类将扩展为包括所有映射的子类，并且本身不必是映射的类。

警告

在调用中使用lambda来 with_loader_criteria() 仅调用 每个唯一类一次 。不应在此lambda内调用自定义函数。看见 使用Lambdas为语句生成添加显著的速度增益 获取“lambda SQL”特性的概述，该特性仅供高级使用。

参数

• entity_or_base¶ -- 一个映射类，或者是一组特定映射类的超类，该规则将应用于该类。

• where_criteria¶ -- 应用限制条件的核心SQL表达式。这也可能是一个“lambda:”或Python函数，当给定的类是具有许多不同映射子类的基时，它接受目标类作为参数。

• include_aliases¶ -- 如果为True，则将规则应用于 aliased() 构造。

• propagate_to_loaders¶ -- 默认为True，应用于关系加载器，如lazy loader。

参见

ORM查询事件 -包括使用的示例 with_loader_criteria() .

添加全局WHERE/ON条件 -如何组合的基本示例 with_loader_criteria() 与 SessionEvents.do_orm_execute() 事件。

参数

track_closure_variables¶ -- 如果为false，则lambda表达式中的闭包变量不会用作任何缓存键的一部分。这允许在lambda表达式内部使用更复杂的表达式，但要求lambda确保每次给定特定类时都返回相同的SQL。。。添加的版本：：1.4.0b2

function sqlalchemy.orm.join(left, right, onclause=None, isouter=False, full=False, join_to_left=None)¶

在左子句和右子句之间生成内部联接。

join() 是由提供的核心联接接口的扩展 join() ，其中，左和右可选择项可能不仅是核心可选择对象，例如 Table ，但也映射类或 AliasedClass 实例。“on”子句可以是SQL表达式，也可以是引用已配置的 relationship() .

join() 在现代使用中并不常用，因为它的功能封装在 Query.join() 方法，它的特点是在 join() 独自一人。明确使用 join() 具有 Query 涉及使用 Query.select_from() 方法，如：

from sqlalchemy.orm import join
session.query(User).\
    select_from(join(User, Address, User.addresses)).\
    filter(Address.email_address=='foo@bar.com')

在现代的SQLAlchemy中，上面的连接可以更简洁地写为：

session.query(User).\
        join(User.addresses).\
        filter(Address.email_address=='foo@bar.com')

见 Query.join() 有关ORM级联接的现代用法的信息。

0.8 版后已移除: 这个 join_to_left 参数已弃用，将在将来的版本中删除。参数无效。

function sqlalchemy.orm.outerjoin(left, right, onclause=None, full=False, join_to_left=None)¶

在左子句和右子句之间生成左外部联接。

这是“外部联接”版本的 join() 函数，除了生成一个外部联接之外，它具有相同的行为。有关其他用法的详细信息，请参阅该函数的文档。

function sqlalchemy.orm.with_parent(instance, prop, from_entity=None)¶

使用已建立的筛选条件，创建将此查询的主实体与给定的相关实例关联的筛选条件 relationship() 配置。

例如。：：

stmt = select(Address).where(with_parent(some_user, Address.user))

呈现的SQL与当惰性加载程序将从该属性的给定父对象中触发时呈现的SQL相同，这意味着在python中从父对象获取适当的状态，而无需在呈现的语句中呈现到父表的联接。

给定的财产也可以利用 PropComparator.of_type() 表示标准的左侧：

a1 = aliased(Address)
a2 = aliased(Address)
stmt = select(a1, a2).where(
    with_parent(u1, User.addresses.of_type(a2))
)

上述用法相当于使用 from_entity() 论点：

a1 = aliased(Address)
a2 = aliased(Address)
stmt = select(a1, a2).where(
    with_parent(u1, User.addresses, from_entity=a2)
)

参数

• instance¶ -- 一个有一些 relationship() .

• property¶ -- 字符串属性名或类绑定属性，它指示应使用实例中的哪个关系来协调父/子关系。。已弃用：：不推荐使用字符串的1.4，它将在SQLAlchemy 2.0中删除。请直接使用类绑定属性。

• from_entity¶ -- 作为左侧考虑的实体。这默认为 Query 本身。…添加的版本：1.2