查询API¶

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

查询对象

Query 是根据给定的 Session ,使用 query() 方法:

q = session.query(SomeMappedClass)

下面是 Query 对象。

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

ORM级SQL构造对象。

Query 是ORM生成的所有SELECT语句的源,这两个语句都是由最终用户查询操作以及相关集合加载等高级内部操作所制定的。它具有一个生成接口,在该接口中,连续调用返回一个新的 Query 对象,前者的副本,以及与之关联的其他条件和选项。

Query 对象通常最初是使用 query() 方法 Session 在不太常见的情况下,通过实例化 Query 直接并与 Session 使用 Query.with_session() 方法。

进行全面的演练 Query 用法,请参见 对象关系教程 .

__init__(entities, session=None)

构建一个 Query 直接。

例如。::

q = Query([User, Address], session=some_session)

以上相当于:

q = some_session.query(User, Address)
参数
add_column(column)

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

待定折旧: add_column() 将被取代 add_columns() .

add_columns(*column)

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

add_entity(entity, alias=None)

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

all()

返回由此表示的结果 Query 作为一个列表。

这将导致执行基础查询。

as_scalar()

返回由该语句表示的完整select语句 Query ,已转换为标量子查询。

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

autoflush(setting)

返回具有特定“autoflush”设置的查询。

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

column_descriptions

返回有关此将返回的列的元数据 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
    }
]
correlate(*args)

返回A Query 将给定的FROM子句与封闭子句相关联的构造 Queryselect() .

这里的方法接受映射类, aliased() 构造,以及 mapper() 构造作为参数,除了适当的表达式构造之外,还解析为表达式构造。

相关参数最终传递给 Select.correlate() 强制表达式构造之后。

相关参数在以下情况下生效: Query.from_self() 使用,或当 Query.subquery() 嵌入到另一个 select() 构造。

count()

返回此查询将返回的行数。

这将为此查询生成SQL,如下所示:

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

对于要计数的特定列的细粒度控制,若要跳过子查询的使用或对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)

返回由该语句表示的完整select语句 Query 表示为公用表表达式(CTE)。

参数和用法与 SelectBase.cte() 方法;有关详细信息,请参阅该方法。

这里是 PostgreSQL WITH RECURSIVE example . 注意,在这个例子中, included_parts cte and the incl_alias alias of it are Core selectables, which means the columns are accessed via the .c. 属性。这个 parts_alias 对象是 orm.aliased() 实例 Part 实体,因此列映射属性直接可用:

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

delete(synchronize_session='evaluate')

执行批量删除查询。

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

例如。::

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之间不同的字符串排序规则。

返回

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

警告

批量查询删除的附加警告

  • 这个方法可以 不适用于联接继承映射 ,因为 SQL不支持多个表删除 以及 继承映射器的联接条件不会自动呈现 . 在删除任何多个表时必须小心,以便首先通过一些其他方法来适应删除相关表的方式,并明确包括这些表之间的联接条件,即使在通常是自动的映射中也是如此。例如一个班 Engineer 子类 Employee ,删除 Employee 表格看起来像:

    session.query(Engineer).\
        filter(Engineer.id == Employee.id).\
        filter(Employee.name == 'dilbert').\
        delete()

    但是,上面的SQL不会从工程表中删除,除非在数据库中建立了一个on-delete级联规则来处理它。

    短篇小说, 不要将此方法用于联接继承映射,除非您已采取其他步骤使其可行。 .

  • 标准的多态性 not 包括用于单表或联接表更新-必须添加 手动 即使是单表继承。

  • 方法确实 not 在python中提供级联关系-假设在删除时为需要它的任何外键引用配置了cascade/set NULL/etc,否则,如果强制使用外键引用,数据库可能会发出完整性冲突。

    删除后,在 Session 受“删除时”影响的可能不包含当前状态,或者可能已被删除。一旦 Session 过期,通常发生在 Session.commit() 或者可以通过使用 Session.expire_all() . 访问已删除行的过期对象将调用select来定位该行;如果找不到该行,则 ObjectDeletedError 提高了。

  • 这个 'fetch' 策略会产生额外的select语句,并将显著降低性能。

  • 这个 'evaluate' 策略对中的所有匹配对象执行扫描 Session ;如果 Session 过期,如通过程序 Session.commit() 调用, 这将导致为每个匹配对象发出选择查询 .

  • 这个 MapperEvents.before_delete()MapperEvents.after_delete() 事件 未调用 从这个方法。相反, SessionEvents.after_bulk_delete() 方法用于对实体行进行批量删除。

参见

Query.update()

插入、更新和删除 -核心SQL教程

distinct(*expr)

应用一 DISTINCT 到查询并返回新生成的 Query .

注解

这个 distinct() 调用包含的逻辑将自动从查询的order by添加列到select语句的columns子句,以满足数据库后端在使用distinct时将order by列作为select列表的一部分的常见需求。这些栏目 不是 添加到实际由 Query 但是,这不会影响结果。当使用 Query.statement 但是,访问器。

参数

*expr -- 可选列表达式。当存在时,PostgreSQL方言将呈现 DISTINCT ON (<expressions>) 构造。

enable_assertions(value)

控制是否生成断言。

当设置为false时,返回的查询不会在某些操作之前断言其状态,包括调用filter()时未应用限制/偏移量,调用get()时不存在条件,调用filter()/order_by()/group_by()等时不存在“from_statement()”。自定义查询子类使用这种更为宽松的模式来指定标准或常规使用模式之外的其他修饰符。

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

enable_eagerloads(value)

控制是否呈现预先连接和子查询。

当设置为false时,返回的查询将不会呈现任何 joinedload()subqueryload() 选项或映射器级别 lazy='joined'/lazy='subquery' 配置。

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

except_(*q)

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

工作方式与 union() . 有关用法示例,请参见该方法。

except_all(*q)

针对一个或多个查询生成一个except all查询。

工作方式与 union() . 有关用法示例,请参见该方法。

execution_options(**kwargs)

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

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

请注意 stream_results 如果 yield_per() 方法。

exists()

将查询转换为窗体的exists子查询的便利方法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)不允许在select的columns子句中存在exists表达式。要基于“存在”选择一个简单的布尔值,请使用 literal() ::

from sqlalchemy import literal

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

将给定的筛选条件应用于此的副本 Query ,使用SQL表达式。

例如。::

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

多个条件可以指定为逗号分隔;其效果是它们将使用 and_() 功能:

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

条件是任何适用于select的where子句的SQL表达式对象。字符串表达式通过 text() 构造。

参见

Query.filter_by() -筛选关键字表达式。

filter_by(**kwargs)

将给定的筛选条件应用于此的副本 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表达式。

first()

返回此操作的第一个结果 Query 如果结果不包含任何行,则为“无”。

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

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

from_self(*entities)

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

Query.from_self() 实际上,将select语句转换为select本身。给出如下查询:

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() 可能有用。一个简单的方法是在上面的位置,我们可能希望对查询的用户对象集应用行限制,然后对该行限制集应用其他联接:

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 别名为内部子查询:

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() 还包括修改正在查询的列的功能。在我们的示例中,我们希望 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

Looking out for Inner / Outer Columns

请记住,当引用源自子查询内部的列时,我们需要确保它们存在于子查询本身的columns子句中;这是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))

我们使用 Query.add_entity() 在上面 之前 我们调用 Query.from_self() 所以 User 列存在于内部子查询中,因此它们可用于 contains_eager() 我们在外部使用的修饰语,产生:

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

如果我们不调用 add_entity(User) ,但仍被问到 contains_eager() 加载 User 如果没有正确的联接条件,则将强制在外部添加表-请注意 anon1, "user" 结尾的短语:

-- 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 -- 将替换所选实体的可选实体列表。

from_statement(statement)

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

此方法绕过所有内部语句编译,执行语句时不做任何修改。

语句通常是 text()select() 构造,并应返回适用于由此表示的实体类的列集 Query .

参见

使用文本SQL -ORM教程中的用法示例

get(ident)

基于给定的主键标识符返回实例,或 None 如果找不到。

例如。::

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

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

some_object = session.query(VersionedFoo).get(
    {"id": 5, "version_id": 10})

get() 特殊之处在于它可以直接访问拥有者的身份地图 Session . 如果给定的主键标识符存在于本地标识映射中,则该对象将直接从此集合返回,并且不会发出SQL,除非该对象已标记为完全过期。如果不存在,则执行选择以定位对象。

get() 还将执行检查对象是否存在于标识映射中并标记为已过期-将发出选择以刷新对象并确保行仍然存在。如果不是, ObjectDeletedError 提高了。

get() 仅用于返回单个映射实例,而不是多个实例或单个列构造,并且严格使用单个主键值。起源 Query 必须以这种方式构造,即针对一个映射的实体,没有附加的筛选条件。通过加载选项 options() 但可以应用,如果对象尚未在本地存在,则将使用。

延迟加载,由配置的多对一属性 relationship() 使用简单的外键到主键条件,也将使用等效于 get() 以便在查询数据库之前从本地标识映射中检索目标值。见 关系加载技术 有关关系加载的详细信息。

参数

ident -- 表示主键的标量、元组或字典。对于复合(例如多列)主键,应传递元组或字典。对于单列主键,标量调用形式通常是最合适的。如果一行的主键是值“5”,则调用看起来像::my_object=query.get(5)tuple表单包含的主键值通常按照它们对应于映射的 Table 对象的主键列,或者如果 Mapper.primary_key 配置参数的使用顺序与该参数的使用顺序相同。例如,如果行的主键由整数“5,10”表示,则调用将类似于::my_object=query.get((5,10)),字典表单应将对应于主键的每个元素的映射属性名称作为键包含。如果映射类具有属性 idversion_id 作为存储对象的主键值的属性,调用将类似于::my_object=query.get(“id”:5,“version_id”:10)。版本添加::1.3 Query.get() 方法现在可以选择接受属性名到值的字典,以指示主键标识符。

返回

对象实例,或 None .

get_execution_options()

获取将在执行期间生效的非SQL选项。

1.3 新版功能.

group_by(*criterion)

将一个或多个分组条件应用于查询并返回新结果 Query

可以通过传递来抑制所有现有的分组依据设置 None -这也将通过在映射器上配置来禁止任何组。

1.1 新版功能: Group By可以通过不传递来取消,方法与Order By相同。

having(criterion)

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

having() 与一起使用 group_by() .

有了条件,就可以对诸如count、sum、avg、max和min之类的聚合函数使用过滤器,例如:

q = session.query(User.id).\
            join(User.addresses).\
            group_by(User.id).\
            having(func.count(Address.id) > 2)
instances(cursor, _Query__context=None)

给定connection.execute()返回的resultProxy游标,将ORM结果作为迭代器返回。

例如。::

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

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

工作方式与 union() . 有关用法示例,请参见该方法。

intersect_all(*q)

生成一个与一个或多个查询相交的所有查询。

工作方式与 union() . 有关用法示例,请参见该方法。

join(*props, **kwargs)

针对此创建SQL联接 Query 对象的标准并生成应用,返回新生成的 Query .

简单关系联接

考虑两个类之间的映射 UserAddress ,有关系 User.addresses 表示的集合 Address 与每个关联的对象 User . 最常见的用法是 join() 是沿着此关系创建联接,使用 User.addresses 属性作为如何发生这种情况的指示器::

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

在上面的什么地方,调用 join() 沿着 User.addresses 将导致SQL等价于:

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

在上面的例子中,我们提到 User.addresses 传到 join() 作为 关于子句 也就是说,它指示应该如何构造连接的“on”部分。对于单个实体查询,如上面的查询(即,我们只从 User 也可以通过其字符串名称来指定关系::

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

join() 还可以容纳多个“on-clause”参数以生成一个连接链,例如下面构造了四个相关实体之间的连接:

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

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

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

联接到目标实体或可选

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

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

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

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

用ON子句联接到目标

第三个调用表单允许显式传递目标实体和ON子句。例如,假设我们想加入 Address 两次,第二次使用别名。我们使用 aliased() 创建 Address ,并使用 target, onclause 窗体,以便可以显式将别名指定为目标以及关系,以指示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)

高级加入目标和适应

在使用“目标”时有很大的灵活性 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() 还具有以下功能: 适应relationship() -驱动ON子句到目标可选。下面我们构造一个连接 User 到子查询 Address ,允许关系表示为 User.addresses适应 自身到被改变的目标:

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() 专门处理连接的“右”端,我们也可以控制“左”端,在需要的情况下,使用 select_from() . 下面我们构造一个查询 Address 但仍然可以利用 User.addresses 通过指示 Query 从中选择第一个 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() 无法使用 aliased=True 标志。此功能在通过算法连接查询时很有用,例如当查询自引用到任意深度时:

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

什么时候? aliased=True 使用时,实际的“alias”构造不显式可用。使用它的方法,例如 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')

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

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

例如 aliased=True ,请参见分发示例 XML持久化 它演示了一个使用算法连接的类似于XPath的查询系统。

参数
  • *props -- 一个或多个联接条件的集合,每个联接条件由表示“on子句”的关系绑定属性或字符串关系名称、单个目标实体或元组组成,其形式为 (target, onclause) . 一个特殊的双参数调用形式 target, onclause 也可接受。

  • aliased=False -- 如果为true,则表示联接目标应匿名别名。后续调用 filter() 类似的方法将使传入的条件适应目标别名,直到 reset_joinpoint() 被称为。

  • isouter=False -- 如果为true,则使用的联接将是左外部联接,就像 Query.outerjoin() 方法被调用。此标志用于与接受的标志保持一致 FromClause.join() 以及其他核心结构。…添加的版本:1.0.0

  • full=False -- 呈现完整的外部连接;暗示 isouter . …添加的版本:1.1

  • from_joinpoint=False -- 使用时 aliased=True ,此处设置为true将导致联接来自最近联接的目标,而不是从查询的原始FROM子句开始。

参见

使用联接查询 在ORM教程中。

映射类继承层次结构 有关如何 join() 用于继承关系。

orm.join() -独立的ORM级联接函数,由内部使用 Query.join() 在以前的SQLAlchemy版本中,它是主要的ORM级联接接口。

label(name)

返回由该语句表示的完整select语句 Query ,转换为带有给定名称标签的标量子查询。

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

lazy_loaded_from = None

InstanceState 用这个吗 Query 对于延迟加载操作。

这可以用于扩展,如水平切分扩展,以及事件处理程序和自定义映射器选项,以确定何时使用查询延迟加载对象上的关系。

1.2.9 新版功能.

limit(limit)

应用一 LIMIT 到查询并返回新生成的 Query .

merge_result(iterator, load=True)

将结果合并到此 Query 对象的会话。

给定由返回的迭代器 Query 对于与此结构相同的结构,返回结果的相同迭代器,所有映射的实例都使用 Session.merge() . 这是一种优化方法,它将合并所有映射的实例,以比调用方法开销更少的方法开销保留结果行和未映射列的结构。 Session.merge() 为每个值显式设置。

结果的结构根据以下列列表确定 Query -如果这些不对应,将发生未选中的错误。

“load”参数与 Session.merge() .

例如如何 merge_result() 使用,请参见示例的源代码 Dogpile缓存 在哪里 merge_result() 用于有效地将状态从缓存还原回目标 Session .

offset(offset)

应用一个 OFFSET 到查询并返回新生成的 Query .

one()

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

加薪 sqlalchemy.orm.exc.NoResultFound 如果查询未选择任何行。加薪 sqlalchemy.orm.exc.MultipleResultsFound 如果返回多个对象标识,或者对于只返回标量值而不是完整标识映射实体的查询返回多行。

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

one_or_none()

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

返回 None 如果查询未选择任何行。加薪 sqlalchemy.orm.exc.MultipleResultsFound 如果返回多个对象标识,或者对于只返回标量值而不是完整标识映射实体的查询返回多行。

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

1.0.9 新版功能: 补充 Query.one_or_none()

only_return_tuples(value)
当设置为true时,查询结果将始终是一个元组,

专门用于单元素查询。默认值为假。

. …添加的版本:1.2.5

options(*args)

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

大多数提供的选项都考虑更改列和关系映射属性的加载方式。参见章节 延迟列加载关系加载技术 作为参考文件。

order_by(*criterion)

对查询应用一个或多个按条件排序并返回新结果 Query

可以通过传递抑制所有现有的按顺序设置 None -这将禁止在 mapper() 对象使用已弃用的 mapper.order_by 参数。

outerjoin(*props, **kwargs)

针对此创建左外部联接 Query 对象的标准并生成应用,返回新生成的 Query .

用法与 join() 方法。

params(*args, **kwargs)

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

参数可以使用 * *kwargs, or optionally a single dictionary as the first positional argument. The reason for both is that * *kwargs is convenient, however some parameter dictionaries contain unicode keys in which case * *Kwargs不能使用。

populate_existing()

返回A Query 它将在加载或从当前实例重新使用时过期并刷新所有实例 Session .

populate_existing() 当ORM正常使用时不会改善行为- Session 对象在回滚或提交之后维护事务和过期所有属性的常见行为自动处理对象状态。此方法不适用于一般用途。

prefix_with(*prefixes)

将前缀应用于查询并返回新生成的 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
reset_joinpoint()

返回一个新的 Query ,其中“连接点”已从查询的实体重置回基。

此方法通常与 aliased=True 特点 join() 方法。请参见中的示例 join() 这是如何使用的。

scalar()

返回第一个结果的第一个元素,如果没有行,则返回无。如果返回多行,则引发multipleResultsFund。

>>> 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(from_obj)

设置此的FROM子句 Query 应用它作为对应映射实体的FROM子句的替换。

这个 Query.select_entity_from() 方法为应用 aliased() 在整个查询中显式构造。而不是指 aliased() 显式构造, Query.select_entity_from() 自动地 适应 可选择的目标实体的所有引用。

为…辩护 aliased() 比如选择 User select语句中的对象:

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

q = session.query(user_alias).\
    filter(user_alias.name == 'ed')

上面,我们应用 user_alias 对象在整个查询中显式地。当它不可行时 user_alias 在很多地方都有明确的引用, Query.select_entity_from() 可以在查询开始时使用以适应现有的 User 单位:

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

上面,生成的SQL将显示 User 实体适用于我们的声明,即使在WHERE条款中:

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

这个 Query.select_entity_from() 方法类似于 Query.select_from() 方法,其中设置查询的FROM子句。区别在于,它还将自适应应用于引用主实体的查询的其他部分。如果上面我们用过 Query.select_from() 相反,生成的SQL应该是:

-- uses plain select_from(), not select_entity_from()
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

将文本SQL提供给 Query.select_entity_from() 方法,我们可以利用 text() 构建。然而, text() 构造需要与实体的列对齐,这是通过使用 TextClause.columns() 方法:

text_stmt = text("select id, name from user").columns(
    User.id, User.name)
q = session.query(User).select_entity_from(text_stmt)

Query.select_entity_from() 本身接受 aliased() 对象,以便 aliased()aliased.adapt_on_names 可在以下范围内使用: Query.select_entity_from() 方法的适应服务。设想一种观点 user_view 同时返回来自的行 user . 如果我们把这个观点 Table ,此视图与 Table 但是,我们可以使用名称匹配从中选择:

user_view = Table('user_view', metadata,
                  autoload_with=engine)
user_view_alias = aliased(
    User, user_view, adapt_on_names=True)
q = session.query(User).\
    select_entity_from(user_view_alias).\
    order_by(User.name)

在 1.1.7 版更改: 这个 Query.select_entity_from() 方法现在接受 aliased() 对象作为 FromClause 对象。

参数

from_obj -- 一 FromClause 将替换此的FROM子句的对象 Query . 它也可能是 aliased() .

select_from(*from_obj)

设置此的FROM子句 Query 明确地。

Query.select_from() 通常与 Query.join() 为了控制从联接的“左侧”选择哪个实体。

这里的实体或可选对象有效地替换了对 join() ,否则不建立连接点时-通常,默认的“连接点”是 Query 对象要选择的实体列表。

典型示例:

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() 方法现在可以实现这一点。有关此行为的描述,请参见该方法。

selectable

返回 Select 此发出的对象 Query .

用于 inspect() 兼容性,相当于:

query.enable_eagerloads(False).with_labels().statement
slice(start, stop)

计算的“切片” 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)
statement

此查询表示的完整select语句。

默认情况下,语句不会将消除歧义的标签应用于构造,除非先调用WITH摼labels(true)。

subquery(name=None, with_labels=False, reduce_columns=False)

返回由该语句表示的完整select语句 Query ,嵌入到 Alias .

查询中的热切联接生成被禁用。

参数
  • name -- 要指定为别名的字符串名称;这将传递给 FromClause.alias() .如果 None ,将在编译时确定地生成名称。

  • with_labels -- 如果属实, with_labels() 将在 Query 首先将表限定标签应用于所有列。

  • reduce_columns -- 如果属实, Select.reduce_columns() 将调用结果 select() 构造,删除相同的命名列,其中一个列还通过外键或WHERE子句等效引用另一个列。

suffix_with(*suffixes)

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

参数

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

1.0.0 新版功能.

union(*q)

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

例如。::

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

q3 = q1.union(q2)

该方法接受多个查询对象以控制嵌套的级别。一系列 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中调用的查询上呈现order by,除非等要禁用所有order by子句,包括在映射器上配置的子句,请发出 query.order_by(None) -结果 Query 对象不会在其select语句中呈现order by。

union_all(*q)

针对一个或多个查询生成一个联合所有查询。

工作方式与 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')

警告

这个 Query.update() 方法是一种“批量”操作,它绕过ORM工作自动化单元,以提高性能。 请阅读以下所有注意事项和警告。

参数
  • values -- 一种字典,其中属性名或作为键映射的属性或SQL表达式,文字值或SQL表达式作为值。如果 parameter-ordered mode 如果需要,值可以作为2个元组的列表传递;这要求 preserve_parameter_order 将标志传递给 Query.update.update_args 字典也是。…versionchanged::1.0.0-现在根据映射的实体解析值字典中的字符串名称;以前,这些字符串作为文本列名称传递,没有映射器级别的转换。

  • synchronize_session -- 选择更新会话中对象属性的策略。有效值为: False -不要同步会话。这个选项是最有效的,并且在会话过期后是可靠的,这通常发生在commit()之后,或者显式地使用expire_all()。在到期之前,更新的对象可能仍然保留在会话中,其属性上的值已过时,这可能导致混淆结果。 'fetch' -在更新之前执行select查询,以查找与更新查询匹配的对象。更新的属性在匹配的对象上过期。 'evaluate' -在Python中直接对会话中的对象评估查询条件。如果未实现对条件的评估,则会引发异常。表达式计算器目前不考虑数据库和python之间不同的字符串排序规则。

  • update_args -- 可选字典(如果存在)将传递给基础 update() 构造为 **kw 对于对象。可用于传递特定于方言的参数,如 mysql_limit 以及其他特殊参数,如 preserve_parameter_order . …添加的版本:1.0.0

返回

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

警告

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

  • 方法确实 not 在python中提供关系级联-假设在更新时为任何需要它的外键引用配置了级联,否则,如果强制使用外键引用,数据库可能会发出完整性冲突。

    更新后,依赖对象 Session 受on-update级联影响的可能不包含当前状态;一旦 Session 过期,通常发生在 Session.commit() 或者可以通过使用 Session.expire_all() .

  • 这个 'fetch' 策略会产生额外的select语句,并将显著降低性能。

  • 这个 'evaluate' 策略对中的所有匹配对象执行扫描 Session ;如果 Session 过期,如通过程序 Session.commit() 调用, 这将导致为每个匹配对象发出选择查询 .

  • 该方法支持多个表更新,如中所述。 多个表更新 ,并且此行为扩展到支持联合继承和其他多表映射的更新。然而, 继承映射器的联接条件不会自动呈现 . 在任何多表更新中都必须小心,以显式地包括这些表之间的联接条件,即使在通常是自动的映射中也是如此。例如一个班 Engineer 子类 Employee ,更新了 Engineer 使用条件的本地表 Employee 本地表可能如下所示:

    session.query(Engineer).\
        filter(Engineer.id == Employee.id).\
        filter(Employee.name == 'dilbert').\
        update({"engineer_type": "programmer"})
  • 标准的多态性 not 包括用于单表或联接表更新-必须添加 手动 ,即使对于单表继承也是如此。

  • 这个 MapperEvents.before_update()MapperEvents.after_update() 事件 不从此方法调用 . 相反, SessionEvents.after_bulk_update() 方法用于对实体行进行批量更新。

参见

Query.delete()

插入、更新和删除 -核心SQL教程

value(column)

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

values(*columns)

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

whereclause

返回此查询的当前Where条件的只读属性。

此返回值是SQL表达式构造,或者 None 如果没有建立标准。

with_entities(*entities)

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

例如。::

# 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)
with_for_update(read=False, nowait=False, of=None, skip_locked=False, key_share=False)

返回一个新的 Query 使用指定的选项 FOR UPDATE 条款。

此方法的行为与 SelectBase.with_for_update() . 当在没有参数的情况下调用时,结果 SELECT 语句将具有 FOR UPDATE 附加条款。当指定其他参数时,后端特定的选项,如 FOR UPDATE NOWAITLOCK IN SHARE MODE 可以生效。

例如。::

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() -核心层面的方法,充分论证和行为描述。

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

为给定实体添加一个索引或其他执行上下文提示,或为此添加可选的 Query .

功能直接传递给 with_hint() ,加上 selectable 可以是 TableAlias 或ORM实体/映射类等。

with_labels()

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

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

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

注解

这个 Query.with_labels() 方法 only 应用的输出 Query.statementnot 到调用系统的任何结果行 Query 本身,例如 Query.first()Query.all() 等等,使用 Query.with_labels() 调用 Query.statement 使用 Session.execute() ::

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

返回一个新的 Query 具有指定的“锁定模式”的对象,它本质上是指 FOR UPDATE 条款。

0.9 版后已移除: 这个 Query.with_lockmode() 方法已弃用,将在将来的版本中删除。请参考 Query.with_for_update() .

参数

mode -- 表示所需锁定模式的字符串。有效值为: * None - translates to no lockmode * 'update' 翻译成 FOR UPDATE (标准SQL,大多数方言都支持) * 'update_nowait' - translates to FOR UPDATE NOWAIT (supported by Oracle, PostgreSQL 8.1 upwards) * 'read' 翻译成 LOCK IN SHARE MODE (用于mysql),以及 FOR SHARE (对于PostgreSQL)

参见

Query.with_for_update() -改进了用于指定 FOR UPDATE 条款。

with_parent(instance, property=None, from_entity=None)

添加将给定实例与子对象或集合关联的筛选条件,使用其属性状态和已建立的 relationship() 配置。

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

参数与 with_parent() ,但给定的属性不能为“无”,在这种情况下,将对该属性执行搜索 Query 对象的目标映射器。

参数
  • instance -- 一个有一些 relationship() .

  • property -- 字符串属性名或类绑定属性,指示应使用来自实例的关系来协调父/子关系。

  • from_entity -- 作为左侧考虑的实体。这默认为 Query 本身。

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

为继承类加载列。

Query.with_polymorphic() 将转换应用于由此表示的“主”映射类 Query . 这里的“主”映射类是指 Query 对象的第一个参数是一个完整类,即 session.query(SomeClass) . 这些转换允许在FROM子句中存在额外的表,以便在查询中提供联接继承子类的列,这既有利于提高加载时间效率,也有利于在查询时使用这些列。

参见文档部分 与多态性一起使用 有关如何使用此方法的详细信息。

with_session(session)

返回A Query 使用给定的 Session .

Query 对象通常使用 Session.query() 方法,建立 Query 不必使用 Session . 这样的 Query 对象,或任何 Query 已经与另一个 Session ,可以产生新的 Query 使用此方法与目标会话关联的对象:

from sqlalchemy.orm import Query

query = Query([MyClass]).filter(MyClass.id == 5)

result = query.with_session(my_session).one()
with_statement_hint(text, dialect_name='*')

在此添加语句提示 Select .

这种方法类似于 Select.with_hint() 但它不需要单独的表,而是作为一个整体应用于语句。

此功能调用到 Select.with_statement_hint() .

1.0.0 新版功能.

with_transformation(fn)

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

例如。::

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

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

这允许为 Query 对象。参见中的示例 建筑变压器 .

yield_per(count)

仅产量 count 一次行。

此方法的目的是在获取非常大的结果集(>10000行)时,对子集合中的结果进行批处理并部分生成结果,这样Python解释器就不需要声明非常大的内存区域,这既耗时又会导致内存使用过度。当使用适当的每次设置的收益率(例如大约1000)时,提取数十万行的性能通常会加倍,即使DBAPIS缓冲行(最多)。

这个 Query.yield_per() 方法 使用集合时不兼容SubQueryLoad Foreign Loading或JoinedLoad Foreign Loading . 它可能与“select-in”预加载兼容, 如果数据库驱动程序支持多个独立的游标 (PysQlite和PSycopg2已知可以工作,MySQL和SQL Server ODBC驱动程序不工作)。

因此,在某些情况下,可以无条件地禁用预加载 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() .

还要注意的是, yield_per() 将设置 stream_results 执行选项为true,当前只有 psycopg2mysqldbpymysql 使用服务器端游标而不是预缓冲此查询的所有行的方言。其他二苯甲哌啶 pre-buffer all rows 在提供之前。原始数据库行的内存使用比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() 函数用于创建映射类到新可选对象的即席映射。默认情况下,从通常映射的可选对象(通常为 Table )使用 FromClause.alias() 方法。然而, aliased() 也可用于将类链接到新的 select() 语句。此外, with_polymorphic() 函数是 aliased() 这是为了指定一个所谓的“多态可选择的”,它对应于同时合并的几个继承子类的联合。

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

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

  • alias -- 要将元素映射到的可选单元。这通常应该是 Alias 对象对应于 Table 类映射到的对象,或 select() 构造与映射兼容。默认情况下,将生成映射表的简单匿名别名。

  • name -- 要用于别名的可选字符串名称(如果不是由 alias 参数。除其他外,名称形成了属性名,可以通过由 Query 对象。

  • flat -- 布尔值,将传递给 FromClause.alias() 调用以便 Join 对象不包括封闭选择。在许多情况下,这会导致更高效的查询。针对嵌套联接的联接将被重写为针对后端不支持此语法的别名select子查询的联接。…版本已添加::0.9.0..参阅: Join.alias()

  • 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(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, 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 对象通常使用 orm.aliased() 功能。当使用 orm.with_polymorphic() 功能。

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

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

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

结果检验对象是 AliasedInsp .

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

基地: sqlalchemy.orm.base.InspectionAttr

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 最终表示别名的构造 TableSelect 构造。

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

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

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

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

基地: sqlalchemy.orm.base.InspectionAttr

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

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

0.9.0 新版功能.

参见

列束

__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 可以作为“单个实体”在任何封闭元组之外以与映射实体相同的方式返回。

c = None

的别名 Bundle.columns .

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

create_row_processor(query, procs, labels)

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

可以被子类重写。

参见

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

label(name)

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

single_entity = False

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

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 表现出类似于 collections.namedtuple() 但是,在Python标准库中提供的构造的体系结构非常不同。不像 collections.namedtuple()KeyedTuple 不是依靠创建自定义子类型来表示一系列新的键,而是每个键 KeyedTuple 实例就地接收其键列表。子类型方法 collections.namedtuple() 引入了显著的复杂性和性能开销,这对于 Query 对象的用例。

参见

查询

_asdict()

返回此内容 KeyedTuple 作为一本字典。

此方法提供与 collections.namedtuple() ,但返回的字典是 not 命令。

_fields

为此返回字符串键名的元组 KeyedTuple .

此方法提供与 collections.namedtuple() .

keys()

继承 keys() 方法 AbstractKeyedTuple

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

class sqlalchemy.orm.strategy_options.Load(entity)

基地: sqlalchemy.sql.expression.Generativesqlalchemy.orm.interfaces.MapperOption

表示修改 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 将被延迟加载,但这些子对象上的其他属性将使用它们的常规加载策略进行加载。

baked_lazyload(attr)

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

orm.baked_lazyload() 用于示例。

contains_eager(attr, alias=None)

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

orm.contains_eager() 用于示例。

defaultload(attr)

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

orm.defaultload() 用于示例。

defer(key)

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

orm.defer() 用于示例。

immediateload(attr)

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

orm.immediateload() 用于示例。

joinedload(attr, innerjoin=None)

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

orm.joinedload() 用于示例。

lazyload(attr)

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

orm.lazyload() 用于示例。

load_only(*attrs)

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

orm.load_only() 用于示例。

noload(attr)

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

orm.noload() 用于示例。

process_query(query)

对给定的应用修改 Query .

process_query_conditionally(query)

与process_query()相同,只是此选项可能不适用于给定的查询。

这通常在延迟加载或标量刷新操作期间使用,以将原始查询中声明的选项传播到用于加载的新查询。对于那些指定propagate_to_loaders=true的选项,会发生这种情况。

raiseload(attr, sql_only=False)

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

orm.raiseload() 用于示例。

selectin_polymorphic(classes)

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

orm.selectin_polymorphic() 用于示例。

selectinload(attr)

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

orm.selectinload() 用于示例。

subqueryload(attr)

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

orm.subqueryload() 用于示例。

undefer(key)

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

orm.undefer() 用于示例。

undefer_group(name)

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

orm.undefer_group() 用于示例。

with_expression(key, expression)

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

orm.with_expression() 用于示例。

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() 在现代使用中并不常用,因为它的功能封装在 Query.join() 方法,它的特点是在 orm.join() 独自一人。明确使用 orm.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 参数已弃用,将在将来的版本中删除。参数无效。

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

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

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

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

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

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

参数
  • instance -- 一个有一些 relationship() .

  • property -- 字符串属性名或类绑定属性,指示应使用来自实例的关系来协调父/子关系。

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