版本:1.1.0b2 |发布日期:2016年7月1日

SQLAlchemy 1.1文档

查询API

查询对象

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 objects are normally initially generated using the query() method of Session. 有关Query用法的完整演练,请参阅Object Relational Tutorial

add_column T0> ( T1> 列 T2> ) T3> ¶ T4>

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

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

add_columns T0> ( T1> *柱 T2> ) T3> ¶ T4>

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

add_entity entityalias = 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子句与包含的Queryselect()关联起来。

这里的方法接受映射的类,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

版本0.7中改变:以上方案是从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别名是Core可选项,这意味着通过.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')

警告

The Query.delete() method is a “bulk” operation, which bypasses ORM unit-of-work automation in favor of greater performance. 请阅读下面的所有警告和警告。

参数: synchronize_session -

选择从会话中删除匹配对象的策略。有效值是:

False - don’t synchronize the session. 一旦会话过期,这个选项是最有效和可靠的,通常在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

  • The 'fetch' strategy results in an additional SELECT statement emitted and will significantly reduce performance.

  • 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()方法来对大量的实体行进行删除。

也可以看看

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>

针对一个或多个查询生成此查询的所有内容。

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子句中。要根据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 on keyword expressions.

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() - filter on SQL expressions.

第一 T0> ( T1> ) T2> ¶ T3>

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

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

调用Query.first()会导致执行底层查询。

from_self T0> ( T1> *实体 T2> ) T3> ¶ T4>

返回一个从这个Query的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

There are lots of cases where Query.from_self() may be useful. 一个简单的方法就是在上面的地方,我们可能希望将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()从子查询中的连接实体加载,我们需要添加这些列。下面举例说明了AddressUser的连接,然后是子查询,然后我们想要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. If not, ObjectDeletedError is raised.

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()的工作方式相同。查看使用示例的方法。

连接 tt> * props** kwargs T5>

根据这个Query对象的标准创建一个SQL JOIN并生成应用,返回最新的结果Query

Simple Relationship Joins

考虑两个类UserAddress之间的映射,其中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引用为join()作为on子句,也就是说, ON“部分的JOIN应该被构建。对于像上面那样的单一实体查询(即,我们只从User开始,而没有其他选择),关系也可以用字符串名来指定:

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

join() can also accommodate multiple “on clause” arguments to produce a chain of joins, such as below where a join across four related entities is constructed:

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

以上是三个分别对join()调用的简写,每个调用都使用显式属性来指示源实体:

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

加入目标实体或可选

第二种形式的join()允许任何映射的实体或核心可选结构作为目标。In this usage, join() will attempt to create a JOIN along the natural foreign key relationship between two entities:

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()的两个参数形式需要使用元组:.join((地址, User.id == Address.user_id))这个调用形式在0.7中是可以接受的,除此之外,除非多个连接条件被传递给一个join()调用,否则这个调用并不是必须的,因为它现在等同于多个调用(这并非总是如此)。

Advanced Join Targeting and Adaption

在使用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. 下面我们构建一个从UserAddress的子查询的JOIN,允许User.addresses 表示的关系适应 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从第一个选择开始使用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). 一个特殊的双参数调用格式target, onclause也被接受。
  • aliased=False – If True, indicate that the JOIN target should be anonymously aliased. 后续对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.

也可以看看

Querying with Joins in the ORM tutorial.

有关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 iteratorload = True >

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

Given an iterator returned by a Query of the same structure as this one, return an identical iterator of results, with all mapped instances merged into the session using Session.merge(). 这是一个优化的方法,它将合并所有映射的实例,为每个值明确调用Session.merge(),从而保留结果行和未映射列的结构,而且方法开销较小。

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

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

For an example of how merge_result() is used, see the source code for the example Dogpile Caching, where merge_result() is used to efficiently restore state from a cache back into a target Session.

偏移 T0> ( T1> 偏移 T2> ) T3> ¶ T4>

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

一个 T0> ( T1> ) T2> ¶ T3>

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

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

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

one_or_none T0> ( T1> ) T2> ¶ T3>

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

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

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

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

选项 T0> ( T1> * ARGS T2> ) T3> ¶ T4>

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

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

ORDER_BY T0> ( T1> *标准 T2> ) T3> ¶ T4>

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

所有现有的ORDER BY设置都可以通过传递None来禁止 - 这将会禁止在映射器​​上配置的ORDER BY。

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

outerjoin(*props, **kwargs)

根据这个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.

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中的内容,则此方法也会应用给定的selectable来替换所选实体通常从中选择的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() maintains an older behavior of 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 – collection of one or more entities to apply to the FROM clause. 实体可以是映射类,AliasedClass对象,Mapper对象以及像子查询这样的核心FromClause元素。

在版本0.9中更改:此方法不再将给定的FROM对象应用于匹配实体从中选择的可选项; 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)
语句 T0> ¶ T1>

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

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

子查询 name = Nonewith_labels = Falsereduce_columns = False ) T5> ¶ T6>

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

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

参数:
  • name – string name to be assigned as the alias; this is passed through to 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_labelsreduce_columns关键字参数。

suffix_with T0> ( T1> *后缀 T2> ) T3> ¶ T4>

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

参数: *后缀 - 可选的后缀,通常是字符串,不使用任何逗号。

版本1.0.0中的新功能

联合 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()的工作方式相同。查看使用示例的方法。

update(values, synchronize_session='evaluate', update_args=None)

执行批量更新查询。

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

例如。:

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

警告

The Query.update() method is a “bulk” operation, which bypasses ORM unit-of-work automation in favor of greater performance. 请阅读下面的所有警告和警告。

参数:
  • -

    包含属性名称的字典,或映射的属性或SQL表达式作为键,字面值或sql表达式作为值。如果需要parameter-ordered mode,则这些值可以作为2元组列表传递;这要求将preserve_parameter_order标志传递给Query.update.update_args字典。

    版本1.0.0中已更改: - 值字典中的字符串名称现在已针对映射的实体进行解析;以前,这些字符串作为文字列名传递,没有映射器级别的转换。

  • synchronize_session -

    选择策略来更新会话中对象的属性。有效值是:

    False - don’t synchronize the session. 一旦会话过期,这个选项是最有效和可靠的,通常在commit()之后发生,或者明确地使用expire_all()。在到期之前,更新的对象可能仍然保留在会话中,其属性上的陈旧值可能会导致令人困惑的结果。

    'fetch' - 在更新之前执行选择查询以查找与更新查询匹配的对象。已更新的属性在匹配对象上过期。

    'evaluate' - 直接在会话中的对象中评估Python中的查询条件。如果评估标准没有得到执行,则会引发例外。

    表达式求值器当前不考虑数据库和Python之间不同的字符串归类。

  • update_args -

    可选字典(如果存在)将作为对象的**kw传递到基础update()结构中。可用于传递特定于方言的参数,如mysql_limit以及其他特殊参数,例如preserve_parameter_order

    版本1.0.0中的新功能

返回:

数据库的“行数”功能所返回的行数。

警告

Additional Caveats for bulk query updates

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

    After the UPDATE, dependent objects in the Session which were impacted by an ON UPDATE CASCADE may not contain the current state; this issue is resolved once the Session is expired, which normally occurs upon Session.commit() or can be forced by using Session.expire_all().

  • The 'fetch' strategy results in an additional SELECT statement emitted and will significantly reduce performance.

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

Functionality is passed straight through to with_hint(), with the addition that selectable can be a Table, Alias, or ORM entity / mapped class /etc.

with_labels T0> ( T1> ) T2> ¶ T3>

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

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

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

注意

The Query.with_labels() method only applies the output of Query.statement, and not to any of the result-row invoking systems of Query itself, e.g. Query.first(), Query.all(), etc. 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 - translates to no lockmode
  • '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() - improved API for specifying the FOR UPDATE clause.

with_parent(instance, property=None)

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

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

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

with_polymorphic(cls_or_mappers, selectable=None, polymorphic_on=None)

加载用于继承类的列。

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>

返回将使用给定SessionQuery

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的例子。

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映射对象少得多,但在进行基准测试时仍应考虑到这一点。

特定于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结构,如Tableselect()构造。在这些情况下,将在对象上调用FromClause.alias()方法,并返回新的Alias对象。在这种情况下,返回的Alias不是ORM映射的。

参数:
  • element – element to be aliased. Is normally a mapped class, but for convenience can also be a FromClause element.
  • 别名 - 可选的单元映射元素。这通常应该是一个与类映射到的Table对应的Alias对象,或者与select()映射。默认情况下,会生成映射表的简单匿名别名。
  • name – optional string name to use for the alias, if not specified by the alias parameter. 其中的名称构成了可以通过Query对象返回的元组访问的属性名称。
  • 扁平 -

    Boolean将传递给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)

    以上,参考.priceaggregated_unit_price上的函数将返回fund.sum(UnitPrice.price).label('price')列,因为它是匹配的名称“价格”。通常,“价格”函数与实际的UnitPrice.price列没有任何“列对应”,因为它不是原始代理。

    New in version 0.7.3.

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

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

ORM相当于一个sqlalchemy.sql.expression.alias()结构,该对象使用__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对象提供检查接口。

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

from sqlalchemy import inspect
from sqlalchemy.orm import aliased

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

AliasedInsp上的属性包括:

  • entity - 表示AliasedClass
  • mapper - 映射基础类的Mapper
  • selectable - the Alias construct which ultimately represents an aliased Table or Select construct.
  • name - the name of the alias. 当从Query返回结果元组时,也用作属性名称。
  • with_polymorphic_mappers - Mapper对象的集合,指示所有在select结构中为AliasedClass表示的映射器。
  • polymorphic_on - an alternate column or SQL expression which will be used as the “discriminator” for a polymorphic load.

也可以看看

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)
参数:
  • name – name of the bundle.
  • * 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, labels)

为这个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()的兼容性,不同的是返回的字典是而不是

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.Generativesqlalchemy.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实体的特定“路径”。这个路径可以使用标准的方法链接方法来遍历。Supposing a class hierarchy such as User, User.addresses -> Address, User.orders -> Order and Order.items -> Item, we can specify a variety of loader options along each element in the “path”:

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

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

baked_lazyload(loadopt, attr)

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

有关使用示例,请参阅orm.baked_lazyload()

contains_eager loadoptattr别名=无 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 tt> loadoptattr

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

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

raiseload(loadopt, attr)

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

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

subqueryload(loadopt, attr)

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

有关使用示例,请参阅orm.subqueryload()

undefer tt> loadoptkey

使用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() is an extension to the core join interface provided by sql.expression.join(), where the left and right selectables may be not only core selectable objects such as Table, but also mapped classes or AliasedClass instances. “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中进行了更改:该方法接受所有持久性状态下的父实例,包括transient,persistent和detached。只有必需的主键/外键属性需要填充。以前的版本不适用于瞬态实例。

参数:
  • 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.