DML基础构造函数¶

顶级的“插入”、“更新”、“删除”构造函数。

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

构建 Delete 对象。

例如。：：

from sqlalchemy import delete

stmt = (
    delete(user_table).
    where(user_table.c.id == 5)
)

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

参见

插入、更新和删除 - in the 1.x tutorial

使用核心更新和删除行 - in the SQLAlchemy 1.4/2.0教程

参数

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

• whereclause¶ -- 描述的可选SQL表达式 WHERE 的条件 DELETE 语句；相当于使用更现代的 Delete.where() 方法来指定 WHERE 子句。。已弃用：：1.4 delete.whereclause 参数将在SQLAlchemy 2.0中删除。请参考 Delete.where() 方法。

参见

删除 -SQL表达式教程

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

构建一个 Insert 对象。

例如。：：

from sqlalchemy import insert

stmt = (
    insert(user_table).
    values(name='username', fullname='Full Username')
)

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

参见

插入表达式 - in the 1.x tutorial

插入带核心的行 - in the SQLAlchemy 1.4/2.0教程

参数

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

• values¶ -- 要插入的值集合；请参见 Insert.values() 有关此处允许格式的说明。完全可以省略；a Insert 构造还将根据传递给的参数在执行时动态地呈现values子句。 Connection.execute() . .. 已弃用：：1.4 insert.values 参数将在SQLAlchemy 2.0中删除。请参考 Insert.values() 方法。

• inline¶ -- 如果为True，则不会尝试检索要在语句中提供的SQL生成的默认值；特别是，这允许SQL表达式在语句中以“内联”方式呈现，而无需预先执行它们；对于支持“返回”的后端，这将关闭语句的“隐式返回”功能。。已弃用：：1.4 insert.inline 参数将在SQLAlchemy 2.0中删除。请使用 Insert.inline() 方法。

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

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

• 文字数据值（即字符串、数字等）；

• 列对象；

• 选择语句。

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

参见

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

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

function 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(user_table).
    where(user_table.c.id == 5).
    values(name='user #5')
)

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

参见

插入、更新和删除 - in the 1.x tutorial

使用核心更新和删除行 - in the SQLAlchemy 1.4/2.0教程

参数

• table¶ -- A Table 表示要更新的数据库表的对象。

• whereclause¶ -- 描述的可选SQL表达式 WHERE 的条件 UPDATE 语句；相当于使用更现代的 Update.where() 方法来指定 WHERE 子句。。已弃用：：1.4 update.whereclause 参数将在SQLAlchemy 2.0中删除。请参考 Update.where() 方法。

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

• inline¶ -- 如果为true，则SQL默认值出现在 Column 对象通过 default 关键字将被“inline”编译到语句中，而不是预先执行。这意味着它们的值在从返回的字典中不可用。 CursorResult.last_updated_params() . .. 已弃用：：1.4 update.inline 参数将在SQLAlchemy 2.0中删除。请使用 Update.inline() 方法。

• preserve_parameter_order¶ -- 如果为true，则update语句将接收参数 only 通过 Update.values() 方法，并且它们必须作为python传递 list 2元组的。呈现的UPDATE语句将为保持此顺序的每个引用列发出SET子句。。已弃用：：1.4 update.preserve_parameter_order 参数将在SQLAlchemy 2.0中删除。使用 Update.ordered_values() 方法的元组列表。。版本添加：：1.0.10。。另请参见： 参数顺序更新 -说明了 Update.ordered_values() 方法。

如果两者 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).\
                scalar_subquery()
    )

参见

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

DML类文档构造函数¶

中列出的构造函数的类文档 DML基础构造函数 .

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

表示删除构造。

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

类签名

class sqlalchemy.sql.expression.Delete (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.UpdateBase)

method sqlalchemy.sql.expression.Delete.where(*whereclause)¶

inherited from the DMLWhereBase.where() method of DMLWhereBase

返回一个新的构造，其中给定的表达式添加到其WHERE子句中，并通过AND（如果有）连接到现有子句。

两个 Update.where() 和 Delete.where() 支持多种表格形式，包括特定于数据库的表格 UPDATE...FROM 以及 DELETE..USING . 对于不支持多个表的后端，使用多个表的与后端无关的方法是使用相关的子查询。有关示例，请参见下面的链接教程部分。

参见

1.x教程示例

相关更新

多个表更新

多个表删除

2.0教程示例

相关更新

UPDATE..FROM

多个表删除

method sqlalchemy.sql.expression.Delete.returning(*cols)¶

inherited from the UpdateBase.returning() method of UpdateBase

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

例如。：

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

可以多次调用该方法以将新条目添加到要返回的表达式列表中。

1.4.0b2 新版功能: 可以多次调用该方法以将新条目添加到要返回的表达式列表中。

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

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

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

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

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

参见

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

INSERT...RETURNING - in the SQLAlchemy 1.4/2.0教程

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

构建新的 Delete 对象。

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

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

表示插入构造。

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

类签名

class sqlalchemy.sql.expression.Insert (sqlalchemy.sql.expression.ValuesBase)

method sqlalchemy.sql.expression.Insert.values(*args, **kwargs)¶

inherited from the ValuesBase.values() method of ValuesBase

为INSERT语句指定固定值子句，或为UPDATE指定SET子句。

请注意 Insert 和 Update 根据传递给的参数，构造支持值和/或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子句。接受的表单根据是否 Insert 或 Update 构建。对于任何一个 Insert 或 Update 构造时，可以传递一个字典，其工作方式与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，表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行，因此 CursorResult.inserted_primary_key 访问器不适用。…versionChanged:：1.0.0多值插入现在支持具有Python端默认值和可调用文件的列，方式与“ExecuteMany”调用方式相同；可调用文件对每一行进行调用。见 当使用多值插入时，为每行单独调用python端默认值 其他细节。UPDATE构造还支持按特定顺序呈现设置参数。有关此功能，请参阅 Update.ordered_values() 方法。。另请参见： Update.ordered_values()

method sqlalchemy.sql.expression.Insert.returning(*cols)¶

inherited from the UpdateBase.returning() method of UpdateBase

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

例如。：

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

可以多次调用该方法以将新条目添加到要返回的表达式列表中。

1.4.0b2 新版功能: 可以多次调用该方法以将新条目添加到要返回的表达式列表中。

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

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

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

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

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

参见

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

INSERT...RETURNING - in the SQLAlchemy 1.4/2.0教程

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

构建新的 Insert 对象。

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

method sqlalchemy.sql.expression.Insert.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，表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行，因此 CursorResult.inserted_primary_key 访问器不适用。

method sqlalchemy.sql.expression.Insert.inline()¶

做这个 Insert 构建“内联”。

设置后，将不会尝试检索要在语句中提供的SQL生成的默认值；特别是，这允许SQL表达式在语句中“内联”呈现，而无需预先执行它们；对于支持“返回”的后端，这将关闭语句的“隐式返回”功能。

在 1.4 版更改: 这个 Insert.inline 参数现在被 Insert.inline() 方法。

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

表示更新构造。

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

类签名

class sqlalchemy.sql.expression.Update (sqlalchemy.sql.expression.DMLWhereBase, sqlalchemy.sql.expression.ValuesBase)

method sqlalchemy.sql.expression.Update.returning(*cols)¶

inherited from the UpdateBase.returning() method of UpdateBase

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

例如。：

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

可以多次调用该方法以将新条目添加到要返回的表达式列表中。

1.4.0b2 新版功能: 可以多次调用该方法以将新条目添加到要返回的表达式列表中。

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

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

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

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

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

参见

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

INSERT...RETURNING - in the SQLAlchemy 1.4/2.0教程

method sqlalchemy.sql.expression.Update.where(*whereclause)¶

inherited from the DMLWhereBase.where() method of DMLWhereBase

返回一个新的构造，其中给定的表达式添加到其WHERE子句中，并通过AND（如果有）连接到现有子句。

两个 Update.where() 和 Delete.where() 支持多种表格形式，包括特定于数据库的表格 UPDATE...FROM 以及 DELETE..USING . 对于不支持多个表的后端，使用多个表的与后端无关的方法是使用相关的子查询。有关示例，请参见下面的链接教程部分。

参见

1.x教程示例

相关更新

多个表更新

多个表删除

2.0教程示例

相关更新

UPDATE..FROM

多个表删除

method sqlalchemy.sql.expression.Update.values(*args, **kwargs)¶

inherited from the ValuesBase.values() method of ValuesBase

为INSERT语句指定固定值子句，或为UPDATE指定SET子句。

请注意 Insert 和 Update 根据传递给的参数，构造支持值和/或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子句。接受的表单根据是否 Insert 或 Update 构建。对于任何一个 Insert 或 Update 构造时，可以传递一个字典，其工作方式与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，表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行，因此 CursorResult.inserted_primary_key 访问器不适用。…versionChanged:：1.0.0多值插入现在支持具有Python端默认值和可调用文件的列，方式与“ExecuteMany”调用方式相同；可调用文件对每一行进行调用。见 当使用多值插入时，为每行单独调用python端默认值 其他细节。UPDATE构造还支持按特定顺序呈现设置参数。有关此功能，请参阅 Update.ordered_values() 方法。。另请参见： Update.ordered_values()

method sqlalchemy.sql.expression.Update.__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函数；请参见 sqlalchemy.sql.expression.update() 完整的用法和参数描述。

method sqlalchemy.sql.expression.Update.inline()¶

做这个 Update 构建“内联”。

设置后，SQL默认值显示在 Column 对象通过 default 关键字将被“inline”编译到语句中，而不是预先执行。这意味着它们的值在从返回的字典中不可用。 CursorResult.last_updated_params() .

在 1.4 版更改: 这个 update.inline 参数现在被 Update.inline() 方法。

method sqlalchemy.sql.expression.Update.ordered_values(*args)¶

使用显式参数顺序指定此UPDATE语句的VALUES子句，该顺序将在生成的UPDATE语句的SET子句中维护。

例如。：：

stmt = table.update().ordered_values(
    ("name", "ed"), ("ident": "foo")
)

参见

参数顺序更新 -完整的示例 Update.ordered_values() 方法。

在 1.4 版更改: 这个 Update.ordered_values() 方法取代 update.preserve_parameter_order 参数，它将在SQLAlchemy 2.0中删除。

class sqlalchemy.sql.expression.UpdateBase¶

为…奠定基础 INSERT ， UPDATE 和 DELETE 声明。

类签名

class sqlalchemy.sql.expression.UpdateBase (sqlalchemy.sql.roles.DMLRole, sqlalchemy.sql.expression.HasCTE, sqlalchemy.sql.expression.HasCompileState, sqlalchemy.sql.base.DialectKWArgs, sqlalchemy.sql.expression.HasPrefixes, sqlalchemy.sql.expression.ReturnsRows, sqlalchemy.sql.expression.Executable, sqlalchemy.sql.expression.ClauseElement)

attribute sqlalchemy.sql.expression.UpdateBase.bind¶

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

attribute sqlalchemy.sql.expression.UpdateBase.exported_columns¶

将返回的列作为此语句的列集合返回。

1.4 新版功能.

method sqlalchemy.sql.expression.UpdateBase.params(*arg, **kw)¶

设置语句的参数。

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

method sqlalchemy.sql.expression.UpdateBase.returning(*cols)¶

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

例如。：

>>> stmt = (
...     table.update()
...     .where(table.c.data == "value")
...     .values(status="X")
...     .returning(table.c.server_flag, table.c.updated_timestamp)
... )
>>> print(stmt)
UPDATE some_table SET status=:status
WHERE some_table.data = :data_1
RETURNING some_table.server_flag, some_table.updated_timestamp

可以多次调用该方法以将新条目添加到要返回的表达式列表中。

1.4.0b2 新版功能: 可以多次调用该方法以将新条目添加到要返回的表达式列表中。

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

>>> stmt = table.insert().returning(
...     (table.c.first_name + " " + table.c.last_name).label("fullname")
... )
>>> print(stmt)
INSERT INTO some_table (first_name, last_name)
VALUES (:first_name, :last_name)
RETURNING some_table.first_name || :first_name_1 || some_table.last_name AS fullname

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

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

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

参见

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

INSERT...RETURNING - in the SQLAlchemy 1.4/2.0教程

method sqlalchemy.sql.expression.UpdateBase.with_dialect_options(**opt)¶

将方言选项添加到此插入/更新/删除对象。

例如。：：

upd = table.update().dialect_options(mysql_limit=10)

method sqlalchemy.sql.expression.UpdateBase.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)¶

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

类签名

class sqlalchemy.sql.expression.ValuesBase (sqlalchemy.sql.expression.UpdateBase)

method sqlalchemy.sql.expression.ValuesBase.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() 不能同时使用。然后，列值将在结果中使用 CursorResult.returned_defaults 作为字典的访问器，引用键入到 Column 对象及其 .key .

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

1. ValuesBase.return_defaults() 只用于与每个参数集只匹配一行的INSERT或UPDATE语句一起使用。而一般意义上的RETURNING构造支持多行UPDATE或DELETE语句，或返回多行的INSERT的特殊情况（例如INSERT from SELECT、multi-VALUES子句）， ValuesBase.return_defaults() 仅用于“ORM样式”单行插入/更新语句。语句返回的行在 ValuesBase.return_defaults() 使用。相比之下， UpdateBase.returning() 使返回的结果集保持原样，包含任意数量的行的集合。

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

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

4. 如果后端数据库驱动程序支持 insert_executemany_returning 特性，目前包括PostgreSQL和psycopg2。使用executemany时 CursorResult.returned_defaults_rows 和 CursorResult.inserted_primary_key_rows 访问器将返回插入的默认值和主键。

   1.4 新版功能.

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

参数

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

0.9.0 新版功能.

参见

UpdateBase.returning()

CursorResult.returned_defaults

CursorResult.returned_defaults_rows

CursorResult.inserted_primary_key

CursorResult.inserted_primary_key_rows

method sqlalchemy.sql.expression.ValuesBase.values(*args, **kwargs)¶

为INSERT语句指定固定值子句，或为UPDATE指定SET子句。

请注意 Insert 和 Update 根据传递给的参数，构造支持值和/或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子句。接受的表单根据是否 Insert 或 Update 构建。对于任何一个 Insert 或 Update 构造时，可以传递一个字典，其工作方式与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，表示该语句不会尝试获取“最后插入的主键”或其他默认值。语句处理任意数量的行，因此 CursorResult.inserted_primary_key 访问器不适用。…versionChanged:：1.0.0多值插入现在支持具有Python端默认值和可调用文件的列，方式与“ExecuteMany”调用方式相同；可调用文件对每一行进行调用。见 当使用多值插入时，为每行单独调用python端默认值 其他细节。UPDATE构造还支持按特定顺序呈现设置参数。有关此功能，请参阅 Update.ordered_values() 方法。。另请参见： Update.ordered_values()