插入、更新、删除¶

插入、更新和删除语句基于以开头的层次结构生成 UpdateBase . 这个 InsertUpdate 构建基于中介的 ValuesBase .

sqlalchemy.sql.expression.delete(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

构建 Delete 对象。

类似功能可通过 delete() 方法对 Table .

参数
  • table -- 要从中删除行的表。

  • whereclause -- A ClauseElement 描述 WHERE 的条件 DELETE 语句。请注意 where() 可以改用生成方法。WHERE子句可以引用多个表。对于支持此功能的数据库, DELETE..USING 或生成类似的子句。对于不支持多表删除语句的数据库,该语句将失败。在WHERE子句中引用其他表的SQL标准方法是使用相关的子查询::users.delete()。WHERE(users.c.name==select( [addresses.c.email_address] )。其中(addresses.c.user_id==users.c.id)。作为_scalar())…versionChanged::1.2.0 delete的where子句可以引用多个表。

参见

删除 -SQL表达式教程

sqlalchemy.sql.expression.insert(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

构建一个 Insert 对象。

类似功能可通过 insert() 方法对 Table .

参数
  • table -- TableClause 这是插入的主题。

  • values -- 要插入的值集合;请参见 Insert.values() 有关此处允许格式的说明。完全可以省略;a Insert 构造还将根据传递给的参数在执行时动态地呈现values子句。 Connection.execute() .

  • inline -- 如果为true,则不会尝试检索要在语句中提供的SQL生成的默认值;特别是,这允许在语句中“内联”呈现SQL表达式,而无需预先执行它们;对于支持“返回”的后端,这将关闭ST的“隐式返回”功能。声明。

如果两者 values 并且存在编译时绑定参数,编译时绑定参数重写 values 以每键为基础。

里面的钥匙 values 要么可以 Column 对象或其字符串标识符。每个键可引用以下其中一个:

  • 文字数据值(即字符串、数字等);

  • 列对象;

  • 选择语句。

如果A SELECT 指定了引用此语句的语句 INSERT 语句的表,该语句将与 INSERT 语句。

参见

插入表达式 -SQL表达式教程

插入、更新和删除 -SQL表达式教程

sqlalchemy.sql.expression.update(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

构建一个 Update 对象。

例如。::

from sqlalchemy import update

stmt = update(users).where(users.c.id==5).\
        values(name='user #5')

类似功能可通过 update() 方法对 Table ::

stmt = users.update().\
            where(users.c.id==5).\
            values(name='user #5')
参数
  • table -- A Table 表示要更新的数据库表的对象。

  • whereclause -- 描述的可选SQL表达式 WHERE 的条件 UPDATE 语句。现代应用可能更喜欢使用生成 where() 方法来指定 WHERE 条款。WHERE子句可以引用多个表。对于支持此功能的数据库, UPDATE FROM 将生成子句,或者在mysql上生成多表更新。对于不支持多表更新语句的数据库,该语句将失败。在WHERE子句中引用其他表的SQL标准方法是使用相关的子查询::users.update().values(name='ed').where(users.c.name==select( [addresses.c.email_address] ).其中(addresses.c.user_id==users.c.id)。as_scalar())

  • values -- 可选字典,指定 SET 的条件 UPDATE . 如果留下 None , the SET 条件由语句执行和/或编译期间传递给语句的参数决定。当在没有任何参数的情况下独立编译时, SET 为所有列生成子句。现代应用可能更喜欢使用生成 Update.values() 方法设置update语句的值。

  • inline -- 如果为true,则SQL默认值出现在 Column 对象通过 default 关键字将被“inline”编译到语句中,而不是预先执行。这意味着它们的值在从返回的字典中不可用。 ResultProxy.last_updated_params() .

  • preserve_parameter_order -- 如果为true,则update语句将接收参数 only 通过 Update.values() 方法,并且它们必须作为python传递 list 2元组。呈现的update语句将为保持此顺序的每个引用列发出set子句。…版本已添加::1.0.10..参阅: 参数顺序更新 -完整的示例 preserve_parameter_order 标志

如果两者 values 并且存在编译时绑定参数,编译时绑定参数重写 values 以每键为基础。

里面的钥匙 values 要么可以 Column 对象或其字符串标识符(特别是 Column ,通常但不一定等于其“名称”)。通常情况下, Column 此处使用的对象应是目标的一部分 Table 这是要更新的表。但是,在使用MySQL时,多表更新语句可以引用WHERE子句中引用的任何表中的列。

中提到的值 values 通常是:

  • 文字数据值(即字符串、数字等)

  • SQL表达式,如相关的 Column ,一个返回的标量 select() 构造等。

合并时 select() 在值子句中构造 update() 构造,子查询由 select() 应该是 相关的 到父表,即提供将子查询中的表链接到要更新的外部表的条件:

users.update().values(
        name=select([addresses.c.email_address]).\
                where(addresses.c.user_id==users.c.id).\
                as_scalar()
    )

参见

插入、更新和删除 -SQL表达式语言教程

class sqlalchemy.sql.expression.Delete(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

基地: sqlalchemy.sql.expression.UpdateBase

表示删除构造。

这个 Delete 对象是使用 delete() 功能。

__eq__

继承 __eq__ 属性 object

返回self==值。

__init__(table, whereclause=None, bind=None, returning=None, prefixes=None, **dialect_kw)

构建新的 Delete 对象。

此构造函数被镜像为公共API函数;请参见 delete() 完整的用法和参数描述。

__le__

继承 __le__ 属性 object

返回self<=value。

__lt__

继承 __lt__ 属性 object

返回self<value。

__ne__

继承 __ne__ 属性 object

回归自我!=值。

classmethod argument_for(dialect_name, argument_name, default)

为此类添加一种新的方言特定关键字参数。

例如。::

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

这个 DialectKWArgs.argument_for() 方法是按参数向 DefaultDialect.construct_arguments 字典。此字典提供了各种模式级构造代表方言接受的参数名列表。

新方言通常应同时将此字典指定为方言类的数据成员。临时添加参数名的用例通常用于最终用户代码,该代码也使用自定义编译方案,该方案使用附加参数。

参数
  • dialect_name -- 方言的名称。方言必须可定位,否则 NoSuchModuleError 提高了。方言还必须包括现有的 DefaultDialect.construct_arguments 集合,指示它参与关键字参数验证和默认系统,否则 ArgumentError 提高了。如果方言不包含此集合,则可以代表此方言指定任何关键字参数。包含在sqlAlchemy中的所有方言都包含此集合,但是对于第三方方言,支持可能有所不同。

  • argument_name -- 参数的名称。

  • default -- 参数的默认值。

0.9.4 新版功能.

bind

继承 bind 属性 UpdateBase

返回链接到此的“bind” UpdateBase 或A Table 与之相关。

compare(other, **kw)

继承 compare() 方法 ClauseElement

将这一条款与给定的条款进行比较。

子类应该覆盖默认行为,这是一个直接的身份比较。

* *kw是子类compare()方法使用的参数,可用于修改比较条件。(见 ColumnElement

compile(default, bind=None, dialect=None, **kw)

继承 compile() 方法 ClauseElement

编译此SQL表达式。

返回值为 Compiled 对象。调用 str()unicode() 返回的值将生成结果的字符串表示形式。这个 Compiled 对象还可以返回绑定参数名称和值的字典,方法是 params 访问器。

参数
  • bind -- 安 EngineConnection 从哪一个 Compiled 将被收购。此参数优先于此 ClauseElement 如果有绑定的引擎。

  • column_keys -- 用于insert和update语句,列名称的列表,应出现在编译语句的values子句中。如果 None ,将呈现目标表对象中的所有列。

  • dialect -- A Dialect 实例,其中 Compiled 将被收购。此参数优先于 bind 还有这个论点 ClauseElement 如果有绑定的引擎。

  • inline -- 用于insert语句,对于不支持对新生成的主键列进行内联检索的方言,将强制用于创建新主键值的表达式在insert语句的value s子句中进行内联呈现。这通常指序列执行,但也可能指与主键关联的任何服务器端默认生成函数。 Column .

  • compile_kwargs -- 在所有“访问”方法中传递给编译器的附加参数的可选字典。例如,这允许将任何自定义标志传递给自定义编译构造。它还用于通过 literal_binds 通过::从sqlachemy.sql导入表、列,选择t=table('t',column('x'))s=select( [t] .where(t.c.x==5)print s.compile(compile“literal_binds”:true)。添加的版本:0.9.0

cte(name=None, recursive=False)

继承 cte() 方法 HasCTE

返回一个新的 CTE 或公用表表达式实例。

公共表表达式是一种SQL标准,通过该标准,select语句可以使用名为“with”的子句,利用随主语句一起指定的辅助语句。还可以使用与union相关的特殊语义来允许“递归”查询,其中select语句可以根据以前选择的行集进行绘制。

CTE还可以应用于某些数据库上的DML构造更新、插入和删除,既可以作为与返回结合时CTE行的源,也可以作为CTE行的使用者。

SQLAlchemy检测 CTE 对象,其处理方式与 Alias 对象,作为要传递到语句的FROM子句以及语句顶部的WITH子句的特殊元素。

在 1.1 版更改: 添加了对更新/插入/删除作为CTE的支持,将CTE添加到更新/插入/删除。

参数
  • name -- 为公用表表达式指定的名称。喜欢 _FromClause.alias() ,名称可以保留为 None 在这种情况下,查询编译时将使用匿名符号。

  • recursive -- 如果 True 将渲染 WITH RECURSIVE . 递归公用表表达式将与union all一起使用,以便从已选定的行派生行。

以下示例包括来自PostgreSQL文档http://www.postgresql.org/docs/current/static/queries-with.html的两个示例,以及其他示例。

示例1,非递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例2,递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例3,使用update和insert with ctes的upsert::

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select([literal(product_id), literal(day), literal(count)])
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

参见

orm.query.Query.cte() -ORM版本 HasCTE.cte() .

dialect_kwargs

指定为此构造的方言特定选项的关键字参数集合。

这些论据以原版呈现在这里。 <dialect>_<kwarg> 格式。只包括实际传递的参数;与 DialectKWArgs.dialect_options 集合,其中包含此方言已知的所有选项,包括默认值。

集合也是可写的;接受窗体的键 <dialect>_<kwarg> 值将组合到选项列表中。

0.9.2 新版功能.

在 0.9.4 版更改: 这个 DialectKWArgs.dialect_kwargs 集合现在可写。

参见

DialectKWArgs.dialect_options -嵌套字典窗体

dialect_options

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表,键控为 <dialect_name><argument_name> . 例如, postgresql_where 参数可定位为:

arg = my_object.dialect_options['postgresql']['where']

0.9.2 新版功能.

参见

DialectKWArgs.dialect_kwargs -平字典形式

execute(*multiparams, **params)

继承 execute() 方法 Executable

编译并执行此 Executable .

execution_options(**kw)

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

可以对每个语句或每个语句设置执行选项。 Connection 基础。另外, Engine 和ORM Query 对象提供对执行选项的访问,这些执行选项反过来在连接时进行配置。

这个 execution_options() 方法是生成的。返回此语句的新实例,其中包含以下选项:

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意,只有可能的执行选项的一个子集可以应用于语句-这些选项包括“autocommit”和“stream_results”,但不包括“isolation_level”或“compiled_cache”。见 Connection.execution_options() 完整的选项列表。

get_children(**kwargs)

返回此的直接子元素 ClauseElement .

用于访问遍历。

* *Kwargs可能包含更改返回的集合的标志,例如返回项的子集以减少更大的遍历,或从不同上下文返回子项(例如架构级集合而不是子句级)。

get_execution_options()

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

1.3 新版功能.

kwargs

继承 kwargs 属性 DialectKWArgs

同义词 DialectKWArgs.dialect_kwargs .

params(*arg, **kw)

继承 params() 方法 UpdateBase

设置语句的参数。

此方法引发 NotImplementedError 在基类上,并被重写 ValuesBase 提供update和insert的set/values子句。

prefix_with(*expr, **kw)

继承 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式,即select、insert、update或delete。生成的。

这用于支持后端特定的前缀关键字,如mysql提供的前缀关键字。

例如。::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用指定多个前缀 prefix_with() .

参数
  • *expr -- 文本或 ClauseElement 在插入、更新或删除关键字后呈现的构造。…警告:: HasPrefixes.prefix_with.*expr 参数 HasPrefixes.prefix_with() 可以作为python字符串参数传递,该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .

  • **kw -- 只接受一个关键字“dialect”。这是一个可选的字符串方言名称,它将此前缀的呈现限制为仅显示该方言。

returning(*cols)

继承 returning() 方法 UpdateBase

添加 RETURNING 或与此声明等效的子句。

例如。::

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

列表达式的给定集合应派生自作为插入、更新或删除目标的表。同时 Column 对象是典型的,元素也可以是表达式:

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后,将在语句中呈现返回子句或等效数据库。对于插入和更新,这些值是新插入/更新的值。对于“删除”,值是已删除的行的值。

执行后,将返回的列的值通过结果集可用,并且可以使用 ResultProxy.fetchone() 类似的。对于本机不支持返回值(即cx_oracle)的dbapis,sqlAlchemy将在结果级别近似此行为,以便提供合理数量的行为中立性。

请注意,并非所有数据库/dbapis都支持返回。对于那些不支持的后端,在编译和/或执行时会引发异常。对于那些支持它的人来说,后端的功能差异很大,包括对executeMany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

参见

ValuesBase.return_defaults() -为有效获取服务器端默认值和触发器而量身定制的一种替代方法,用于单行插入或更新。

scalar(*multiparams, **params)

继承 scalar() 方法 Executable

编译并执行此 Executable ,返回结果的标量表示。

self_group(against=None)

继承 self_group() 方法 ClauseElement

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select() 当放入另一个的FROM子句时构造 select() . (请注意,通常应使用 Select.alias() 方法,因为许多平台都需要命名嵌套的select语句)。

当表达式组合在一起时,应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

unique_params(*optionaldict, **kwargs)

返回副本 bindparam() 元素被替换。

功能与 params() ,除了添加 unique=True 以影响绑定参数,以便可以使用多个语句。

where(whereclause)

将给定的WHERE子句添加到新返回的DELETE构造中。

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

继承 with_hint() 方法 UpdateBase

在此INSERT/UPDATE/DELETE语句中添加单个表的表提示。

注解

UpdateBase.with_hint() 当前仅适用于Microsoft SQL Server。对于MySQL插入/更新/删除提示,请使用 UpdateBase.prefix_with() .

提示文本呈现在正在使用的数据库后端的适当位置,相对于 Table 这是本声明的主题,或者是给定的主题 Table 作为传递 selectable 争论。

这个 dialect_name 选项将把特定提示的呈现限制到特定的后端。例如,要添加仅对SQL Server有效的提示,请执行以下操作:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
参数
  • text -- 提示的文本。

  • selectable -- 可选择的 Table 它将更新或删除中的FROM子句的元素指定为提示的主题-仅适用于某些后端。

  • dialect_name -- 默认为 * 如果指定为特定方言的名称,则仅在使用该方言时应用这些提示。

class sqlalchemy.sql.expression.Insert(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

基地: sqlalchemy.sql.expression.ValuesBase

表示插入构造。

这个 Insert 对象是使用 insert() 功能。

__eq__

继承 __eq__ 属性 object

返回self==值。

__init__(table, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, **dialect_kw)

构建新的 Insert 对象。

此构造函数被镜像为公共API函数;请参见 insert() 完整的用法和参数描述。

__le__

继承 __le__ 属性 object

返回self<=value。

__lt__

继承 __lt__ 属性 object

返回self<value。

__ne__

继承 __ne__ 属性 object

回归自我!=值。

classmethod argument_for(dialect_name, argument_name, default)

为此类添加一种新的方言特定关键字参数。

例如。::

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

这个 DialectKWArgs.argument_for() 方法是按参数向 DefaultDialect.construct_arguments 字典。此字典提供了各种模式级构造代表方言接受的参数名列表。

新方言通常应同时将此字典指定为方言类的数据成员。临时添加参数名的用例通常用于最终用户代码,该代码也使用自定义编译方案,该方案使用附加参数。

参数
  • dialect_name -- 方言的名称。方言必须可定位,否则 NoSuchModuleError 提高了。方言还必须包括现有的 DefaultDialect.construct_arguments 集合,指示它参与关键字参数验证和默认系统,否则 ArgumentError 提高了。如果方言不包含此集合,则可以代表此方言指定任何关键字参数。包含在sqlAlchemy中的所有方言都包含此集合,但是对于第三方方言,支持可能有所不同。

  • argument_name -- 参数的名称。

  • default -- 参数的默认值。

0.9.4 新版功能.

bind

继承 bind 属性 UpdateBase

返回链接到此的“bind” UpdateBase 或A Table 与之相关。

compare(other, **kw)

继承 compare() 方法 ClauseElement

将这一条款与给定的条款进行比较。

子类应该覆盖默认行为,这是一个直接的身份比较。

* *kw是子类compare()方法使用的参数,可用于修改比较条件。(见 ColumnElement

compile(default, bind=None, dialect=None, **kw)

继承 compile() 方法 ClauseElement

编译此SQL表达式。

返回值为 Compiled 对象。调用 str()unicode() 返回的值将生成结果的字符串表示形式。这个 Compiled 对象还可以返回绑定参数名称和值的字典,方法是 params 访问器。

参数
  • bind -- 安 EngineConnection 从哪一个 Compiled 将被收购。此参数优先于此 ClauseElement 如果有绑定的引擎。

  • column_keys -- 用于insert和update语句,列名称的列表,应出现在编译语句的values子句中。如果 None ,将呈现目标表对象中的所有列。

  • dialect -- A Dialect 实例,其中 Compiled 将被收购。此参数优先于 bind 还有这个论点 ClauseElement 如果有绑定的引擎。

  • inline -- 用于insert语句,对于不支持对新生成的主键列进行内联检索的方言,将强制用于创建新主键值的表达式在insert语句的value s子句中进行内联呈现。这通常指序列执行,但也可能指与主键关联的任何服务器端默认生成函数。 Column .

  • compile_kwargs -- 在所有“访问”方法中传递给编译器的附加参数的可选字典。例如,这允许将任何自定义标志传递给自定义编译构造。它还用于通过 literal_binds 通过::从sqlachemy.sql导入表、列,选择t=table('t',column('x'))s=select( [t] .where(t.c.x==5)print s.compile(compile“literal_binds”:true)。添加的版本:0.9.0

cte(name=None, recursive=False)

继承 cte() 方法 HasCTE

返回一个新的 CTE 或公用表表达式实例。

公共表表达式是一种SQL标准,通过该标准,select语句可以使用名为“with”的子句,利用随主语句一起指定的辅助语句。还可以使用与union相关的特殊语义来允许“递归”查询,其中select语句可以根据以前选择的行集进行绘制。

CTE还可以应用于某些数据库上的DML构造更新、插入和删除,既可以作为与返回结合时CTE行的源,也可以作为CTE行的使用者。

SQLAlchemy检测 CTE 对象,其处理方式与 Alias 对象,作为要传递到语句的FROM子句以及语句顶部的WITH子句的特殊元素。

在 1.1 版更改: 添加了对更新/插入/删除作为CTE的支持,将CTE添加到更新/插入/删除。

参数
  • name -- 为公用表表达式指定的名称。喜欢 _FromClause.alias() ,名称可以保留为 None 在这种情况下,查询编译时将使用匿名符号。

  • recursive -- 如果 True 将渲染 WITH RECURSIVE . 递归公用表表达式将与union all一起使用,以便从已选定的行派生行。

以下示例包括来自PostgreSQL文档http://www.postgresql.org/docs/current/static/queries-with.html的两个示例,以及其他示例。

示例1,非递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例2,递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例3,使用update和insert with ctes的upsert::

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select([literal(product_id), literal(day), literal(count)])
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

参见

orm.query.Query.cte() -ORM版本 HasCTE.cte() .

dialect_kwargs

指定为此构造的方言特定选项的关键字参数集合。

这些论据以原版呈现在这里。 <dialect>_<kwarg> 格式。只包括实际传递的参数;与 DialectKWArgs.dialect_options 集合,其中包含此方言已知的所有选项,包括默认值。

集合也是可写的;接受窗体的键 <dialect>_<kwarg> 值将组合到选项列表中。

0.9.2 新版功能.

在 0.9.4 版更改: 这个 DialectKWArgs.dialect_kwargs 集合现在可写。

参见

DialectKWArgs.dialect_options -嵌套字典窗体

dialect_options

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表,键控为 <dialect_name><argument_name> . 例如, postgresql_where 参数可定位为:

arg = my_object.dialect_options['postgresql']['where']

0.9.2 新版功能.

参见

DialectKWArgs.dialect_kwargs -平字典形式

execute(*multiparams, **params)

继承 execute() 方法 Executable

编译并执行此 Executable .

execution_options(**kw)

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

可以对每个语句或每个语句设置执行选项。 Connection 基础。另外, Engine 和ORM Query 对象提供对执行选项的访问,这些执行选项反过来在连接时进行配置。

这个 execution_options() 方法是生成的。返回此语句的新实例,其中包含以下选项:

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意,只有可能的执行选项的一个子集可以应用于语句-这些选项包括“autocommit”和“stream_results”,但不包括“isolation_level”或“compiled_cache”。见 Connection.execution_options() 完整的选项列表。

from_select(names, select, include_defaults=True)

返回一个新的 Insert 表示一个 INSERT...FROM SELECT 语句。

例如。::

sel = select([table1.c.a, table1.c.b]).where(table1.c.c > 5)
ins = table2.insert().from_select(['a', 'b'], sel)
参数
  • names -- 字符串列名序列或 Column 表示目标列的对象。

  • select -- 一 select() 构建, FromClause 或其他构造,其分解为 FromClause ,例如ORM Query 对象等。从此From子句返回的列的顺序应与作为 names 参数;虽然在传递到数据库之前不检查此项,但是如果这些列列表不对应,数据库通常会引发异常。

  • include_defaults -- 如果为true,则为上指定的非服务器默认值和SQL表达式 Column 对象(如 列插入/更新默认值 )名称列表中未另行指定的值将呈现到insert和select语句中,以便这些值也包含在要插入的数据中。…注意:只调用使用python可调用函数的python端默认值 once 对于整个陈述,以及 不是每行 . …添加的版本:1.0.0- Insert.from_select() 现在将python端和sql表达式列默认呈现到列的select语句中,否则不包括在列名称列表中。

在 1.0.0 版更改: 使用From Select的插入意味着 insert.inline 标志设置为true,表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行,因此 ResultProxy.inserted_primary_key 访问器不适用。

get_children(**kwargs)

返回此的直接子元素 ClauseElement .

用于访问遍历。

* *Kwargs可能包含更改返回的集合的标志,例如返回项的子集以减少更大的遍历,或从不同上下文返回子项(例如架构级集合而不是子句级)。

get_execution_options()

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

1.3 新版功能.

kwargs

继承 kwargs 属性 DialectKWArgs

同义词 DialectKWArgs.dialect_kwargs .

params(*arg, **kw)

继承 params() 方法 UpdateBase

设置语句的参数。

此方法引发 NotImplementedError 在基类上,并被重写 ValuesBase 提供update和insert的set/values子句。

prefix_with(*expr, **kw)

继承 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式,即select、insert、update或delete。生成的。

这用于支持后端特定的前缀关键字,如mysql提供的前缀关键字。

例如。::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用指定多个前缀 prefix_with() .

参数
  • *expr -- 文本或 ClauseElement 在插入、更新或删除关键字后呈现的构造。…警告:: HasPrefixes.prefix_with.*expr 参数 HasPrefixes.prefix_with() 可以作为python字符串参数传递,该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .

  • **kw -- 只接受一个关键字“dialect”。这是一个可选的字符串方言名称,它将此前缀的呈现限制为仅显示该方言。

return_defaults(*cols)

利用一个 RETURNING 用于获取服务器端表达式和默认值的子句。

例如。::

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持返回的后端时,由SQL表达式或服务器端默认值生成的所有列值都将添加到任何现有的返回子句中,前提是 UpdateBase.returning() 不能同时使用。然后,列值将在结果中使用 ResultProxy.returned_defaults 作为字典的访问器,引用键入到 Column 对象及其 .key .

这种方法不同于 UpdateBase.returning() 以这些方式:

  1. ValuesBase.return_defaults() 仅用于与一行完全匹配的insert或update语句。一般意义上的返回构造支持多行用于多行更新或删除语句,或用于返回多行的插入的特殊情况(例如,insert from select、multi-values子句)。 ValuesBase.return_defaults() 仅用于“ORM样式”单行插入/更新语句。语句返回的行在 ValuesBase.return_defaults() 使用。相比之下, UpdateBase.returning() 使返回的结果集保持原样,包含任意数量的行的集合。

  2. 它与提取自动生成的主键值(也称为“隐式返回”)的现有逻辑兼容。支持返回的后端将自动利用返回来获取新生成的主键的值;而 UpdateBase.returning() 方法规避了这种行为, ValuesBase.return_defaults() 保持原样。

  3. 它可以针对任何后端调用。不支持返回的后端将跳过功能的使用,而不是引发异常。的返回值 ResultProxy.returned_defaultsNone

ValuesBase.return_defaults() 被ORM用来为 eager_defaults 特点 mapper() .

参数

cols -- 列键名称的可选列表或 Column 对象。如果省略,则服务器上计算的所有列表达式都将添加到返回列表中。

0.9.0 新版功能.

returning(*cols)

继承 returning() 方法 UpdateBase

添加 RETURNING 或与此声明等效的子句。

例如。::

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

列表达式的给定集合应派生自作为插入、更新或删除目标的表。同时 Column 对象是典型的,元素也可以是表达式:

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后,将在语句中呈现返回子句或等效数据库。对于插入和更新,这些值是新插入/更新的值。对于“删除”,值是已删除的行的值。

执行后,将返回的列的值通过结果集可用,并且可以使用 ResultProxy.fetchone() 类似的。对于本机不支持返回值(即cx_oracle)的dbapis,sqlAlchemy将在结果级别近似此行为,以便提供合理数量的行为中立性。

请注意,并非所有数据库/dbapis都支持返回。对于那些不支持的后端,在编译和/或执行时会引发异常。对于那些支持它的人来说,后端的功能差异很大,包括对executeMany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

参见

ValuesBase.return_defaults() -为有效获取服务器端默认值和触发器而量身定制的一种替代方法,用于单行插入或更新。

scalar(*multiparams, **params)

继承 scalar() 方法 Executable

编译并执行此 Executable ,返回结果的标量表示。

self_group(against=None)

继承 self_group() 方法 ClauseElement

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select() 当放入另一个的FROM子句时构造 select() . (请注意,通常应使用 Select.alias() 方法,因为许多平台都需要命名嵌套的select语句)。

当表达式组合在一起时,应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

unique_params(*optionaldict, **kwargs)

返回副本 bindparam() 元素被替换。

功能与 params() ,除了添加 unique=True 以影响绑定参数,以便可以使用多个语句。

values(*args, **kwargs)

继承 values() 方法 ValuesBase

为insert语句指定一个fixed values子句,或为update指定set子句。

请注意 InsertUpdate 根据传递给的参数,构造支持值和/或set子句的每次执行时格式设置。 Connection.execute() . 然而, ValuesBase.values() 方法可用于“修复”语句中的一组特定参数。

多次调用 ValuesBase.values() 将生成一个新的构造,每个构造都修改了参数列表,以包含发送的新参数。在单个参数字典的典型情况下,新传递的键将替换前面构造中的相同键。在基于列表的“多个值”构造的情况下,每个新的值列表都会扩展到现有的值列表中。

参数
  • **kwargs -- 表示字符串键的键值对 Column 映射到要呈现到values或set子句中的值:users.insert().values(name=“some name”)users.update().where(users.c.id==5).values(name=“some name”)

  • *args -- 作为传递键/值参数的替代方法,可以将字典、元组或字典或元组列表作为单个位置参数传递,以形成语句的values或set子句。接受的表单根据是否 InsertUpdate 构建。对于任何一个 InsertUpdate 构造时,可以传递一个字典,其工作方式与Kwargs Form::Users.Insert().Values(“name”:“some name”)Users.Update().Values(“name”:“some new name”)相同,但更常见的是针对 Insert 构造时,还接受包含表中每个列的条目的元组::users.insert().values((5,“some name”))和 Insert construct还支持传递字典列表或全表元组,服务器上的这些列表将呈现“多个值”较不常见的SQL语法-后端支持此语法,如sqlite、postgresql、mysql,但不一定是其他::users.insert()。values( [“name”:“some name”,“name”:“some other name”,“name”:“yet another name”,] )上面的表单将呈现类似于::insert into users(name)values的multiple values语句。 (:name_1), (:name_2), (:name_3) It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. The above syntax is a special syntax not typically used. To emit an INSERT statement against multiple rows, the normal method is to pass a multiple values list to the Connection.execute() 方法,它由所有数据库后端支持,通常对于大量参数更有效。…参阅: 执行多个语句 -介绍插入和其他语句的多参数集调用的传统核心方法。…versionChanged::1.0.0使用多值子句的插入,即使是长度为1的列表,也意味着 Insert.inline 标志设置为true,表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行,因此 ResultProxy.inserted_primary_key 访问器不适用。…versionChanged::1.0.0多值插入现在支持具有Python端默认值和可调用文件的列,方式与“ExecuteMany”调用方式相同;可调用文件对每一行进行调用。见 当使用多值插入时,为每行单独调用python端默认值 其他细节。这个 Update 构造支持一个特殊的表单,该表单是2个元组的列表,在提供时,必须与 preserve_parameter_order 参数。此窗体使update语句使用给定的参数顺序呈现set子句 Update.values() ,而不是 Table . …versionAdded::1.0.10-通过 preserve_parameter_order 标志。…参阅: 参数顺序更新 -完整的示例 preserve_parameter_order 标志

参见

插入、更新和删除 -SQL表达式语言教程

insert() -产生一个 INSERT 陈述

update() -产生一个 UPDATE 陈述

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

继承 with_hint() 方法 UpdateBase

在此INSERT/UPDATE/DELETE语句中添加单个表的表提示。

注解

UpdateBase.with_hint() 当前仅适用于Microsoft SQL Server。对于MySQL插入/更新/删除提示,请使用 UpdateBase.prefix_with() .

提示文本呈现在正在使用的数据库后端的适当位置,相对于 Table 这是本声明的主题,或者是给定的主题 Table 作为传递 selectable 争论。

这个 dialect_name 选项将把特定提示的呈现限制到特定的后端。例如,要添加仅对SQL Server有效的提示,请执行以下操作:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
参数
  • text -- 提示的文本。

  • selectable -- 可选择的 Table 它将更新或删除中的FROM子句的元素指定为提示的主题-仅适用于某些后端。

  • dialect_name -- 默认为 * 如果指定为特定方言的名称,则仅在使用该方言时应用这些提示。

class sqlalchemy.sql.expression.Update(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

基地: sqlalchemy.sql.expression.ValuesBase

表示更新构造。

这个 Update 对象是使用 update() 功能。

__eq__

继承 __eq__ 属性 object

返回self==值。

__init__(table, whereclause=None, values=None, inline=False, bind=None, prefixes=None, returning=None, return_defaults=False, preserve_parameter_order=False, **dialect_kw)

构建新的 Update 对象。

此构造函数被镜像为公共API函数;请参见 update() 完整的用法和参数描述。

__le__

继承 __le__ 属性 object

返回self<=value。

__lt__

继承 __lt__ 属性 object

返回self<value。

__ne__

继承 __ne__ 属性 object

回归自我!=值。

classmethod argument_for(dialect_name, argument_name, default)

为此类添加一种新的方言特定关键字参数。

例如。::

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

这个 DialectKWArgs.argument_for() 方法是按参数向 DefaultDialect.construct_arguments 字典。此字典提供了各种模式级构造代表方言接受的参数名列表。

新方言通常应同时将此字典指定为方言类的数据成员。临时添加参数名的用例通常用于最终用户代码,该代码也使用自定义编译方案,该方案使用附加参数。

参数
  • dialect_name -- 方言的名称。方言必须可定位,否则 NoSuchModuleError 提高了。方言还必须包括现有的 DefaultDialect.construct_arguments 集合,指示它参与关键字参数验证和默认系统,否则 ArgumentError 提高了。如果方言不包含此集合,则可以代表此方言指定任何关键字参数。包含在sqlAlchemy中的所有方言都包含此集合,但是对于第三方方言,支持可能有所不同。

  • argument_name -- 参数的名称。

  • default -- 参数的默认值。

0.9.4 新版功能.

bind

继承 bind 属性 UpdateBase

返回链接到此的“bind” UpdateBase 或A Table 与之相关。

compare(other, **kw)

继承 compare() 方法 ClauseElement

将这一条款与给定的条款进行比较。

子类应该覆盖默认行为,这是一个直接的身份比较。

* *kw是子类compare()方法使用的参数,可用于修改比较条件。(见 ColumnElement

compile(default, bind=None, dialect=None, **kw)

继承 compile() 方法 ClauseElement

编译此SQL表达式。

返回值为 Compiled 对象。调用 str()unicode() 返回的值将生成结果的字符串表示形式。这个 Compiled 对象还可以返回绑定参数名称和值的字典,方法是 params 访问器。

参数
  • bind -- 安 EngineConnection 从哪一个 Compiled 将被收购。此参数优先于此 ClauseElement 如果有绑定的引擎。

  • column_keys -- 用于insert和update语句,列名称的列表,应出现在编译语句的values子句中。如果 None ,将呈现目标表对象中的所有列。

  • dialect -- A Dialect 实例,其中 Compiled 将被收购。此参数优先于 bind 还有这个论点 ClauseElement 如果有绑定的引擎。

  • inline -- 用于insert语句,对于不支持对新生成的主键列进行内联检索的方言,将强制用于创建新主键值的表达式在insert语句的value s子句中进行内联呈现。这通常指序列执行,但也可能指与主键关联的任何服务器端默认生成函数。 Column .

  • compile_kwargs -- 在所有“访问”方法中传递给编译器的附加参数的可选字典。例如,这允许将任何自定义标志传递给自定义编译构造。它还用于通过 literal_binds 通过::从sqlachemy.sql导入表、列,选择t=table('t',column('x'))s=select( [t] .where(t.c.x==5)print s.compile(compile“literal_binds”:true)。添加的版本:0.9.0

cte(name=None, recursive=False)

继承 cte() 方法 HasCTE

返回一个新的 CTE 或公用表表达式实例。

公共表表达式是一种SQL标准,通过该标准,select语句可以使用名为“with”的子句,利用随主语句一起指定的辅助语句。还可以使用与union相关的特殊语义来允许“递归”查询,其中select语句可以根据以前选择的行集进行绘制。

CTE还可以应用于某些数据库上的DML构造更新、插入和删除,既可以作为与返回结合时CTE行的源,也可以作为CTE行的使用者。

SQLAlchemy检测 CTE 对象,其处理方式与 Alias 对象,作为要传递到语句的FROM子句以及语句顶部的WITH子句的特殊元素。

在 1.1 版更改: 添加了对更新/插入/删除作为CTE的支持,将CTE添加到更新/插入/删除。

参数
  • name -- 为公用表表达式指定的名称。喜欢 _FromClause.alias() ,名称可以保留为 None 在这种情况下,查询编译时将使用匿名符号。

  • recursive -- 如果 True 将渲染 WITH RECURSIVE . 递归公用表表达式将与union all一起使用,以便从已选定的行派生行。

以下示例包括来自PostgreSQL文档http://www.postgresql.org/docs/current/static/queries-with.html的两个示例,以及其他示例。

示例1,非递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例2,递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例3,使用update和insert with ctes的upsert::

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select([literal(product_id), literal(day), literal(count)])
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

参见

orm.query.Query.cte() -ORM版本 HasCTE.cte() .

dialect_kwargs

指定为此构造的方言特定选项的关键字参数集合。

这些论据以原版呈现在这里。 <dialect>_<kwarg> 格式。只包括实际传递的参数;与 DialectKWArgs.dialect_options 集合,其中包含此方言已知的所有选项,包括默认值。

集合也是可写的;接受窗体的键 <dialect>_<kwarg> 值将组合到选项列表中。

0.9.2 新版功能.

在 0.9.4 版更改: 这个 DialectKWArgs.dialect_kwargs 集合现在可写。

参见

DialectKWArgs.dialect_options -嵌套字典窗体

dialect_options

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表,键控为 <dialect_name><argument_name> . 例如, postgresql_where 参数可定位为:

arg = my_object.dialect_options['postgresql']['where']

0.9.2 新版功能.

参见

DialectKWArgs.dialect_kwargs -平字典形式

execute(*multiparams, **params)

继承 execute() 方法 Executable

编译并执行此 Executable .

execution_options(**kw)

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

可以对每个语句或每个语句设置执行选项。 Connection 基础。另外, Engine 和ORM Query 对象提供对执行选项的访问,这些执行选项反过来在连接时进行配置。

这个 execution_options() 方法是生成的。返回此语句的新实例,其中包含以下选项:

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意,只有可能的执行选项的一个子集可以应用于语句-这些选项包括“autocommit”和“stream_results”,但不包括“isolation_level”或“compiled_cache”。见 Connection.execution_options() 完整的选项列表。

get_children(**kwargs)

返回此的直接子元素 ClauseElement .

用于访问遍历。

* *Kwargs可能包含更改返回的集合的标志,例如返回项的子集以减少更大的遍历,或从不同上下文返回子项(例如架构级集合而不是子句级)。

get_execution_options()

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

1.3 新版功能.

kwargs

继承 kwargs 属性 DialectKWArgs

同义词 DialectKWArgs.dialect_kwargs .

params(*arg, **kw)

继承 params() 方法 UpdateBase

设置语句的参数。

此方法引发 NotImplementedError 在基类上,并被重写 ValuesBase 提供update和insert的set/values子句。

prefix_with(*expr, **kw)

继承 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式,即select、insert、update或delete。生成的。

这用于支持后端特定的前缀关键字,如mysql提供的前缀关键字。

例如。::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用指定多个前缀 prefix_with() .

参数
  • *expr -- 文本或 ClauseElement 在插入、更新或删除关键字后呈现的构造。…警告:: HasPrefixes.prefix_with.*expr 参数 HasPrefixes.prefix_with() 可以作为python字符串参数传递,该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .

  • **kw -- 只接受一个关键字“dialect”。这是一个可选的字符串方言名称,它将此前缀的呈现限制为仅显示该方言。

return_defaults(*cols)

利用一个 RETURNING 用于获取服务器端表达式和默认值的子句。

例如。::

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持返回的后端时,由SQL表达式或服务器端默认值生成的所有列值都将添加到任何现有的返回子句中,前提是 UpdateBase.returning() 不能同时使用。然后,列值将在结果中使用 ResultProxy.returned_defaults 作为字典的访问器,引用键入到 Column 对象及其 .key .

这种方法不同于 UpdateBase.returning() 以这些方式:

  1. ValuesBase.return_defaults() 仅用于与一行完全匹配的insert或update语句。一般意义上的返回构造支持多行用于多行更新或删除语句,或用于返回多行的插入的特殊情况(例如,insert from select、multi-values子句)。 ValuesBase.return_defaults() 仅用于“ORM样式”单行插入/更新语句。语句返回的行在 ValuesBase.return_defaults() 使用。相比之下, UpdateBase.returning() 使返回的结果集保持原样,包含任意数量的行的集合。

  2. 它与提取自动生成的主键值(也称为“隐式返回”)的现有逻辑兼容。支持返回的后端将自动利用返回来获取新生成的主键的值;而 UpdateBase.returning() 方法规避了这种行为, ValuesBase.return_defaults() 保持原样。

  3. 它可以针对任何后端调用。不支持返回的后端将跳过功能的使用,而不是引发异常。的返回值 ResultProxy.returned_defaultsNone

ValuesBase.return_defaults() 被ORM用来为 eager_defaults 特点 mapper() .

参数

cols -- 列键名称的可选列表或 Column 对象。如果省略,则服务器上计算的所有列表达式都将添加到返回列表中。

0.9.0 新版功能.

returning(*cols)

继承 returning() 方法 UpdateBase

添加 RETURNING 或与此声明等效的子句。

例如。::

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

列表达式的给定集合应派生自作为插入、更新或删除目标的表。同时 Column 对象是典型的,元素也可以是表达式:

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后,将在语句中呈现返回子句或等效数据库。对于插入和更新,这些值是新插入/更新的值。对于“删除”,值是已删除的行的值。

执行后,将返回的列的值通过结果集可用,并且可以使用 ResultProxy.fetchone() 类似的。对于本机不支持返回值(即cx_oracle)的dbapis,sqlAlchemy将在结果级别近似此行为,以便提供合理数量的行为中立性。

请注意,并非所有数据库/dbapis都支持返回。对于那些不支持的后端,在编译和/或执行时会引发异常。对于那些支持它的人来说,后端的功能差异很大,包括对executeMany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

参见

ValuesBase.return_defaults() -为有效获取服务器端默认值和触发器而量身定制的一种替代方法,用于单行插入或更新。

scalar(*multiparams, **params)

继承 scalar() 方法 Executable

编译并执行此 Executable ,返回结果的标量表示。

self_group(against=None)

继承 self_group() 方法 ClauseElement

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select() 当放入另一个的FROM子句时构造 select() . (请注意,通常应使用 Select.alias() 方法,因为许多平台都需要命名嵌套的select语句)。

当表达式组合在一起时,应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

unique_params(*optionaldict, **kwargs)

返回副本 bindparam() 元素被替换。

功能与 params() ,除了添加 unique=True 以影响绑定参数,以便可以使用多个语句。

values(*args, **kwargs)

继承 values() 方法 ValuesBase

为insert语句指定一个fixed values子句,或为update指定set子句。

请注意 InsertUpdate 根据传递给的参数,构造支持值和/或set子句的每次执行时格式设置。 Connection.execute() . 然而, ValuesBase.values() 方法可用于“修复”语句中的一组特定参数。

多次调用 ValuesBase.values() 将生成一个新的构造,每个构造都修改了参数列表,以包含发送的新参数。在单个参数字典的典型情况下,新传递的键将替换前面构造中的相同键。在基于列表的“多个值”构造的情况下,每个新的值列表都会扩展到现有的值列表中。

参数
  • **kwargs -- 表示字符串键的键值对 Column 映射到要呈现到values或set子句中的值:users.insert().values(name=“some name”)users.update().where(users.c.id==5).values(name=“some name”)

  • *args -- 作为传递键/值参数的替代方法,可以将字典、元组或字典或元组列表作为单个位置参数传递,以形成语句的values或set子句。接受的表单根据是否 InsertUpdate 构建。对于任何一个 InsertUpdate 构造时,可以传递一个字典,其工作方式与Kwargs Form::Users.Insert().Values(“name”:“some name”)Users.Update().Values(“name”:“some new name”)相同,但更常见的是针对 Insert 构造时,还接受包含表中每个列的条目的元组::users.insert().values((5,“some name”))和 Insert construct还支持传递字典列表或全表元组,服务器上的这些列表将呈现“多个值”较不常见的SQL语法-后端支持此语法,如sqlite、postgresql、mysql,但不一定是其他::users.insert()。values( [“name”:“some name”,“name”:“some other name”,“name”:“yet another name”,] )上面的表单将呈现类似于::insert into users(name)values的multiple values语句。 (:name_1), (:name_2), (:name_3) It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. The above syntax is a special syntax not typically used. To emit an INSERT statement against multiple rows, the normal method is to pass a multiple values list to the Connection.execute() 方法,它由所有数据库后端支持,通常对于大量参数更有效。…参阅: 执行多个语句 -介绍插入和其他语句的多参数集调用的传统核心方法。…versionChanged::1.0.0使用多值子句的插入,即使是长度为1的列表,也意味着 Insert.inline 标志设置为true,表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行,因此 ResultProxy.inserted_primary_key 访问器不适用。…versionChanged::1.0.0多值插入现在支持具有Python端默认值和可调用文件的列,方式与“ExecuteMany”调用方式相同;可调用文件对每一行进行调用。见 当使用多值插入时,为每行单独调用python端默认值 其他细节。这个 Update 构造支持一个特殊的表单,该表单是2个元组的列表,在提供时,必须与 preserve_parameter_order 参数。此窗体使update语句使用给定的参数顺序呈现set子句 Update.values() ,而不是 Table . …versionAdded::1.0.10-通过 preserve_parameter_order 标志。…参阅: 参数顺序更新 -完整的示例 preserve_parameter_order 标志

参见

插入、更新和删除 -SQL表达式语言教程

insert() -产生一个 INSERT 陈述

update() -产生一个 UPDATE 陈述

where(whereclause)

返回一个新的update()构造,并将给定表达式添加到其WHERE子句中,通过和(如果有)联接到现有子句。

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

继承 with_hint() 方法 UpdateBase

在此INSERT/UPDATE/DELETE语句中添加单个表的表提示。

注解

UpdateBase.with_hint() 当前仅适用于Microsoft SQL Server。对于MySQL插入/更新/删除提示,请使用 UpdateBase.prefix_with() .

提示文本呈现在正在使用的数据库后端的适当位置,相对于 Table 这是本声明的主题,或者是给定的主题 Table 作为传递 selectable 争论。

这个 dialect_name 选项将把特定提示的呈现限制到特定的后端。例如,要添加仅对SQL Server有效的提示,请执行以下操作:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
参数
  • text -- 提示的文本。

  • selectable -- 可选择的 Table 它将更新或删除中的FROM子句的元素指定为提示的主题-仅适用于某些后端。

  • dialect_name -- 默认为 * 如果指定为特定方言的名称,则仅在使用该方言时应用这些提示。

class sqlalchemy.sql.expression.UpdateBase

基地: sqlalchemy.sql.expression.HasCTEsqlalchemy.sql.base.DialectKWArgssqlalchemy.sql.expression.HasPrefixessqlalchemy.sql.expression.Executablesqlalchemy.sql.expression.ClauseElement

为…奠定基础 INSERTUPDATEDELETE 声明。

__eq__

继承 __eq__ 属性 object

返回self==值。

__init__

继承 __init__ 属性 object

初始化自身。请参阅帮助(键入(self))以获得准确的签名。

__le__

继承 __le__ 属性 object

返回self<=value。

__lt__

继承 __lt__ 属性 object

返回self<value。

__ne__

继承 __ne__ 属性 object

回归自我!=值。

classmethod argument_for(dialect_name, argument_name, default)

为此类添加一种新的方言特定关键字参数。

例如。::

Index.argument_for("mydialect", "length", None)

some_index = Index('a', 'b', mydialect_length=5)

这个 DialectKWArgs.argument_for() 方法是按参数向 DefaultDialect.construct_arguments 字典。此字典提供了各种模式级构造代表方言接受的参数名列表。

新方言通常应同时将此字典指定为方言类的数据成员。临时添加参数名的用例通常用于最终用户代码,该代码也使用自定义编译方案,该方案使用附加参数。

参数
  • dialect_name -- 方言的名称。方言必须可定位,否则 NoSuchModuleError 提高了。方言还必须包括现有的 DefaultDialect.construct_arguments 集合,指示它参与关键字参数验证和默认系统,否则 ArgumentError 提高了。如果方言不包含此集合,则可以代表此方言指定任何关键字参数。包含在sqlAlchemy中的所有方言都包含此集合,但是对于第三方方言,支持可能有所不同。

  • argument_name -- 参数的名称。

  • default -- 参数的默认值。

0.9.4 新版功能.

bind

返回链接到此的“bind” UpdateBase 或A Table 与之相关。

compare(other, **kw)

继承 compare() 方法 ClauseElement

将这一条款与给定的条款进行比较。

子类应该覆盖默认行为,这是一个直接的身份比较。

* *kw是子类compare()方法使用的参数,可用于修改比较条件。(见 ColumnElement

compile(default, bind=None, dialect=None, **kw)

继承 compile() 方法 ClauseElement

编译此SQL表达式。

返回值为 Compiled 对象。调用 str()unicode() 返回的值将生成结果的字符串表示形式。这个 Compiled 对象还可以返回绑定参数名称和值的字典,方法是 params 访问器。

参数
  • bind -- 安 EngineConnection 从哪一个 Compiled 将被收购。此参数优先于此 ClauseElement 如果有绑定的引擎。

  • column_keys -- 用于insert和update语句,列名称的列表,应出现在编译语句的values子句中。如果 None ,将呈现目标表对象中的所有列。

  • dialect -- A Dialect 实例,其中 Compiled 将被收购。此参数优先于 bind 还有这个论点 ClauseElement 如果有绑定的引擎。

  • inline -- 用于insert语句,对于不支持对新生成的主键列进行内联检索的方言,将强制用于创建新主键值的表达式在insert语句的value s子句中进行内联呈现。这通常指序列执行,但也可能指与主键关联的任何服务器端默认生成函数。 Column .

  • compile_kwargs -- 在所有“访问”方法中传递给编译器的附加参数的可选字典。例如,这允许将任何自定义标志传递给自定义编译构造。它还用于通过 literal_binds 通过::从sqlachemy.sql导入表、列,选择t=table('t',column('x'))s=select( [t] .where(t.c.x==5)print s.compile(compile“literal_binds”:true)。添加的版本:0.9.0

cte(name=None, recursive=False)

继承 cte() 方法 HasCTE

返回一个新的 CTE 或公用表表达式实例。

公共表表达式是一种SQL标准,通过该标准,select语句可以使用名为“with”的子句,利用随主语句一起指定的辅助语句。还可以使用与union相关的特殊语义来允许“递归”查询,其中select语句可以根据以前选择的行集进行绘制。

CTE还可以应用于某些数据库上的DML构造更新、插入和删除,既可以作为与返回结合时CTE行的源,也可以作为CTE行的使用者。

SQLAlchemy检测 CTE 对象,其处理方式与 Alias 对象,作为要传递到语句的FROM子句以及语句顶部的WITH子句的特殊元素。

在 1.1 版更改: 添加了对更新/插入/删除作为CTE的支持,将CTE添加到更新/插入/删除。

参数
  • name -- 为公用表表达式指定的名称。喜欢 _FromClause.alias() ,名称可以保留为 None 在这种情况下,查询编译时将使用匿名符号。

  • recursive -- 如果 True 将渲染 WITH RECURSIVE . 递归公用表表达式将与union all一起使用,以便从已选定的行派生行。

以下示例包括来自PostgreSQL文档http://www.postgresql.org/docs/current/static/queries-with.html的两个示例,以及其他示例。

示例1,非递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

orders = Table('orders', metadata,
    Column('region', String),
    Column('amount', Integer),
    Column('product', String),
    Column('quantity', Integer)
)

regional_sales = select([
                    orders.c.region,
                    func.sum(orders.c.amount).label('total_sales')
                ]).group_by(orders.c.region).cte("regional_sales")


top_regions = select([regional_sales.c.region]).\
        where(
            regional_sales.c.total_sales >
            select([
                func.sum(regional_sales.c.total_sales)/10
            ])
        ).cte("top_regions")

statement = select([
            orders.c.region,
            orders.c.product,
            func.sum(orders.c.quantity).label("product_units"),
            func.sum(orders.c.amount).label("product_sales")
    ]).where(orders.c.region.in_(
        select([top_regions.c.region])
    )).group_by(orders.c.region, orders.c.product)

result = conn.execute(statement).fetchall()

示例2,递归:

from sqlalchemy import (Table, Column, String, Integer,
                        MetaData, select, func)

metadata = MetaData()

parts = Table('parts', metadata,
    Column('part', String),
    Column('sub_part', String),
    Column('quantity', Integer),
)

included_parts = select([
                    parts.c.sub_part,
                    parts.c.part,
                    parts.c.quantity]).\
                    where(parts.c.part=='our part').\
                    cte(recursive=True)


incl_alias = included_parts.alias()
parts_alias = parts.alias()
included_parts = included_parts.union_all(
    select([
        parts_alias.c.sub_part,
        parts_alias.c.part,
        parts_alias.c.quantity
    ]).
        where(parts_alias.c.part==incl_alias.c.sub_part)
)

statement = select([
            included_parts.c.sub_part,
            func.sum(included_parts.c.quantity).
              label('total_quantity')
        ]).\
        group_by(included_parts.c.sub_part)

result = conn.execute(statement).fetchall()

示例3,使用update和insert with ctes的upsert::

from datetime import date
from sqlalchemy import (MetaData, Table, Column, Integer,
                        Date, select, literal, and_, exists)

metadata = MetaData()

visitors = Table('visitors', metadata,
    Column('product_id', Integer, primary_key=True),
    Column('date', Date, primary_key=True),
    Column('count', Integer),
)

# add 5 visitors for the product_id == 1
product_id = 1
day = date.today()
count = 5

update_cte = (
    visitors.update()
    .where(and_(visitors.c.product_id == product_id,
                visitors.c.date == day))
    .values(count=visitors.c.count + count)
    .returning(literal(1))
    .cte('update_cte')
)

upsert = visitors.insert().from_select(
    [visitors.c.product_id, visitors.c.date, visitors.c.count],
    select([literal(product_id), literal(day), literal(count)])
        .where(~exists(update_cte.select()))
)

connection.execute(upsert)

参见

orm.query.Query.cte() -ORM版本 HasCTE.cte() .

dialect_kwargs

指定为此构造的方言特定选项的关键字参数集合。

这些论据以原版呈现在这里。 <dialect>_<kwarg> 格式。只包括实际传递的参数;与 DialectKWArgs.dialect_options 集合,其中包含此方言已知的所有选项,包括默认值。

集合也是可写的;接受窗体的键 <dialect>_<kwarg> 值将组合到选项列表中。

0.9.2 新版功能.

在 0.9.4 版更改: 这个 DialectKWArgs.dialect_kwargs 集合现在可写。

参见

DialectKWArgs.dialect_options -嵌套字典窗体

dialect_options

指定为此构造的方言特定选项的关键字参数集合。

这是一个两级嵌套注册表,键控为 <dialect_name><argument_name> . 例如, postgresql_where 参数可定位为:

arg = my_object.dialect_options['postgresql']['where']

0.9.2 新版功能.

参见

DialectKWArgs.dialect_kwargs -平字典形式

execute(*multiparams, **params)

继承 execute() 方法 Executable

编译并执行此 Executable .

execution_options(**kw)

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

可以对每个语句或每个语句设置执行选项。 Connection 基础。另外, Engine 和ORM Query 对象提供对执行选项的访问,这些执行选项反过来在连接时进行配置。

这个 execution_options() 方法是生成的。返回此语句的新实例,其中包含以下选项:

statement = select([table.c.x, table.c.y])
statement = statement.execution_options(autocommit=True)

请注意,只有可能的执行选项的一个子集可以应用于语句-这些选项包括“autocommit”和“stream_results”,但不包括“isolation_level”或“compiled_cache”。见 Connection.execution_options() 完整的选项列表。

get_children(**kwargs)

返回此的直接子元素 ClauseElement .

用于访问遍历。

* *Kwargs可能包含更改返回的集合的标志,例如返回项的子集以减少更大的遍历,或从不同上下文返回子项(例如架构级集合而不是子句级)。

get_execution_options()

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

1.3 新版功能.

kwargs

继承 kwargs 属性 DialectKWArgs

同义词 DialectKWArgs.dialect_kwargs .

params(*arg, **kw)

设置语句的参数。

此方法引发 NotImplementedError 在基类上,并被重写 ValuesBase 提供update和insert的set/values子句。

prefix_with(*expr, **kw)

继承 prefix_with() 方法 HasPrefixes

在语句关键字后添加一个或多个表达式,即select、insert、update或delete。生成的。

这用于支持后端特定的前缀关键字,如mysql提供的前缀关键字。

例如。::

stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")

可以通过多次调用指定多个前缀 prefix_with() .

参数
  • *expr -- 文本或 ClauseElement 在插入、更新或删除关键字后呈现的构造。…警告:: HasPrefixes.prefix_with.*expr 参数 HasPrefixes.prefix_with() 可以作为python字符串参数传递,该参数将被视为 可信SQL文本 并按规定呈现。 不要将不受信任的输入传递给此参数 .

  • **kw -- 只接受一个关键字“dialect”。这是一个可选的字符串方言名称,它将此前缀的呈现限制为仅显示该方言。

returning(*cols)

添加 RETURNING 或与此声明等效的子句。

例如。::

stmt = table.update().\
          where(table.c.data == 'value').\
          values(status='X').\
          returning(table.c.server_flag,
                    table.c.updated_timestamp)

for server_flag, updated_timestamp in connection.execute(stmt):
    print(server_flag, updated_timestamp)

列表达式的给定集合应派生自作为插入、更新或删除目标的表。同时 Column 对象是典型的,元素也可以是表达式:

stmt = table.insert().returning(
    (table.c.first_name + " " + table.c.last_name).
    label('fullname'))

编译后,将在语句中呈现返回子句或等效数据库。对于插入和更新,这些值是新插入/更新的值。对于“删除”,值是已删除的行的值。

执行后,将返回的列的值通过结果集可用,并且可以使用 ResultProxy.fetchone() 类似的。对于本机不支持返回值(即cx_oracle)的dbapis,sqlAlchemy将在结果级别近似此行为,以便提供合理数量的行为中立性。

请注意,并非所有数据库/dbapis都支持返回。对于那些不支持的后端,在编译和/或执行时会引发异常。对于那些支持它的人来说,后端的功能差异很大,包括对executeMany()和其他返回多行的语句的限制。请阅读正在使用的数据库的文档说明,以确定返回的可用性。

参见

ValuesBase.return_defaults() -为有效获取服务器端默认值和触发器而量身定制的一种替代方法,用于单行插入或更新。

scalar(*multiparams, **params)

继承 scalar() 方法 Executable

编译并执行此 Executable ,返回结果的标量表示。

self_group(against=None)

继承 self_group() 方法 ClauseElement

对此应用“分组” ClauseElement .

此方法被子类重写以返回“grouping”构造,即括号。尤其是“binary”表达式使用它在放入更大的表达式时提供围绕其自身的分组,以及 select() 当放入另一个的FROM子句时构造 select() . (请注意,通常应使用 Select.alias() 方法,因为许多平台都需要命名嵌套的select语句)。

当表达式组合在一起时,应用 self_group() 是自动的-最终用户代码不需要直接使用这个方法。请注意,sqlachemy的子句构造将运算符优先考虑在内,因此可能不需要括号,例如,在类似这样的表达式中 x OR (y AND z) -优先于或。

底座 self_group() 方法 ClauseElement 只需返回自我。

unique_params(*optionaldict, **kwargs)

返回副本 bindparam() 元素被替换。

功能与 params() ,除了添加 unique=True 以影响绑定参数,以便可以使用多个语句。

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

在此INSERT/UPDATE/DELETE语句中添加单个表的表提示。

注解

UpdateBase.with_hint() 当前仅适用于Microsoft SQL Server。对于MySQL插入/更新/删除提示,请使用 UpdateBase.prefix_with() .

提示文本呈现在正在使用的数据库后端的适当位置,相对于 Table 这是本声明的主题,或者是给定的主题 Table 作为传递 selectable 争论。

这个 dialect_name 选项将把特定提示的呈现限制到特定的后端。例如,要添加仅对SQL Server有效的提示,请执行以下操作:

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")
参数
  • text -- 提示的文本。

  • selectable -- 可选择的 Table 它将更新或删除中的FROM子句的元素指定为提示的主题-仅适用于某些后端。

  • dialect_name -- 默认为 * 如果指定为特定方言的名称,则仅在使用该方言时应用这些提示。

class sqlalchemy.sql.expression.ValuesBase(table, values, prefixes)

基地: sqlalchemy.sql.expression.UpdateBase

为…提供支持 ValuesBase.values() 插入和更新构造。

return_defaults(*cols)

利用一个 RETURNING 用于获取服务器端表达式和默认值的子句。

例如。::

stmt = table.insert().values(data='newdata').return_defaults()

result = connection.execute(stmt)

server_created_at = result.returned_defaults['created_at']

当用于支持返回的后端时,由SQL表达式或服务器端默认值生成的所有列值都将添加到任何现有的返回子句中,前提是 UpdateBase.returning() 不能同时使用。然后,列值将在结果中使用 ResultProxy.returned_defaults 作为字典的访问器,引用键入到 Column 对象及其 .key .

这种方法不同于 UpdateBase.returning() 以这些方式:

  1. ValuesBase.return_defaults() 仅用于与一行完全匹配的insert或update语句。一般意义上的返回构造支持多行用于多行更新或删除语句,或用于返回多行的插入的特殊情况(例如,insert from select、multi-values子句)。 ValuesBase.return_defaults() 仅用于“ORM样式”单行插入/更新语句。语句返回的行在 ValuesBase.return_defaults() 使用。相比之下, UpdateBase.returning() 使返回的结果集保持原样,包含任意数量的行的集合。

  2. 它与提取自动生成的主键值(也称为“隐式返回”)的现有逻辑兼容。支持返回的后端将自动利用返回来获取新生成的主键的值;而 UpdateBase.returning() 方法规避了这种行为, ValuesBase.return_defaults() 保持原样。

  3. 它可以针对任何后端调用。不支持返回的后端将跳过功能的使用,而不是引发异常。的返回值 ResultProxy.returned_defaultsNone

ValuesBase.return_defaults() 被ORM用来为 eager_defaults 特点 mapper() .

参数

cols -- 列键名称的可选列表或 Column 对象。如果省略,则服务器上计算的所有列表达式都将添加到返回列表中。

0.9.0 新版功能.

values(*args, **kwargs)

为insert语句指定一个fixed values子句,或为update指定set子句。

请注意 InsertUpdate 根据传递给的参数,构造支持值和/或set子句的每次执行时格式设置。 Connection.execute() . 然而, ValuesBase.values() 方法可用于“修复”语句中的一组特定参数。

多次调用 ValuesBase.values() 将生成一个新的构造,每个构造都修改了参数列表,以包含发送的新参数。在单个参数字典的典型情况下,新传递的键将替换前面构造中的相同键。在基于列表的“多个值”构造的情况下,每个新的值列表都会扩展到现有的值列表中。

参数
  • **kwargs -- 表示字符串键的键值对 Column 映射到要呈现到values或set子句中的值:users.insert().values(name=“some name”)users.update().where(users.c.id==5).values(name=“some name”)

  • *args -- 作为传递键/值参数的替代方法,可以将字典、元组或字典或元组列表作为单个位置参数传递,以形成语句的values或set子句。接受的表单根据是否 InsertUpdate 构建。对于任何一个 InsertUpdate 构造时,可以传递一个字典,其工作方式与Kwargs Form::Users.Insert().Values(“name”:“some name”)Users.Update().Values(“name”:“some new name”)相同,但更常见的是针对 Insert 构造时,还接受包含表中每个列的条目的元组::users.insert().values((5,“some name”))和 Insert construct还支持传递字典列表或全表元组,服务器上的这些列表将呈现“多个值”较不常见的SQL语法-后端支持此语法,如sqlite、postgresql、mysql,但不一定是其他::users.insert()。values( [“name”:“some name”,“name”:“some other name”,“name”:“yet another name”,] )上面的表单将呈现类似于::insert into users(name)values的multiple values语句。 (:name_1), (:name_2), (:name_3) It is essential to note that passing multiple values is NOT the same as using traditional executemany() form. The above syntax is a special syntax not typically used. To emit an INSERT statement against multiple rows, the normal method is to pass a multiple values list to the Connection.execute() 方法,它由所有数据库后端支持,通常对于大量参数更有效。…参阅: 执行多个语句 -介绍插入和其他语句的多参数集调用的传统核心方法。…versionChanged::1.0.0使用多值子句的插入,即使是长度为1的列表,也意味着 Insert.inline 标志设置为true,表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行,因此 ResultProxy.inserted_primary_key 访问器不适用。…versionChanged::1.0.0多值插入现在支持具有Python端默认值和可调用文件的列,方式与“ExecuteMany”调用方式相同;可调用文件对每一行进行调用。见 当使用多值插入时,为每行单独调用python端默认值 其他细节。这个 Update 构造支持一个特殊的表单,该表单是2个元组的列表,在提供时,必须与 preserve_parameter_order 参数。此窗体使update语句使用给定的参数顺序呈现set子句 Update.values() ,而不是 Table . …versionAdded::1.0.10-通过 preserve_parameter_order 标志。…参阅: 参数顺序更新 -完整的示例 preserve_parameter_order 标志

参见

插入、更新和删除 -SQL表达式语言教程

insert() -产生一个 INSERT 陈述

update() -产生一个 UPDATE 陈述