查询对象¶

Query is produced in terms of a given Session, using the query() method:

q = session.query(SomeMappedClass)

以下是Query对象的完整界面。

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

ORM级的SQL构造对象。

Query is the source of all SELECT statements generated by the ORM, both those formulated by end-user query operations as well as by high level internal operations such as related collection loading. 它具有一个生成接口，通过这个接口，连续调用返回一个新的Query对象，前者的副本带有与其相关的附加条件和选项。

Query对象通常最初使用Session的query()方法生成。有关Query用法的完整演练，请参阅Object Relational Tutorial。

add_column T0> （ T1> 列 T2> ） T3> ¶ T4>

将列表达式添加到要返回的结果列表的列表中。

等待弃用：add_column()将被add_columns()取代。

add_columns T0> （ T1> *柱 T2> ） T3> ¶ T4>

将一个或多个列表达式添加到要返回的结果列表的列表中。

add_entity （ entity，alias = None ） t5 >

将映射实体添加到要返回的结果列的列表中。

所有 T0> （ T1> ） T2> ¶ T3>

将Query表示的结果作为列表返回。

这导致底层查询的执行。

as_scalar T0> （ T1> ） T2> ¶ T3>

返回由此Query表示的完整SELECT语句，转换为标量子查询。

类似于sqlalchemy.sql.expression.SelectBase.as_scalar()。

版本0.6.5中的新功能

自动冲洗 T0> （ T1> 设置 T2> ） T3> ¶ T4>

使用特定的“自动刷新”设置返回查询。

请注意，即使在查询级别将此标志设置为True，具有autoflush = False的会话也不会自动刷新。因此此标志通常仅用于禁用特定查询的自动刷新。

column_descriptions T0> ¶ T1>

返回有关由Query返回的列的元数据。

格式是词典的列表：

user_alias = aliased(User, name='user2')
q = sess.query(User, User.id, user_alias)

# this expression:
q.column_descriptions

# would return:
[
    {
        'name':'User',
        'type':User,
        'aliased':False,
        'expr':User,
        'entity': User
    },
    {
        'name':'id',
        'type':Integer(),
        'aliased':False,
        'expr':User.id,
        'entity': User
    },
    {
        'name':'user2',
        'type':User,
        'aliased':True,
        'expr':user_alias,
        'entity': user_alias
    }
]

归属关系 T0> （ T1> * ARGS T2> ） T3> ¶ T4>

返回一个Query结构，它将给定的FROM子句与一个包含Query或select()的子句关联起来。

此处的方法接受映射类，aliased()构造和mapper()构造作为参数，除了适当的表达式构造之外，它们被解析为表达式构造。

相关参数在强制转换为表达式结构后最终传递给Select.correlate()。

在使用Query.from_self()时，或者当由Query.subquery()返回的子查询嵌入另一个select()构造。

计数 T0> （ T1> ） T2> ¶ T3>

返回此Query将返回的行数。

这将为此查询生成SQL，如下所示：

SELECT count(1) AS count_1 FROM (
    SELECT <rest of query follows...>
) AS anon_1

Changed in version 0.7: The above scheme is newly refined as of 0.7b3.

要细化对特定列进行计数的控制，要跳过子查询的使用或控制FROM子句或使用其他聚合函数，请将func表达式与query()，即：

from sqlalchemy import func

# count User records, without
# using a subquery.
session.query(func.count(User.id))

# return count of user "id" grouped
# by "name"
session.query(func.count(User.id)).\
        group_by(User.name)

from sqlalchemy import distinct

# count distinct "name" values
session.query(func.count(distinct(User.name)))

cte(name=None, recursive=False)¶

返回由Query表示的完整SELECT语句，表示为一个公用表表达式（CTE）。

参数和用法与SelectBase.cte()方法的参数和用法相同；请参阅该方法了解更多详情。

这里是Postgresql WITH RECURSIVE示例。请注意，在本例中，它的included_parts cte和incl_alias别名是核心可选项，这意味着通过.c.属性。parts_alias对象是Part实体的orm.aliased()实例，因此列映射属性可直接使用：

from sqlalchemy.orm import aliased

class Part(Base):
    __tablename__ = 'part'
    part = Column(String, primary_key=True)
    sub_part = Column(String, primary_key=True)
    quantity = Column(Integer)

included_parts = session.query(
                Part.sub_part,
                Part.part,
                Part.quantity).\
                    filter(Part.part=="our part").\
                    cte(name="included_parts", recursive=True)

incl_alias = aliased(included_parts, name="pr")
parts_alias = aliased(Part, name="p")
included_parts = included_parts.union_all(
    session.query(
        parts_alias.sub_part,
        parts_alias.part,
        parts_alias.quantity).\
            filter(parts_alias.part==incl_alias.c.sub_part)
    )

q = session.query(
        included_parts.c.sub_part,
        func.sum(included_parts.c.quantity).
            label('total_quantity')
    ).\
    group_by(included_parts.c.sub_part)

也可以看看

HasCTE.cte()

删除 T0> （ T1> synchronize_session = '评价' T2> ） T3> ¶ T4>

执行批量删除查询。

从数据库中删除此查询匹配的行。

例如。：

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    delete(synchronize_session='evaluate')

警告

Query.delete()方法是一种“批量”操作，它绕过ORM工作单元自动化，以提高性能。请阅读下面的所有警告和警告。

参数：	synchronize_session ¶ - 选择从会话中删除匹配对象的策略。有效值是： False - 不要同步会话。一旦会话过期，这个选项是最高效和可靠的，通常在commit()之后发生，或者明确地使用expire_all()。在到期之前，对象可能仍然保留在会话中，事实上这些对象被删除，如果通过get()或已经加载的集合访问它们，会导致混淆结果。 'fetch' - 在删除之前执行选择查询，以查找与删除查询匹配并需要从会话中删除的对象。匹配的对象从会话中删除。 'evaluate' - 直接在会话中的对象中评估Python中的查询条件。如果评估标准未实施，则会出现错误。 表达式求值程序目前没有考虑数据库和Python之间的不同字符串整理。
返回：	数据库的“行数”功能返回的行数相匹配。

警告

Additional Caveats for bulk query deletes

• The method does not offer in-Python cascading of relationships - it is assumed that ON DELETE CASCADE/SET NULL/etc. 配置为需要它的任何外键引用，否则如果外键引用被强制执行，数据库可能会发出完整性违规。

  在DELETE之后，受到ON DELETE影响的Session中的相关对象可能不包含当前状态，或可能已被删除。一旦Session过期（通常发生在Session.commit()）或者可以通过使用Session.expire_all()访问行已被删除的过期对象将调用SELECT来定位行；当找不到该行时，会引发ObjectDeletedError。

• 'fetch'策略会导致发出额外的SELECT语句，并且会显着降低性能。

• The 'evaluate' strategy performs a scan of all matching objects within the Session; if the contents of the Session are expired, such as via a proceeding Session.commit() call, this will result in SELECT queries emitted for every matching object.

• MapperEvents.before_delete()和MapperEvents.after_delete()事件不会从此方法调用。相反，提供了SessionEvents.after_bulk_delete()方法来处理实体行的大量DELETE操作。

也可以看看

Query.update()

Inserts, Updates and Deletes - 核心SQL教程

不同 T0> （ T1> *标准 T2> ） T3> ¶ T4>

将DISTINCT应用于查询并返回新生成的Query。

注意

distinct()调用包含的逻辑将自动将查询的ORDER BY中的列添加到SELECT语句的columns子句中，以满足ORDER BY列成为部分的数据库后端的通用需求当使用DISTINCT时，SELECT列表的列表。然而，这些列不会被添加到由Query实际获取的列列表中，因此不会影响结果。但是，使用Query.statement访问器时，列会通过。

参数：	* expr ¶ - 可选的列表达式。当存在时，Postgresql方言将呈现DISTINCT ON （＆lt；表达式＆gt；）结构。

enable_assertions T0> （ T1> 值 T2> ） T3> ¶ T4>

控制是否生成断言。

当设置为False时，返回的Query将不会在某些操作之前声明其状态，包括在调用filter()时未应用LIMIT / OFFSET，调用get()时不存在条件，并且没有“from_statement()”当filter()/ order_by()/ group_by()等存在时叫做。自定义查询子类使用这种更宽松的模式来指定常规使用模式之外的条件或其他修饰符。

应该注意确保使用模式是可能的。例如，由from_statement()应用的语句将覆盖由filter()或order_by()设置的任何条件。

enable_eagerloads T0> （ T1> 值 T2> ） T3> ¶ T4>

控制是否呈现急切联接和子查询。

When set to False, the returned Query will not render eager joins regardless of joinedload(), subqueryload() options or mapper-level lazy='joined'/lazy='subquery' configurations.

这主要用于将Query语句嵌套到子查询或其他可选项中，或者在使用Query.yield_per()时使用。

除了_ T0> （ T1> * Q T2> ） T3> ¶ T4>

针对一个或多个查询生成此查询的EXCEPT。

与union()的工作方式相同。查看使用示例的方法。

except_all T0> （ T1> * Q T2> ） T3> ¶ T4>

针对一个或多个查询生成一个EXCEPT ALL查询。

与union()的工作方式相同。查看使用示例的方法。

execution_options T0> （ T1> ** kwargs T2> ） T3> ¶ T4>

设置在执行期间生效的非SQL选项。

这些选项与Connection.execution_options()接受的选项相同。

请注意，如果使用yield_per()方法，则会自动启用stream_results执行选项。

存在 T0> （ T1> ） T2> ¶ T3>

将查询转换为EXISTS（SELECT 1 FROM ... WHERE ...）形式的EXISTS子查询的便捷方法。

例如。：

q = session.query(User).filter(User.name == 'fred')
session.query(q.exists())

生成SQL类似于：

SELECT EXISTS (
    SELECT 1 FROM users WHERE users.name = :name_1
) AS anon_1

EXISTS结构通常用在WHERE子句中：

session.query(User.id).filter(q.exists()).scalar()

请注意，某些数据库（如SQL Server）不允许EXISTS表达式存在于SELECT的columns子句中。要根据exists的WHERE选择一个简单的布尔值，可以使用literal()：

from sqlalchemy import literal

session.query(literal(True)).filter(q.exists()).scalar()

0.8.1版本中的新功能

过滤 T0> （ T1> *标准 T2> ） T3> ¶ T4>

使用SQL表达式将给定的过滤标准应用于此Query的副本。

例如。：

session.query(MyClass).filter(MyClass.name == 'some name')

多个标准可以指定为逗号分隔；效果是它们将使用and_()函数连接在一起：

session.query(MyClass).\
    filter(MyClass.name == 'some name', MyClass.id > 5)

条件是适用于select的WHERE子句的任何SQL表达式对象。通过text()结构将字符串表达式强制转换为SQL表达式结构。

也可以看看

Query.filter_by() - 对关键字表达式进行过滤。

filter_by T0> （ T1> ** kwargs T2> ） T3> ¶ T4>

使用关键字表达式将给定的过滤标准应用于此Query的副本。

例如。：

session.query(MyClass).filter_by(name = 'some name')

多个标准可以指定为逗号分隔；效果是它们将使用and_()函数连接在一起：

session.query(MyClass).\
    filter_by(name = 'some name', id = 5)

关键字表达式是从查询的主要实体或最后一个调用Query.join()的目标实体提取的。

也可以看看

Query.filter() - 过滤SQL表达式。

第一 T0> （ T1> ） T2> ¶ T3>

如果结果不包含任何行，则返回此Query的第一个结果或None。

first()在生成的SQL中应用一个限制，以便在服务器端仅生成一个主要实体行（注意，如果存在连接加载的集合，则这可能包含多个结果行）。

调用Query.first()会导致执行基础查询。

也可以看看

Query.one()

Query.one_or_none()

from_self T0> （ T1> *实体 T2> ） T3> ¶ T4>

返回从此查询的SELECT语句中选择的Query。

Query.from_self() essentially turns the SELECT statement into a SELECT of itself. 给定一个查询，如：

q = session.query(User).filter(User.name.like('e%'))

给定Query.from_self()版本：

q = session.query(User).filter(User.name.like('e%')).from_self()

此查询呈现为：

SELECT anon_1.user_id AS anon_1_user_id,
       anon_1.user_name AS anon_1_user_name
FROM (SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE "user".name LIKE :name_1) AS anon_1

有很多情况下，Query.from_self()可能会有用。一个简单的方法就是在上面，我们可能希望将一行LIMIT应用到我们查询的用户对象集合，然后对该行有限集合应用其他连接：

q = session.query(User).filter(User.name.like('e%')).\
    limit(5).from_self().\
    join(User.addresses).filter(Address.email.like('q%'))

上述查询连接到Address实体，但仅针对User查询的前五个结果：

SELECT anon_1.user_id AS anon_1_user_id,
       anon_1.user_name AS anon_1_user_name
FROM (SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE "user".name LIKE :name_1
 LIMIT :param_1) AS anon_1
JOIN address ON anon_1.user_id = address.user_id
WHERE address.email LIKE :email_1

自动别名

Query.from_self()的另一个关键行为是，当子查询内部的实体在外部引用时，它将自动别名应用到子查询中的实体。在上面，如果我们继续引用User实体而没有应用任何额外的别名，那么这些引用将以子查询的形式表示：

q = session.query(User).filter(User.name.like('e%')).\
    limit(5).from_self().\
    join(User.addresses).filter(Address.email.like('q%')).\
    order_by(User.name)

针对User.name的ORDER BY被别名为内部子查询：

SELECT anon_1.user_id AS anon_1_user_id,
       anon_1.user_name AS anon_1_user_name
FROM (SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE "user".name LIKE :name_1
 LIMIT :param_1) AS anon_1
JOIN address ON anon_1.user_id = address.user_id
WHERE address.email LIKE :email_1 ORDER BY anon_1.user_name

对于简单的过滤器和排序，自动别名功能只能以限制方式工作。比较引人注目的构造，例如引用连接中的实体，应该更喜欢使用明确的子查询对象，通常使用Query.subquery()方法生成显式的子查询对象。总是通过查看SQL来测试查询的结构，以确保特定的结构符合预期！

更改实体

Query.from_self() also includes the ability to modify what columns are being queried. 在我们的例子中，我们想通过内部查询来查询User.id，以便我们可以连接到外部的Address实体，但我们只需要外部查询返回Address.email列：

q = session.query(User).filter(User.name.like('e%')).\
    limit(5).from_self(Address.email).\
    join(User.addresses).filter(Address.email.like('q%'))

收益：

SELECT address.email AS address_email
FROM (SELECT "user".id AS user_id, "user".name AS user_name
FROM "user"
WHERE "user".name LIKE :name_1
 LIMIT :param_1) AS anon_1
JOIN address ON anon_1.user_id = address.user_id
WHERE address.email LIKE :email_1

寻找内部/外部列

请记住，当引用源自子查询内部的列时，我们需要确保它们存在于子查询本身的列子句中；这是SQL的一个普通方面。例如，如果我们想要使用contains_eager()从子查询中的连接实体加载，我们需要添加这些列。下面举例说明Address到User的连接，然后是子查询，然后我们希望contains_eager()访问User列：

q = session.query(Address).join(Address.user).\
    filter(User.name.like('e%'))

q = q.add_entity(User).from_self().\
    options(contains_eager(Address.user))

We use Query.add_entity() above before we call Query.from_self() so that the User columns are present in the inner subquery, so that they are available to the contains_eager() modifier we are using on the outside, producing:

SELECT anon_1.address_id AS anon_1_address_id,
       anon_1.address_email AS anon_1_address_email,
       anon_1.address_user_id AS anon_1_address_user_id,
       anon_1.user_id AS anon_1_user_id,
       anon_1.user_name AS anon_1_user_name
FROM (
    SELECT address.id AS address_id,
    address.email AS address_email,
    address.user_id AS address_user_id,
    "user".id AS user_id,
    "user".name AS user_name
FROM address JOIN "user" ON "user".id = address.user_id
WHERE "user".name LIKE :name_1) AS anon_1

If we didn’t call add_entity(User), but still asked contains_eager() to load the User entity, it would be forced to add the table on the outside without the correct join criteria - note the anon1, "user" phrase at the end:

-- incorrect query
SELECT anon_1.address_id AS anon_1_address_id,
       anon_1.address_email AS anon_1_address_email,
       anon_1.address_user_id AS anon_1_address_user_id,
       "user".id AS user_id,
       "user".name AS user_name
FROM (
    SELECT address.id AS address_id,
    address.email AS address_email,
    address.user_id AS address_user_id
FROM address JOIN "user" ON "user".id = address.user_id
WHERE "user".name LIKE :name_1) AS anon_1, "user"

参数：	*entities¶ – optional list of entities which will replace those being selected.

from_statement T0> （ T1> 语句 T2> ） T3> ¶ T4>

执行给定的SELECT语句并返回结果。

此方法绕过所有内部语句编译，并且语句不加修改地执行。

该语句通常是一个text()或select()结构，并且应返回适合该Query

也可以看看

Using Textual SQL - ORM教程中的使用示例

获得 T0> （ T1> IDENT T2> ） T3> ¶ T4>

基于给定的主键标识符返回实例，如果未找到，则返回None。

例如。：

my_user = session.query(User).get(5)

some_object = session.query(VersionedFoo).get((5, 10))

get() is special in that it provides direct access to the identity map of the owning Session. 如果给定主键标识符存在于本地标识映射中，则直接从该集合返回对象，并且不会发出SQL，除非该对象已标记为完全过期。如果不存在，则执行SELECT以查找对象。

get() also will perform a check if the object is present in the identity map and marked as expired - a SELECT is emitted to refresh the object as well as to ensure that the row is still present. 如果不是，则引发ObjectDeletedError。

get() is only used to return a single mapped instance, not multiple instances or individual column constructs, and strictly on a single primary key value. 必须以这种方式构建始发的Query，即针对单个映射的实体，而不需要附加的过滤标准。通过options()加载选项可能会被应用，但是如果对象尚未本地存在，将会被使用。

使用简单的外键到主键标准，由relationship()配置的延迟加载多对一属性也将使用与get()，以便在查询数据库之前从本地标识映射中检索目标值。有关关系加载的更多详细信息，请参见Relationship Loading Techniques。

参数：	ident¶ – A scalar or tuple value representing the primary key. 对于组合主键，标识符的顺序在大多数情况下与映射的Table对象的主键列相对应。For a mapper() that was given the primary key argument during construction, the order of identifiers corresponds to the elements present in this collection.
返回：	对象实例，或None。

GROUP_BY T0> （ T1> *标准 T2> ） T3> ¶ T4>

将一个或多个GROUP BY标准应用于查询并返回新生成的Query

具有 T0> （ T1> 标准 T2> ） T3> ¶ T4>

将HAVING条件应用于查询并返回新生成的Query。

having() is used in conjunction with group_by().

HAVING标准可以在COUNT，SUM，AVG，MAX和MIN等集合函数上使用过滤器，例如。:

q = session.query(User.id).\
            join(User.addresses).\
            group_by(User.id).\
            having(func.count(Address.id) > 2)

实例 （ 游标，_Query__context =无 ） t5 >

给定由connection.execute()返回的ResultProxy游标，返回一个ORM结果作为迭代器。

例如。：

result = engine.execute("select * from users")
for u in session.query(User).instances(result):
    print u

相交 T0> （ T1> * Q T2> ） T3> ¶ T4>

根据一个或多个查询生成此查询的INTERSECT。

与union()的工作方式相同。查看使用示例的方法。

intersect_all T0> （ T1> * Q T2> ） T3> ¶ T4>

针对一个或多个查询生成此查询的INTERSECT ALL。

与union()的工作方式相同。查看使用示例的方法。

join tt> （ * props，** kwargs ） T5>

根据Query对象的标准创建SQL JOIN并生成应用，返回最新生成的Query。

简单的关系加入

考虑两个类User和Address之间的映射，其中User.addresses表示Address对象的集合与每个User关联。join()的最常见用法是使用User.addresses属性作为这种情况发生的指示符，以此关系创建JOIN：

q = session.query(User).join(User.addresses)

在上面，沿着User.addresses调用join()将导致SQL等同于：

SELECT user.* FROM user JOIN address ON user.id = address.user_id

在上面的例子中，我们将User.addresses作为on子句传递给join()，也就是说， ON“部分的JOIN应该被构建。对于像上面那样的单一实体查询（即，我们只从User开始，而没有其他选择），关系也可以用字符串名称来指定：

q = session.query(User).join("addresses")

join()也可以容纳多个“on子句”参数来产生连接链，例如在下面构建跨四个相关实体的连接：

q = session.query(User).join("orders", "items", "keywords")

上述内容可以简短地描述三次对join()的单独调用，每个调用都使用显式属性来指示源实体：

q = session.query(User).\
        join(User.orders).\
        join(Order.items).\
        join(Item.keywords)

加入目标实体或可选

第二种形式的join()允许任何映射实体或核心可选结构作为目标。在这种用法中，join()将尝试沿两个实体之间的自然外键关系创建JOIN：

q = session.query(User).join(Address)

如果两个实体之间没有外键，或者它们之间有多个外键链接，join()的上述调用形式将引发错误。在上面的调用形式中，join()被调用来为我们自动创建“on子句”。目标可以是任何映射实体或可选，如Table：

q = session.query(User).join(addresses_table)

使用ON子句加入目标

第三个调用形式允许明确传递目标实体以及ON子句。假设我们想要加入Address两次，第二次使用别名。我们使用aliased()创建Address的不同别名，并使用目标， / t7>表单，以便可以将该别名与关系一起显式指定为目标，以指示ON子句应如何继续：

a_alias = aliased(Address)

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

以上所述，生成的SQL将类似于：

SELECT user.* FROM user
    JOIN address ON user.id = address.user_id
    JOIN address AS address_1 ON user.id=address_1.user_id
    WHERE address.email_address = :email_address_1
    AND address_1.email_address = :email_address_2

join()的双参数调用形式也允许我们构建任意连接，并使用面向SQL的“on子句”表达式，而不是完全依赖配置关系。在使用双参数形式时，任何SQL表达式都可以作为ON子句传递，它应该以某种方式引用目标实体以及适用的源实体：

q = session.query(User).join(Address, User.id==Address.user_id)

在版本0.7中更改：在SQLAlchemy 0.6及更早版本中，join()的两个参数形式需要使用元组：query（User） .join（（地址， User.id == Address.user_id））。这个调用形式在0.7中被接受，并且更进一步，除非多个连接条件被传递给单个join()调用，否则它是不必要的，它本身也不是必需的，因为它现在等同于多个调用（情况并非总是如此）。

高级连接定位和自适应

在使用join()时，“目标”可以具有很大的灵活性。如前所述，它还接受Table结构和其他可选项，例如alias()和select()结构，其中一个或两个 - 形式：

addresses_q = select([Address.user_id]).\
            where(Address.email_address.endswith("@bar.com")).\
            alias()

q = session.query(User).\
            join(addresses_q, addresses_q.c.user_id==User.id)

join() also features the ability to adapt a relationship() -driven ON clause to the target selectable. 下面我们构造一个从User到Address的子查询的JOIN，允许User.addresses到adapt t6 >本身改变目标：

address_subq = session.query(Address).\
                filter(Address.email_address == 'ed@foo.com').\
                subquery()

q = session.query(User).join(address_subq, User.addresses)

生成SQL类似于：

SELECT user.* FROM user
    JOIN (
        SELECT address.id AS id,
                address.user_id AS user_id,
                address.email_address AS email_address
        FROM address
        WHERE address.email_address = :email_address_1
    ) AS anon_1 ON user.id = anon_1.user_id

上面的表格允许在任何时候回到明确的ON子句上：

q = session.query(User).\
        join(address_subq, User.id==address_subq.c.user_id)

控制要从加入的内容

虽然join()专门处理JOIN的“右侧”，但我们也可以在需要的情况下使用select_from()下面我们构建一个针对Address的查询，但是仍然可以通过指示Query从第一个选择第一个作为ON子句来使用User.addresses User实体：

q = session.query(Address).select_from(User).\
                join(User.addresses).\
                filter(User.name == 'ed')

这将产生SQL类似于：

SELECT address.* FROM user
    JOIN address ON user.id=address.user_id
    WHERE user.name = :name_1

匿名构建别名

join() can construct anonymous aliases using the aliased=True flag. 当查询以算法方式加入时，如自查询到任意深度时，此功能非常有用：

q = session.query(Node).\
        join("children", "children", aliased=True)

当使用aliased=True时，实际的“别名”结构不明确可用。要使用它，诸如Query.filter()等方法将使传入实体适应最后一个连接点：

q = session.query(Node).\
        join("children", "children", aliased=True).\
        filter(Node.name == 'grandchild 1')

使用自动别名时，from_joinpoint=True参数可以允许将多节点连接分解为对join()的多次调用，以便每个路径都可以进一步过滤：

q = session.query(Node).\
        join("children", aliased=True).\
        filter(Node.name='child 1').\
        join("children", aliased=True, from_joinpoint=True).\
        filter(Node.name == 'grandchild 1')

上面的过滤别名可以使用reset_joinpoint()重置回原始的Node实体：

q = session.query(Node).\
        join("children", "children", aliased=True).\
        filter(Node.name == 'grandchild 1').\
        reset_joinpoint().\
        filter(Node.name == 'parent 1)

有关aliased=True的示例，请参阅分发示例XML Persistence，其中演示了使用算法联接的类似XPath的查询系统。

参数：

*props¶ – A collection of one or more join conditions, each consisting of a relationship-bound attribute or string relationship name representing an “on clause”, or a single target entity, or a tuple in the form of (target, onclause). 还可以接受目标， 形式的特殊双参数调用形式。 aliased = False ¶ - 如果为True，表明JOIN目标应该匿名别名。随后对filter()和类似的调用将使输入标准适应目标别名，直到调用reset_joinpoint()。 isouter = False ¶ - 如果为True，则使用的连接将是左外连接，就像调用Query.outerjoin()方法一样。这个标志在这里保持与FromClause.join()和其他Core结构所接受的相同标志的一致性。 版本1.0.0中的新功能 full = False ¶ - 渲染全外连接；意味着isouter。 版本1.1中的新功能 from_joinpoint=False¶ – When using aliased=True, a setting of True here will cause the join to be from the most recent joined target, rather than starting back from the original FROM clauses of the query.

也可以看看

在ORM教程中Querying with Joins。

有关如何将join()用于继承关系的详细信息，请参见Mapping Class Inheritance Hierarchies。

orm.join() - a standalone ORM-level join function, used internally by Query.join(), which in previous SQLAlchemy versions was the primary ORM-level joining interface.

标签 T0> （ T1> 名称 T2> ） T3> ¶ T4>

返回由Query表示的完整SELECT语句，将其转换为具有给定名称标签的标量子查询。

类似于sqlalchemy.sql.expression.SelectBase.label()。

版本0.6.5中的新功能

限制 T0> （ T1> 限制 T2> ） T3> ¶ T4>

将LIMIT应用于查询并返回新生成的Query。

merge_result （ iterator，load = True ） t5 >

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

给定一个与此结构相同结构的Query返回的迭代器，返回结果的相同迭代器，所有映射实例都使用Session.merge()合并到会话中。这是一种优化的方法，它将合并所有映射的实例，为每个值明确调用Session.merge()，从而以较少的方法开销保留结果行和未映射列的结构。

结果的结构是根据这个Query的列表确定的 - 如果这些不一致，则会发生未经检查的错误。

'load'参数与Session.merge()相同。

有关如何使用merge_result()的示例，请参阅示例Dogpile Caching的源代码，其中merge_result()用于高效将状态从缓存恢复回目标Session。

偏移 T0> （ T1> 偏移 T2> ） T3> ¶ T4>

对查询应用一个OFFSET并返回新生成的Query。

一个 T0> （ T1> ） T2> ¶ T3>

只返回一个结果或引发异常。

如果查询未选择任何行，则引发sqlalchemy.orm.exc.NoResultFound。如果返回多个对象标识，或者如果为仅返回标量值的查询返回多个行而不是完整的标识映射实体，则引发sqlalchemy.orm.exc.MultipleResultsFound。

调用one()会导致执行基础查询。

也可以看看

Query.first()

Query.one_or_none()

one_or_none T0> （ T1> ） T2> ¶ T3>

至多返回一个结果或引发异常。

如果查询未选择任何行，则返回None。如果返回多个对象标识，或者如果为仅返回标量值的查询返回多个行而不是完整的标识映射实体，则引发sqlalchemy.orm.exc.MultipleResultsFound。

调用Query.one_or_none()会导致执行基础查询。

版本1.0.9新增：添加了Query.one_or_none()

也可以看看

Query.first()

Query.one()

选项 T0> （ T1> * ARGS T2> ） T3> ¶ T4>

返回一个新的查询对象，应用给定的映射器选项列表。

大多数提供的选项都会改变如何加载列和关系映射属性。有关参考文档，请参阅Deferred Column Loading和Relationship Loading Techniques部分。

ORDER_BY T0> （ T1> *标准 T2> ） T3> ¶ T4>

将一个或多个ORDER BY标准应用于查询并返回新生成的Query

所有现有的ORDER BY设置都可以通过传递None

或者，通过传递False作为值，可以完全取消Query对象上现有的ORDER BY设置 - 在调用ORDER BY无效的方法之前使用此设置。

外连接 （ * props，** kwargs ） T5>

根据此Query对象的标准创建左外连接，并生成应用，返回新生成的Query。

用法与join()方法相同。

params （ * args，** kwargs ） T5>

添加可能已经在filter()中指定的绑定参数的值。

参数可以使用** kwargs或可选的单个字典指定为第一个位置参数。两者的原因是** kwargs很方便，但是一些参数字典包含unicode键，在这种情况下** kwargs不能使用。

populate_existing T0> （ T1> ） T2> ¶ T3>

返回一个Query，它将在加载时刷新所有实例，或刷新当前Session中的所有实例。

populate_existing() does not improve behavior when the ORM is used normally - the Session object’s usual behavior of maintaining a transaction and expiring all attributes after rollback or commit handles object state automatically. 此方法不适用于一般用途。

prefix_with T0> （ T1> *前缀 T2> ） T3> ¶ T4>

将前缀应用于查询并返回新生成的Query。

参数：	* prefixes ¶ - 可选前缀，通常是字符串，不使用任何逗号。对于MySQL关键字尤其有用。

例如。：

query = sess.query(User.name).\
    prefix_with('HIGH_PRIORITY').\
    prefix_with('SQL_SMALL_RESULT', 'ALL')

会呈现：

SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name
FROM users

New in version 0.7.7.

也可以看看

HasPrefixes.prefix_with()

reset_joinpoint T0> （ T1> ） T2> ¶ T3>

返回一个新的Query，其中“连接点”已被重置回查询的基本FROM实体。

此方法通常与join()方法的aliased=True特性结合使用。请参阅join()中的示例了解如何使用它。

标量 T0> （ T1> ） T2> ¶ T3>

返回第一个结果的第一个元素，如果没有行存在，返回None。如果返回多行，则引发MultipleResultsFound。

>>> session.query(Item).scalar()
<Item>
>>> session.query(Item.id).scalar()
1
>>> session.query(Item.id).filter(Item.id < 0).scalar()
None
>>> session.query(Item.id, Item.name).scalar()
1
>>> session.query(func.count(Parent.id)).scalar()
20

这导致底层查询的执行。

select_entity_from T0> （ T1> from_obj T2> ） T3> ¶ T4>

将此Query的FROM子句设置为可选的核心，将其作为替代的FROM子句应用于相应的映射实体。

这个方法类似于Query.select_from()方法，因为它设置查询的FROM子句。但是，Query.select_from()仅影响放置在FROM中的内容，此方法也适用给定的可选项来替换所选实体通常从中选择的FROM。

The given from_obj must be an instance of a FromClause, e.g. a select() or Alias construct.

An example would be a Query that selects User entities, but uses Query.select_entity_from() to have the entities selected from a select() construct instead of the base user table:

select_stmt = select([User]).where(User.id == 7)

q = session.query(User).\
        select_entity_from(select_stmt).\
        filter(User.name == 'ed')

生成的查询将直接从给定的select()构造中选择User个实体，并且将为：

SELECT anon_1.id AS anon_1_id, anon_1.name AS anon_1_name
FROM (SELECT "user".id AS id, "user".name AS name
FROM "user"
WHERE "user".id = :id_1) AS anon_1
WHERE anon_1.name = :name_1

注意，即使WHERE标准是“适应性的”，使得anon_1子查询有效地替代了所有对user表的引用，除了它在内部引用的那个。

将它与Query.select_from()进行比较，该版本的版本为0.9，不会影响现有实体。以下声明：

q = session.query(User).\
        select_from(select_stmt).\
        filter(User.name == 'ed')

生成SQL，其中user表以及select_stmt构造在FROM子句中作为单独的元素存在。没有应用user表的“自适应”：

SELECT "user".id AS user_id, "user".name AS user_name
FROM "user", (SELECT "user".id AS id, "user".name AS name
FROM "user"
WHERE "user".id = :id_1) AS anon_1
WHERE "user".name = :name_1

Query.select_entity_from()保持Query.select_from()的旧行为。在现代使用中，使用aliased()也可以实现类似的结果：

select_stmt = select([User]).where(User.id == 7)
user_from_select = aliased(User, select_stmt.alias())

q = session.query(user_from_select)

参数：	from_obj¶ – a FromClause object that will replace the FROM clause of this Query.

也可以看看

Query.select_from()

0.8版新增： Query.select_entity_from()被添加来指定实体替换的具体行为，但是Query.select_from()这种行为以及直到0.9。

select_from T0> （ T1> * from_obj T2> ） T3> ¶ T4>

显式地设置这个Query的FROM子句。

Query.select_from() is often used in conjunction with Query.join() in order to control which entity is selected from on the “left” side of the join.

The entity or selectable object here effectively replaces the “left edge” of any calls to join(), when no joinpoint is otherwise established - usually, the default “join point” is the leftmost entity in the Query object’s list of entities to be selected.

一个典型的例子：

q = session.query(Address).select_from(User).\
    join(User.addresses).\
    filter(User.name == 'ed')

其中生成的SQL等同于：

SELECT address.* FROM user
JOIN address ON user.id=address.user_id
WHERE user.name = :name_1

参数：	* from_obj ¶ - 应用于FROM子句的一个或多个实体的集合。实体可以是映射类，AliasedClass对象，Mapper对象以及像子查询这样的核心FromClause元素。

在版本0.9中更改：此方法不再将给定的FROM对象应用于匹配实体从中选择的可选项； select_entity_from()方法现在可以完成此操作。请参阅该方法以了解此行为的说明。

也可以看看

join()

Query.select_entity_from()

可选 T0> ¶ T1>

返回由此Query发出的Select对象。

用于inspect()兼容性，这相当于：

query.enable_eagerloads(False).with_labels().statement

切片 （ 开始，停止 ）

计算由给定索引表示的Query的“片段”并返回结果的Query。

开始和停止索引的行为与Python内置的range()函数的参数类似。此方法提供了使用LIMIT / OFFSET来获取查询片段的替代方法。

例如，

session.query(User).order_by(User.id).slice(1, 3)

呈现为

SELECT users.id AS users_id,
       users.name AS users_name
FROM users ORDER BY users.id
LIMIT ? OFFSET ?
(2, 1)

也可以看看

Query.limit()

Query.offset()

语句 T0> ¶ T1>

此Query所表示的完整SELECT语句。

默认情况下，声明不会消除应用于构造的标签，除非首先调用with_labels（True）。

subquery （ name = None，with_labels = False，reduce_columns = False ） T5> ¶ T6>

返回嵌入在Alias中的由此Query表示的完整SELECT语句。

查询中的Eager JOIN生成被禁用。

参数：

name ¶ - 要指定为别名的字符串名称；这会传递给FromClause.alias()。如果None，则会在编译时确定性地生成名称。 with_labels¶ – if True, with_labels() will be called on the Query first to apply table-qualified labels to all columns. reduce_columns ¶ - if True, Select.reduce_columns() will be called on the resulting select() construct, to remove same-named columns where one also refers to the other via foreign key or WHERE clause equivalence. 在版本0.8中更改：添加了with_labels和reduce_columns关键字参数。

suffix_with T0> （ T1> *后缀 T2> ） T3> ¶ T4>

将后缀应用于查询并返回新生成的Query。

参数：	*后缀 ¶ - 可选后缀，通常是字符串，不使用任何逗号。

版本1.0.0中的新功能

也可以看看

Query.prefix_with()

HasSuffixes.suffix_with()

联合 T0> （ T1> * Q T2> ） T3> ¶ T4>

根据一个或多个查询生成此查询的一个UNION。

例如。：

q1 = sess.query(SomeClass).filter(SomeClass.foo=='bar')
q2 = sess.query(SomeClass).filter(SomeClass.bar=='foo')

q3 = q1.union(q2)

该方法接受多个Query对象以控制嵌套的级别。一系列union()调用，例如：

x.union(y).union(z).all()

将嵌套在每个union()上，并生成：

SELECT * FROM (SELECT * FROM (SELECT * FROM X UNION
                SELECT * FROM y) UNION SELECT * FROM Z)

鉴于：

x.union(y, z).all()

生产：

SELECT * FROM (SELECT * FROM X UNION SELECT * FROM y UNION
                SELECT * FROM Z)

请注意，许多数据库后端不允许在UNION，EXCEPT等内部调用的查询上呈现ORDER BY。要禁用所有ORDER BY子句（包括映射器上配置的子句），发出query.order_by(None) - 生成的Query对象不会在其SELECT语句中呈现ORDER BY。

union_all T0> （ T1> * Q T2> ） T3> ¶ T4>

针对一个或多个查询生成此查询的UNION ALL。

与union()的工作方式相同。查看使用示例的方法。

更新 （ 值，synchronize_session ='评估'，update_args =无 ） T5> ¶ T6>

执行批量更新查询。

更新数据库中此查询匹配的行。

例如。：

sess.query(User).filter(User.age == 25).\
    update({User.age: User.age - 10}, synchronize_session=False)

sess.query(User).filter(User.age == 25).\
    update({"age": User.age - 10}, synchronize_session='evaluate')

警告

Query.update()方法是一种“批量”操作，绕过ORM工作单元自动化，以提高性能。请阅读下面的所有警告和警告。

参数：

值 ¶ - 一个带有属性名称的字典，或者映射属性或SQL表达式作为键，字面值或sql表达式作为值。如果需要parameter-ordered mode，则这些值可以作为2元组列表传递；这要求将preserve_parameter_order标志传递给Query.update.update_args字典。 版本1.0.0更改： - 值字典中的字符串名称现在针对映射的实体进行解析；以前，这些字符串是作为文字列名传递的，没有映射器级别的转换。 synchronize_session ¶ - 选择策略来更新会话中对象的属性。有效值是： False - 不要同步会话。一旦会话过期，这个选项是最高效和可靠的，通常在commit()之后发生，或者明确地使用expire_all()。在到期之前，更新的对象可能仍然保留在会话中，其属性上的陈旧值会导致混淆结果。 'fetch' - 在更新之前执行选择查询以查找与更新查询匹配的对象。已更新的属性在匹配的对象上过期。 'evaluate' - 直接在会话中的对象中评估Python中的查询条件。如果评估标准没有实施，则会引发例外。 表达式求值程序目前没有考虑数据库和Python之间的不同字符串整理。 update_args ¶ - 可选字典（如果存在）将作为该对象的**kw传递给底层的update()结构。可用于传递特定于方言的参数，如mysql_limit以及其他特殊参数，如preserve_parameter_order。 版本1.0.0中的新功能

返回：

数据库的“行数”功能返回的行数相匹配。

警告

批量查询更新的其他注意事项

• The method does not offer in-Python cascading of relationships - it is assumed that ON UPDATE CASCADE is configured for any foreign key references which require it, otherwise the database may emit an integrity violation if foreign key references are being enforced.

  UPDATE之后，受到ON UPDATE CASCADE影响的Session中的依赖对象可能不包含当前状态；一旦Session过期（通常发生在Session.commit()或可以通过使用Session.expire_all() >。

• 'fetch'策略会导致发出额外的SELECT语句，并且会显着降低性能。

• The 'evaluate' strategy performs a scan of all matching objects within the Session; if the contents of the Session are expired, such as via a proceeding Session.commit() call, this will result in SELECT queries emitted for every matching object.

• 该方法支持多表更新，详见Multiple Table Updates，并且此行为的扩展支持已加入继承和其他多个表映射的更新。但是，继承映射器的连接条件不会自动呈现。任何多表更新都必须小心，以明确包含这些表之间的连接条件，即使在通常为自动的映射中也是如此。例如。如果类Engineer子类Employee，则使用针对Employee本地表的条件对Engineer本地表进行UPDATE看起来像：

  session.query(Engineer).\
      filter(Engineer.id == Employee.id).\
      filter(Employee.name == 'dilbert').\
      update({"engineer_type": "programmer"})

• MapperEvents.before_update()和MapperEvents.after_update()事件不会从此方法调用。相反，提供了SessionEvents.after_bulk_update()方法来对实体行的批量更新进行操作。

也可以看看

Query.delete()

Inserts, Updates and Deletes - 核心SQL教程

值 T0> （ T1> 列 T2> ） T3> ¶ T4>

返回与给定列表达式相对应的标量结果。

值 T0> （ T1> *列 T2> ） T3> ¶ T4>

返回一个迭代器，产生与列给定列表相对应的结果元组

whereclause T0> ¶ T1>

readonly属性，它返回此查询的当前WHERE标准。

这个返回值是一个SQL表达式结构，如果没有建立标准，则返回None。

with_entities T0> （ T1> *实体 T2> ） T3> ¶ T4>

返回一个新的Query替换给定实体的SELECT列表。

例如。：

# Users, filtered on some arbitrary criterion
# and then ordered by related email address
q = session.query(User).\
            join(User.address).\
            filter(User.name.like('%ed%')).\
            order_by(Address.email)

# given *only* User.id==5, Address.email, and 'q', what
# would the *next* User in the result be ?
subq = q.with_entities(Address.email).\
            order_by(None).\
            filter(User.id==5).\
            subquery()
q = q.join((subq, subq.c.email < Address.email)).\
            limit(1)

版本0.6.5中的新功能

with_for_update(read=False, nowait=False, of=None, skip_locked=False, key_share=False)¶

用FOR UPDATE子句的指定选项返回新的Query。

此方法的行为与SelectBase.with_for_update()的行为相同。当不带参数调用时，结果的SELECT语句将附加一个FOR UPDATE子句。When additional arguments are specified, backend-specific options such as FOR UPDATE NOWAIT or LOCK IN SHARE MODE can take effect.

例如。：

q = sess.query(User).with_for_update(nowait=True, of=User)

在Postgresql后端的上述查询将呈现如下所示：

SELECT users.id AS users_id FROM users FOR UPDATE OF users NOWAIT

版本0.9.0中的新功能： Query.with_for_update()取代Query.with_lockmode()方法。

也可以看看

GenerativeSelect.with_for_update() - Core level method with full argument and behavioral description.

with_hint(selectable, text, dialect_name='*')¶

为给定实体添加一个索引或其他执行上下文提示，或者可选择Query。

功能直接传递给with_hint()，其中selectable可以是Table，Alias或ORM实体/映射类/等等。

也可以看看

Query.with_statement_hint()

with_labels T0> （ T1> ） T2> ¶ T3>

将列标签应用于Query.statement的返回值。

指示此查询的语句访问器应该返回一个SELECT语句，该语句将标签以_ 形式应用于所有列；这通常用于消除多个具有相同名称的表中的列的歧义。

当Query实际发出SQL来加载行时，它总是使用列标签。

注意

只有Query.with_labels()方法将Query.statement和不的输出应用于任何结果行调用Query本身的系统，例如Query.first()，Query.all()等To execute a query using Query.with_labels(), invoke the Query.statement using Session.execute():

result = session.execute(query.with_labels().statement)

with_lockmode T0> （ T1> 模式 T2> ） T3> ¶ T4>

使用指定的“锁定模式”返回一个新的Query对象，该模式实质上是指FOR UPDATE子句。

从版本0.9.0开始弃用：被Query.with_for_update()取代。

参数：	模式 ¶ - 代表所需锁定模式的字符串。有效值是： None - 转换为无锁模式 'update' - translates to FOR UPDATE (standard SQL, supported by most dialects) 'update_nowait' - translates to FOR UPDATE NOWAIT (supported by Oracle, PostgreSQL 8.1 upwards) 'read' - translates to LOCK IN SHARE MODE (for MySQL), and FOR SHARE (for PostgreSQL)

也可以看看

Query.with_for_update() - 用于指定FOR UPDATE子句的改进的API。

with_parent （ 实例，属性=无 ） t5 >

添加过滤标准，将给定实例与子对象或集合相关联，使用其属性状态以及建立的relationship()配置。

该方法使用with_parent()函数生成子句，其结果传递给Query.filter()。

参数与with_parent()相同，只是给定的属性可以是None，在这种情况下，将对该Query对象的目标映射器执行搜索。

with_polymorphic （ cls_or_mappers，selectable =无，polymorphic_on =无 ） T5> ¶ T6>

加载用于继承类的列。

Query.with_polymorphic() applies transformations to the “main” mapped class represented by this Query. 这里的“main”映射类意味着Query对象的第一个参数是一个完整的类，即session.query(SomeClass)。这些转换允许在FROM子句中出现额外的表，这样查询中就可以使用联合继承子类的列，这既是为了加载时效率，也是为了在查询时使用这些列。

有关如何使用此方法的详细信息，请参阅文档部分Basic Control of Which Tables are Queried。

Changed in version 0.8: A new and more flexible function orm.with_polymorphic() supersedes Query.with_polymorphic(), as it can apply the equivalent functionality to any set of columns or classes in the Query, not just the “zero mapper”. 请参阅该函数以获取参数的说明。

with_session T0> （ T1> 会话 T2> ） T3> ¶ T4>

返回将使用给定Session的Query。

with_statement_hint(text, dialect_name='*')¶

向此Select添加语句提示。

该方法类似于Select.with_hint()，不同之处在于它不需要单独的表格，而是作为整体应用于该语句。

该功能调用Select.with_statement_hint()。

版本1.0.0中的新功能

也可以看看

Query.with_hint()

with_transformation T0> （ T1> FN T2> ） T3> ¶ T4>

返回由给定函数转换的新Query对象。

例如。：

def filter_something(criterion):
    def transform(q):
        return q.filter(criterion)
    return transform

q = q.with_transformation(filter_something(x==5))

这允许为Query对象创建专门的配方。请参阅Building Transformers中的示例。

New in version 0.7.4.

yield_per T0> （ T1> 计数 T2> ） T3> ¶ T4>

一次只产生count行。

这个方法的目的是当获取非常大的结果集（> 10K行）时，在子集合中批量结果并部分生成结果集，以便Python解释器不需要声明非常大的内存区域，耗时并导致过度使用内存。当使用合适的yield-per设置（例如，大约1000）时，即使使用缓冲行（最多）的DBAPI，从成千上万行提取数据的性能通常也会提高一倍。

Query.yield_per()方法与大多数热切加载方案（包括子查询加载和集合加载）不兼容。出于这个原因，禁用预先加载可能是有帮助的，无论是无条件地使用Query.enable_eagerloads()：

q = sess.query(Object).yield_per(100).enable_eagerloads(False)

或者更有选择地使用lazyload()；例如用星号来指定默认的加载程序方案：

q = sess.query(Object).yield_per(100).\
    options(lazyload('*'), joinedload(Object.some_related))

警告

谨慎使用此方法；如果同一个实例存在于多个批次的行中，则最终用户对属性的更改将被覆盖。

特别是，通常不可能在急切加载的集合（即任何lazy ='joined'或'subquery'）中使用此设置，因为在后续结果批处理中遇到新集合时，这些集合将被清除。在加载“子查询”的情况下，所有行的完整结果被取出，这通常会损害yield_per()的用途。

Also note that while yield_per() will set the stream_results execution option to True, currently this is only understood by psycopg2 dialect which will stream results using server side cursors instead of pre-buffer all rows for this query. 其他DBAPI 在使其可用之前预缓冲所有行。原始数据库行的内存使用量远小于ORM映射对象的内存使用量，但在进行基准测试时应该将其考虑在内。

也可以看看

Query.enable_eagerloads()

特定于ORM的查询构造¶

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()函数用于创建映射类到新选择对象的临时映射。默认情况下，使用FromClause.alias()方法从可正常映射的可选项（通常为Table）生成可选项。但是，也可以使用aliased()将该类链接到新的select()语句。此外，with_polymorphic()函数是aliased()的一个变体，旨在指定所谓的“多态可选”，它对应于多个联合的联合 - 一次性继承子类。

为方便起见，aliased()函数还接受普通的FromClause结构，如Table或select()构造。在这些情况下，将在对象上调用FromClause.alias()方法，并返回新的Alias对象。在这种情况下，返回的Alias不是ORM映射的。

参数：

元素 ¶ - 元素为别名。通常是一个映射类，但为了方便起见，也可以是一个FromClause元素。 别名 ¶ - 可选可选单元以将元素映射到。This should normally be a Alias object corresponding to the Table to which the class is mapped, or to a select() construct that is compatible with the mapping. 默认情况下，会生成映射表的简单匿名别名。 name¶ – optional string name to use for the alias, if not specified by the alias parameter. 除此之外，该名称构成了可通过Query对象返回的元组访问的属性名称。 flat ¶ - 布尔值将传递给FromClause.alias()调用，以便Join对象的别名不包含封闭的SELECT。这可以在许多情况下导致更高效的查询。针对嵌套JOIN的JOIN将被重写为针对不支持此语法的后端上的别名SELECT子查询的JOIN。 版本0.9.0中的新功能 也可以看看 Join.alias() adapt_on_names ¶ - 如果为True，则在将ORM实体的映射列映射到给定可选列表的映射列时将使用更自由的“匹配” - 如果给定可选列不具有与一个列相对应的列，则将执行基于名称的匹配在实体上。这个用例就是将一个实体与某些派生可选项（例如使用集合函数的实体）相关联： class UnitPrice(Base): __tablename__ = 'unit_price' ... unit_id = Column(Integer) price = Column(Numeric) aggregated_unit_price = Session.query( func.sum(UnitPrice.price).label('price') ).group_by(UnitPrice.unit_id).subquery() aggregated_unit_price = aliased(UnitPrice, alias=aggregated_unit_price, adapt_on_names=True) 以上，引用.price的aggregated_unit_price上的函数将返回fund.sum(UnitPrice.price).label('price')列，因为它与名称“价格”相匹配。通常，“价格”函数与实际的UnitPrice.price列没有任何“列对应”，因为它不是原始代理。 New in version 0.7.3.

class sqlalchemy.orm.util。 AliasedClass （ cls，别名= None，name = None，flat = False，adapt_on_names = False，with_polymorphic_mappers =() t9 >，with_polymorphic_discriminator = None，base_alias = None，use_mapper_path = False ）

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

该对象是sqlalchemy.sql.expression.alias()构造的ORM等价物，它使用__getattr__方案模仿映射类并维护对真实Alias对象的引用。

用法是通过orm.aliased()函数，或者通过orm.with_polymorphic()函数。

用法示例：

# 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的一个实例。该对象实现了一个属性方案，该方案产生与原始映射类相同的属性和方法接口，允许AliasedClass与原始类中的任何属性技术兼容，包括混合属性（参见Hybrid Attributes）。

可以使用inspect()检查AliasedClass的底层Mapper，别名可选和其他信息：

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

得到的检查对象是AliasedInsp的实例。

有关构造参数的描述，请参阅aliased()和with_polymorphic()。

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

基础：sqlalchemy.orm.base.InspectionAttr

为AliasedClass对象提供检查界面。

给AliasedClass使用inspect()函数返回AliasedInsp对象：

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 - collection of Mapper objects indicating all those mappers expressed in the select construct for the AliasedClass.
• polymorphic_on - 将用作多态加载的“鉴别符”的备用列或SQL表达式。

也可以看看

Runtime Inspection API

class sqlalchemy.orm.query。 Bundle （ name，* exprs，** kw ） ¶

基础：sqlalchemy.orm.base.InspectionAttr

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

Bundle本质上允许嵌套基于列的Query对象返回的基于元组的结果。它也可以通过简单的子类来扩展，其中主要的覆盖能力是应该如何返回表达式集合，允许后处理以及自定义返回类型，而不涉及ORM身份映射类。

版本0.9.0中的新功能

也可以看看

Column Bundles

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

参数：	名称 ¶ - 包的名称。 * exprs ¶ - 包含该包的列或SQL表达式。 single_entity=False¶ – if True, rows for this Bundle can be returned as a “single entity” outside of any enclosing tuple in the same manner as a mapped entity.

c =无 ¶

Bundle.columns的别名。

列 =无 ¶

由Bundle引用的SQL表达式的名称空间。

例如。：

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

create_row_processor （ query，procs，标签 ） ¶ T6>

为这个Bundle产生“行处理”功能。

可能被子类覆盖。

也可以看看

Column Bundles - 包含子类的示例。

标签 T0> （ T1> 名称 T2> ） T3> ¶ T4>

提供这个Bundle的副本，传递一个新标签。

single_entity = False ¶

如果为True，则对单个Bundle的查询将作为单个实体返回，而不是键控元组内的元素。

class sqlalchemy.util。 KeyedTuple ¶

基础：sqlalchemy.util._collections.AbstractKeyedTuple

tuple子类添加标签名称。

例如。：

>>> k = KeyedTuple([1, 2, 3], labels=["one", "two", "three"])
>>> k.one
1
>>> k.two
2

由Query返回的包含多个ORM实体和/或列表达式的结果行使用此类来返回行。

KeyedTuple表现出与Python标准库中提供的collections.namedtuple()结构类似的行为，但结构却非常不同。与collections.namedtuple()不同，KeyedTuple不依赖于创建自定义子类型来表示一系列新的键，而是每个KeyedTuplecollections.namedtuple()的子类型方法引入了显着的复杂性和性能开销，这对Query对象的用例来说不是必需的。

Changed in version 0.8: Compatibility methods with collections.namedtuple() have been added including KeyedTuple._fields and KeyedTuple._asdict().

也可以看看

Querying

_asdict T0> （ T1> ） T2> ¶ T3>

将KeyedTuple的内容作为字典返回。

该方法提供了与collections.namedtuple()的兼容性，不同之处在于返回的字典是not的顺序。

0.8版本中的新功能

_fields T0> ¶ T1>

返回此KeyedTuple的字符串键名称的元组。

该方法提供了与collections.namedtuple()的兼容性。

0.8版本中的新功能

也可以看看

KeyedTuple.keys()

键 T0> （ T1> ） T2> ¶ T3>

inherited from the keys() method of AbstractKeyedTuple

返回此KeyedTuple的字符串键名称列表。

也可以看看

KeyedTuple._fields

class sqlalchemy.orm.strategy_options.Load(entity)¶

基础：sqlalchemy.sql.expression.Generative，sqlalchemy.orm.interfaces.MapperOption

表示加载器选项，它修改Query的状态以影响各种映射属性的加载方式。

0.9.0版新增： Load()系统是现有加载程序选项系统的新基础，包括orm.joinedload()，orm.defer()等等。特别是，它引入了一种新的方法链接系统，它取代了对点分隔路径的需求以及诸如orm.joinedload_all()之类的“_all()”选项。

一个Load对象可以直接或间接使用。直接使用一个，给定父类的实例。在处理具有多个实体的Query时，或者在生成可一般应用于任何查询类型的加载程序选项时，这种使用方式很有用：

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

上面的myopt现在可以用于Query.options()：

session.query(MyClass).options(myopt)

The Load construct is invoked indirectly whenever one makes use of the various loader options that are present in sqlalchemy.orm, including options such as orm.joinedload(), orm.defer(), orm.subqueryload(), and all the rest. 这些结构产生一个“匿名”形式的Load对象，用于跟踪属性和选项，但直到它与父对象Query相关联时才会链接到父类。

# produce "unbound" Load object
myopt = joinedload("widgets")

# when applied using options(), the option is "bound" to the
# class observed in the given query, e.g. MyClass
session.query(MyClass).options(myopt)

无论使用直接还是间接样式，返回的Load对象现在都表示沿着Query的实体的特定“路径”。这个路径可以使用标准的方法链式方法来遍历。假设一个类层次结构如User，User.addresses - >＆lt； / t4> Address ，User.orders - ＆gt； 订单和Order.items - ＆gt； Item，我们可以在“路径”中的每个元素上指定各种加载器选项：

session.query(User).options(
            joinedload("addresses"),
            subqueryload("orders").joinedload("items")
        )

在上面，addresses集合将被连接加载，orders集合将被子查询加载，并且在该子查询中加载items集合将被连接加载。

baked_lazyload tt> （ loadopt，attr ） ¶

应用orm.baked_lazyload()选项产生一个新的Load对象。

有关用法示例，请参阅orm.baked_lazyload()。

contains_eager （ loadopt，attr，别名=无 T5> ¶ T6>

使用orm.contains_eager()选项生成新的Load对象。

有关用法示例，请参阅orm.contains_eager()。

defaultload(loadopt, attr)¶

应用orm.defaultload()选项生成新的Load对象。

有关用法示例，请参阅orm.defaultload()。

defer(loadopt, key)¶

应用orm.defer()选项生成新的Load对象。

有关用法示例，请参阅orm.defer()。

immediateload(loadopt, attr)¶

应用orm.immediateload()选项生成新的Load对象。

有关用法示例，请参阅orm.immediateload()。

joinedload(loadopt, attr, innerjoin=None)¶

应用orm.joinedload()选项产生一个新的Load对象。

有关用法示例，请参阅orm.joinedload()。

lazyload(loadopt, attr)¶

应用orm.lazyload()选项产生一个新的Load对象。

有关使用示例，请参阅orm.lazyload()。

load_only(loadopt, *attrs)¶

应用orm.load_only()选项生成新的Load对象。

有关用法示例，请参阅orm.load_only()。

noload （ loadopt，attr ）

应用orm.noload()选项生成新的Load对象。

有关使用示例，请参阅orm.noload()。

raiseload(loadopt, attr)¶

应用orm.raiseload()选项生成新的Load对象。

有关使用示例，请参阅orm.raiseload()。

subqueryload(loadopt, attr)¶

使用orm.subqueryload()选项生成新的Load对象。

有关用法示例，请参阅orm.subqueryload()。

undefer （ loadopt，键 ） ¶

应用orm.undefer()选项产生一个新的Load对象。

有关用法示例，请参阅orm.undefer()。

undefer_group(loadopt, name)¶

应用orm.undefer_group()选项产生一个新的Load对象。

有关用法示例，请参阅orm.undefer_group()。

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

在左边和右边的子句之间产生一个内部连接。

orm.join()是sql.expression.join()提供的核心连接接口的扩展，其中左和右选择符不仅可以是核心可选对象如Table，还映射了类或AliasedClass实例。“on”子句可以是SQL表达式，也可以是引用配置的relationship()的属性或字符串名称。

orm.join() is not commonly needed in modern usage, as its functionality is encapsulated within that of the Query.join() method, which features a significant amount of automation beyond orm.join() by itself. 使用Query显式使用orm.join()涉及使用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.1中更改： - join_to_left参数不再使用，并且已弃用。

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

在左边和右边的子句之间产生一个左外连接。

这是orm.join()函数的“外部连接”版本，除了生成一个OUTER JOIN外，其特征与其他行为相同。有关其他使用细节，请参阅该函数的文档。

sqlalchemy.orm.with_parent(instance, prop)¶

使用已建立的relationship()配置创建过滤标准，将该查询的主要实体与给定的相关实例相关联。

呈现的SQL与延迟加载器从该属性上的给定父级触发时所呈现的相同，这意味着从Python中的父对象获取适当的状态，而无需在呈现中呈现连接至父表的连接声明。

在版本0.6.4中进行了更改：此方法接受所有持久状态下的父实例，包括瞬态，持久和分离。只有必要的主键/外键属性需要填充。以前的版本不适用于瞬态实例。

参数：	instance¶ – An instance which has some relationship(). property¶ – String property name, or class-bound attribute, which indicates what relationship from the instance should be used to reconcile the parent/child relationship.