插入、更新、删除¶

INSERT、UPDATE 和 DELETE 语句建立在以 UpdateBase 开头的层次结构上。插入和更新 构造构建在中间 ValuesBase 之上。

DML 基础构造函数¶

顶级 “INSERT”、“UPDATE”、“DELETE” 构造函数。

对象名称	描述
删除（表）	构造 `Delete` 对象。
insert（表）	构造一个 `Insert` 对象。
update（表）	构造 `Update` 对象。

函数 sqlalchemy.sql.expression 中。delete（table： _DMLTableArgument）→ 删除¶

构造 Delete 对象。

例如：

from sqlalchemy import delete

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

类似的功能可通过 TableClause.delete（） 方法 表。

参数: table¶– 要从中删除行的表。

另请参阅

使用 UPDATE 和 DELETE 语句 - 在 SQLAlchemy Unified 教程中

函数 sqlalchemy.sql.expression 中。insert（table： _DMLTableArgument）→ 插入¶

构造一个 Insert 对象。

例如：

from sqlalchemy import insert

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

类似的功能可通过 TableClause.insert（） 方法 表。

另请参阅

使用 INSERT 语句 - 在 SQLAlchemy Unified 教程中

参数

table¶– TableClause 这是插入。
values¶ – 要插入的值的集合;看 插入.值（） 有关允许的格式的说明，请点击此处。可以完全省略;Insert 构造还将在执行时根据传递给 Connection.execute（） 的参数动态呈现 VALUES 子句。
inline¶——如果为 True，则不会尝试检索要在语句中提供的 SQL 生成的默认值;特别是，这允许 SQL 表达式在语句中“内联”呈现，而无需事先预执行它们;对于支持 “returning” 的后端，这将关闭语句的 “implicit returning” 功能。

如果 insert.values 和编译时绑定参数都存在，则编译时绑定参数将基于每个键覆盖 insert.values 中指定的信息。

Insert.values 中的键可以是 列对象或其字符串标识符。每个键可以引用以下项之一：

文本数据值（即字符串、数字等）;
一个 Column 对象;
一个 SELECT 语句。

如果指定了引用此 INSERT 语句的 table 中，该语句将与 INSERT 语句相关联。

另请参阅

使用 INSERT 语句 - 在 SQLAlchemy Unified 教程中

函数 sqlalchemy.sql.expression 中。update（table： _DMLTableArgument）→ 更新¶

构造 Update 对象。

例如：

from sqlalchemy import update

stmt = (
    update(user_table).where(user_table.c.id == 5).values(name="user #5")
)

类似的功能可通过 TableClause.update（） 方法 表。

参数: table¶– 一个 Table 表示数据库的对象要更新的表。

另请参阅

使用 UPDATE 和 DELETE 语句 - 在 SQLAlchemy Unified 教程中

DML 类文档构造函数¶

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

对象名称	描述
删除	表示 DELETE 构造。
插入	表示 INSERT 构造。
更新	表示 Update 构造。
更新基地	构成 `INSERT、UPDATE` 和 `DELETE` 语句的基础。
值基础	为 INSERT 和 UPDATE 构造提供对 `ValuesBase.values（）` 的支持。

类 sqlalchemy.sql.expression 中。删除¶

表示 DELETE 构造。

Delete 对象是使用 delete（） 函数。

成员

其中（）， returning（）

类签名

类 sqlalchemy.sql.expression.Delete （ sqlalchemy.sql.expression.DMLWhereBase ， sqlalchemy.sql.expression.UpdateBase ）

method sqlalchemy.sql.expression.Delete. where（*whereclause： _ColumnExpressionArgument[bool]）→ Self¶

继承自DMLWhereBase 的 DMLWhereBase.where（） 方法

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

Update.where（） 和 Delete.where（） 支持多表表单，包括特定于数据库的表单 更新。。。FROM 以及 DELETE..使用。对于不支持多表的后端，使用多个表的后端不可知的方法是使用相关子查询。有关示例，请参阅下面的链接教程部分。

另请参阅

相关更新

更新。。从

多个表删除

method sqlalchemy.sql.expression.Delete. returning（*cols： _ColumnsClauseArgument[Any]， sort_by_parameter_order： bool = False， **_UpdateBase__kw： Any）→ UpdateBase¶

继承自UpdateBase 的 UpdateBase.returning（） 方法

向此语句添加 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 版本中的新功能：可以多次调用该方法，以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应派生自 table 的 SET 作为 INSERT、UPDATE 或 DELETE 的目标。而 列对象是典型的，元素也可以是表达式：

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

编译时，将在语句中呈现 RETURNING 子句或数据库等效项。对于 INSERT 和 UPDATE，值是新插入/更新的值。对于 DELETE，值是已删除的行的值。

执行时，将生成要返回的列的值可通过结果集进行迭代，并且可以使用 CursorResult.fetchone（） 等。对于本身不支持返回值（即 cx_oracle）的 DBAPI，SQLAlchemy 将在结果级别近似此行为，以便提供合理数量的行为中立性。

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

参数

*cols¶ – 要返回的一系列列、SQL 表达式或整个表实体。
sort_by_parameter_order¶ –

对于针对多个参数集执行的批处理 INSERT，组织 RETURNING 的结果，以便返回的行与传入的参数集的顺序相对应。这仅适用于 executemany 执行以支持方言，并且通常使用 insertmanyValues 功能。

在 2.0.10 版本加入.

另请参阅

将 RETURNING 行与参数集相关联 - 批量 INSERT 的 RETURNING 行排序的背景（核心级别讨论）

将 RETURNING 记录与输入数据顺序相关联 - 与 ORM 批量 INSERT 语句一起使用的示例（ORM 级别讨论）

另请参阅

UpdateBase.return_defaults（） - 一种为高效获取服务器端默认值和单行 INSERT 或 UPDATE 触发器而定制的替代方法。

插入。。。RETURNING - 在 SQLAlchemy Unified Tutorial 中

类 sqlalchemy.sql.expression 中。插入¶

表示 INSERT 构造。

Insert 对象是使用 insert（） 函数。

成员

values（）、returning（）、from_select（）、inline（），选择

类签名

类 sqlalchemy.sql.expression.Insert （ sqlalchemy.sql.expression.ValuesBase ）

method sqlalchemy.sql.expression.Insert. values（*args：_DMLColumnKeyMapping[Any]Sequence[Any]， **kwargs： Any）→ Self¶

继承自ValuesBase 的 ValuesBase.values（） 方法

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

请注意，Insert 和 更新 构造支持 VALUES 和/或 SET 子句的每次执行时间格式，基于传递给 Connection.execute（） 的参数。但是，ValuesBase.values（） 方法可用于将一组特定的参数“修复”到语句中。

多次调用 ValuesBase.values（） 将生成一个新的结构，每次调用都修改了参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换上一个构造中的相同键。在基于列表的 “multiple 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 或 更新 构造，则可以传递单个字典，其工作原理与 kwargs 形式的：
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
也适用于任一形式，但更常见的是 Insert 构造，则还接受包含表中每一列的条目的 Tuples：
```
users.insert().values((5, "some name"))
```
Insert 结构还支持传递字典或全表元组列表，这在服务器上将呈现不太常见的 SQL 语法“多个值” - 此语法在 SQLite、PostgreSQL、MySQL 等后端受支持，但不一定支持其他语法：
```
users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)
```
上述表单将呈现类似于以下内容的多个 VALUES 语句：
```
INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)
```
请务必注意，传递多个值是与使用传统的 executemany（）形式不同。上述语法是通常不使用的特殊语法。要发出 INSERT 语句，通常的方法是要将多个值列表传递给 Connection.execute（） 方法，所有数据库后端都支持该方法，并且通常对于大量参数更有效。

另请参阅

发送多个参数 - 介绍 INSERT 和其他语句的多参数集调用的传统 Core 方法。

UPDATE 构造还支持渲染 SET 参数按特定顺序。有关此功能，请参阅 Update.ordered_values（） 方法。

另请参阅

Update.ordered_values（）

method sqlalchemy.sql.expression.Insert. returning（*cols： _ColumnsClauseArgument[Any]， sort_by_parameter_order： bool = False， **_UpdateBase__kw： Any）→ UpdateBase¶

继承自UpdateBase 的 UpdateBase.returning（） 方法

向此语句添加 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 版本中的新功能：可以多次调用该方法，以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应派生自 table 的 SET 作为 INSERT、UPDATE 或 DELETE 的目标。而 列对象是典型的，元素也可以是表达式：

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

编译时，将在语句中呈现 RETURNING 子句或数据库等效项。对于 INSERT 和 UPDATE，值是新插入/更新的值。对于 DELETE，值是已删除的行的值。

执行时，将生成要返回的列的值可通过结果集进行迭代，并且可以使用 CursorResult.fetchone（） 等。对于本身不支持返回值（即 cx_oracle）的 DBAPI，SQLAlchemy 将在结果级别近似此行为，以便提供合理数量的行为中立性。

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

参数

*cols¶ – 要返回的一系列列、SQL 表达式或整个表实体。
sort_by_parameter_order¶ –

对于针对多个参数集执行的批处理 INSERT，组织 RETURNING 的结果，以便返回的行与传入的参数集的顺序相对应。这仅适用于 executemany 执行以支持方言，并且通常使用 insertmanyValues 功能。

在 2.0.10 版本加入.

另请参阅

将 RETURNING 行与参数集相关联 - 批量 INSERT 的 RETURNING 行排序的背景（核心级别讨论）

将 RETURNING 记录与输入数据顺序相关联 - 与 ORM 批量 INSERT 语句一起使用的示例（ORM 级别讨论）

另请参阅

UpdateBase.return_defaults（） - 一种为高效获取服务器端默认值和单行 INSERT 或 UPDATE 触发器而定制的替代方法。

插入。。。RETURNING - 在 SQLAlchemy Unified Tutorial 中

方法 sqlalchemy.sql.expression.Insert. from_select（names： Sequence[_DMLColumnArgument]， select： Selectable， include_defaults： bool = True）→ Self¶

返回一个表示 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¶ —— 字符串列名序列或 列 表示目标列的对象。
select¶ —— select（） 结构， From子句 或其他解析为 FromClause 等，例如 ORM Query 对象等。从此 FROM 子句返回的列的顺序应对应于作为 names 参数发送的列的顺序;虽然在传递给数据库之前没有检查这一点，但如果这些列列表不对应，数据库通常会引发异常。
include_defaults¶ –

如果为 True，则在名称列表中未另行指定的 Column 对象上指定的非服务器默认值和 SQL 表达式（如列 INSERT/UPDATE 默认值中所述）将呈现到 INSERT 和 SELECT 语句中，以便这些值也包含在要插入的数据中。

注意

使用 Python 可调用函数的 Python 端默认值将仅对整个语句调用一次，而不会每行。

method sqlalchemy.sql.expression.Insert. inline（）→ Self¶

使此 Insert 构造 “inline” 。

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

在 1.4 版本发生变更： Insert.inline 参数现在被 Insert.inline（） 方法取代。

attribute sqlalchemy.sql.expression.Insert. select：Select[Any]None = None¶: SELECT 语句 INSERT ..从选择

类 sqlalchemy.sql.expression 中。更新¶

表示 Update 构造。

Update 对象是使用 update（） 函数。

成员

returning（）、where（）、values（）、inline（）、ordered_values（）

类签名

类 sqlalchemy.sql.expression.Update （ sqlalchemy.sql.expression.DMLWhereBase ， sqlalchemy.sql.expression.ValuesBase ）

method sqlalchemy.sql.expression.Update. returning（*cols： _ColumnsClauseArgument[Any]， sort_by_parameter_order： bool = False， **_UpdateBase__kw： Any）→ UpdateBase¶

继承自UpdateBase 的 UpdateBase.returning（） 方法

向此语句添加 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 版本中的新功能：可以多次调用该方法，以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应派生自 table 的 SET 作为 INSERT、UPDATE 或 DELETE 的目标。而 列对象是典型的，元素也可以是表达式：

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

编译时，将在语句中呈现 RETURNING 子句或数据库等效项。对于 INSERT 和 UPDATE，值是新插入/更新的值。对于 DELETE，值是已删除的行的值。

执行时，将生成要返回的列的值可通过结果集进行迭代，并且可以使用 CursorResult.fetchone（） 等。对于本身不支持返回值（即 cx_oracle）的 DBAPI，SQLAlchemy 将在结果级别近似此行为，以便提供合理数量的行为中立性。

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

参数

*cols¶ – 要返回的一系列列、SQL 表达式或整个表实体。
sort_by_parameter_order¶ –

对于针对多个参数集执行的批处理 INSERT，组织 RETURNING 的结果，以便返回的行与传入的参数集的顺序相对应。这仅适用于 executemany 执行以支持方言，并且通常使用 insertmanyValues 功能。

在 2.0.10 版本加入.

另请参阅

将 RETURNING 行与参数集相关联 - 批量 INSERT 的 RETURNING 行排序的背景（核心级别讨论）

将 RETURNING 记录与输入数据顺序相关联 - 与 ORM 批量 INSERT 语句一起使用的示例（ORM 级别讨论）

另请参阅

UpdateBase.return_defaults（） - 一种为高效获取服务器端默认值和单行 INSERT 或 UPDATE 触发器而定制的替代方法。

插入。。。RETURNING - 在 SQLAlchemy Unified Tutorial 中

method sqlalchemy.sql.expression.Update. where（*whereclause： _ColumnExpressionArgument[bool]）→ Self¶

继承自DMLWhereBase 的 DMLWhereBase.where（） 方法

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

Update.where（） 和 Delete.where（） 支持多表表单，包括特定于数据库的表单 更新。。。FROM 以及 DELETE..使用。对于不支持多表的后端，使用多个表的后端不可知的方法是使用相关子查询。有关示例，请参阅下面的链接教程部分。

另请参阅

相关更新

更新。。从

多个表删除

method sqlalchemy.sql.expression.Update. values（*args：_DMLColumnKeyMapping[Any]Sequence[Any]， **kwargs： Any）→ Self¶

继承自ValuesBase 的 ValuesBase.values（） 方法

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

请注意，Insert 和 更新 构造支持 VALUES 和/或 SET 子句的每次执行时间格式，基于传递给 Connection.execute（） 的参数。但是，ValuesBase.values（） 方法可用于将一组特定的参数“修复”到语句中。

多次调用 ValuesBase.values（） 将生成一个新的结构，每次调用都修改了参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换上一个构造中的相同键。在基于列表的 “multiple 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 或 更新 构造，则可以传递单个字典，其工作原理与 kwargs 形式的：
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
也适用于任一形式，但更常见的是 Insert 构造，则还接受包含表中每一列的条目的 Tuples：
```
users.insert().values((5, "some name"))
```
Insert 结构还支持传递字典或全表元组列表，这在服务器上将呈现不太常见的 SQL 语法“多个值” - 此语法在 SQLite、PostgreSQL、MySQL 等后端受支持，但不一定支持其他语法：
```
users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)
```
上述表单将呈现类似于以下内容的多个 VALUES 语句：
```
INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)
```
请务必注意，传递多个值是与使用传统的 executemany（）形式不同。上述语法是通常不使用的特殊语法。要发出 INSERT 语句，通常的方法是要将多个值列表传递给 Connection.execute（） 方法，所有数据库后端都支持该方法，并且通常对于大量参数更有效。

另请参阅

发送多个参数 - 介绍 INSERT 和其他语句的多参数集调用的传统 Core 方法。

UPDATE 构造还支持渲染 SET 参数按特定顺序。有关此功能，请参阅 Update.ordered_values（） 方法。

另请参阅

Update.ordered_values（）

method sqlalchemy.sql.expression.Update. inline（）→ Self¶

将此 Update 构造设为 “inline” 。

设置后，SQL 默认值存在于 Column 上对象通过 default 关键字将 “inline” 编译到语句中，并且未预先执行。这意味着它们的值将不可用在 CursorResult.last_updated_params() 。

在 1.4 版本发生变更： update.inline 参数现在被 Update.inline（） 方法取代。

method sqlalchemy.sql.expression.Update. ordered_values（*args： Tuple[_DMLColumnArgument， Any]）→ Self¶

指定此 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 中删除。

类 sqlalchemy.sql.expression 中。UpdateBase（更新基地）¶

构成 INSERT、UPDATE 和 DELETE 语句的基础。

成员

entity_description、exported_columns、params（）、return_defaults（）、returning（）、returning_column_descriptions、with_dialect_options（）、with_hint（）

类签名

类 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.Generative sqlalchemy.sql.expression.ExecutableReturnsRows sqlalchemy.sql.expression.ClauseElement ）

属性 sqlalchemy.sql.expression.UpdateBase. entity_description¶

返回此 DML 构造所针对的表和/或实体的启用插件的描述。

此属性在使用 ORM 时通常很有用，因为会返回包含有关映射实体信息的扩展结构。检查启用 ORM 的 SELECT 和 DML 语句中的实体和列部分包含更多背景。

对于 Core 语句，此访问器返回的结构派生自 UpdateBase.table 属性，并引用正在插入、更新或删除的 Table：

>>> stmt = insert(user_table)
>>> stmt.entity_description
{
    "name": "user_table",
    "table": Table("user_table", ...)
}

在 1.4.33 版本加入.

另请参阅

UpdateBase.returning_column_descriptions

Select.column_descriptions - select（） 结构的实体信息

检查支持 ORM 的 SELECT 和 DML 语句中的实体和列 - ORM 背景

属性 sqlalchemy.sql.expression.UpdateBase. exported_columns¶: 返回 RETURNING 列作为此语句的列集合。

在 1.4 版本加入.

method sqlalchemy.sql.expression.UpdateBase. params（*arg： Any， **kw： Any）→ NoReturn¶

设置语句的参数。

此方法在基类上引发 NotImplementedError，并被 ValuesBase 重写以提供 UPDATE 和 INSERT 的 SET/VALUES 子句。

method sqlalchemy.sql.expression.UpdateBase. return_defaults（*cols： _DMLColumnArgument， supplemental_cols：Iterable[_DMLColumnArgument]None=None， sort_by_parameter_order： bool = False）→ 自身¶

使用 RETURNING 子句来获取服务器端表达式和默认值，仅用于支持后端。

深度炼金术

ORM 使用 UpdateBase.return_defaults（） 方法进行内部工作，以获取新生成的主键和服务器默认值，特别是提供 Mapper.eager_defaults 的底层实现 ORM 功能以及允许批量的 RETURNING 支持 ORM 插入。它的行为相当特殊并且并非真正用于一般用途。最终用户应该坚持使用 UpdateBase.returning（） 以便将 RETURNING 子句添加到它们的 INSERT、UPDATE 和 DELETE 语句中。

通常，单行 INSERT 语句会自动填充 CursorResult.inserted_primary_key 属性，该属性存储刚刚以 Row 对象形式插入的行的主键，其中列名称作为命名元组键（并且 Row._mapping 视图也已完全填充）。正在使用的方言选择要使用的策略来填充此数据;如果它是使用服务器端默认值和/或 SQL 表达式生成的，则特定于方言的方法（如 cursor.lastrowId）或 RETURNING 通常用于获取新的主键值。

但是，当通过调用 UpdateBase.return_defaults（） 执行语句之前，其他行为仅针对支持 RETURNING 的后端和维护 Table.implicit_returning 参数设置为其默认值 没错。在这些情况下，当返回 CursorResult 时从语句的执行中，不仅会 CursorResult.inserted_primary_key 的 CursorResult.returned_defaults 属性还将填充一个 Row 命名元组，该元组表示该单行中服务器生成值的全部范围，包括指定 Column.server_default 或使用 Column.default。

当使用 insertmany值、 UpdateBase.return_defaults（） 修饰符将具有 CursorResult.inserted_primary_key_rows 和 CursorResult.returned_defaults_rows 属性中完全填充了表示新插入的主键值以及新插入的服务器生成值。这 CursorResult.inserted_primary_key 和 CursorResult.returned_defaults attributes 也将继续填充这两个集合的第一行。

如果后端不支持 RETURNING 或正在使用的 Table 已禁用 Table.implicit_returning，则不会添加 RETURNING 子句，也不会获取其他数据，但 INSERT、UPDATE 或 DELETE 语句会正常进行。

例如：

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

result = connection.execute(stmt)

server_created_at = result.returned_defaults["created_at"]

当用于 UPDATE 语句时 UpdateBase.return_defaults（） 会查找包含 Column.onupdate 或 Column.server_onupdate分配的参数，在构造默认情况下将包含在 RETURNING 子句中的列（如果未指定显式列）。当用于 DELETE 语句时，默认情况下 RETURNING 中不包含任何列，而是必须显式指定它们，因为在 DELETE 语句继续时，没有通常会更改值的列。

2.0 版本中的新功能：支持 UpdateBase.return_defaults（） for DELETE 语句也已从 ValuesBase 设置为 UpdateBase。

UpdateBase.return_defaults（） 方法与 UpdateBase.returning（） 方法互斥，如果在一条语句上同时使用这两个方法，则在 SQL 编译过程中将引发错误。因此，INSERT、UPDATE 或 DELETE 语句的 RETURNING 子句一次只能由这些方法中的一种控制。

UpdateBase.return_defaults（） 方法不同于 UpdateBase.returning（） 的调用方法如下：

UpdateBase.return_defaults（） 方法会导致 CursorResult.returned_defaults 集合中要填充 RETURNING 结果中的第一行。使用 UpdateBase.returning（） 时，不会填充此属性。
UpdateBase.return_defaults（） 与用于获取自动生成的主键值的现有逻辑兼容，这些主键值随后被填充到 CursorResult.inserted_primary_key 属性。相比之下，使用 UpdateBase.returning（） 将具有 CursorResult.inserted_primary_key 属性。
UpdateBase.return_defaults（） 可以针对任何后端调用。不支持 RETURNING 的后端将跳过该功能的使用，而不是引发异常，除非传递了 supplemental_cols。的返回值为 CursorResult.returned_defaults None 对于不支持 RETURNING 的后端或目标 Table.implicit_returning 的表集 错误。
如果后端数据库驱动程序支持插入许多值大多数 SQLAlchemy 包含的后端现在都支持该功能。使用 executemany 时， CursorResult.returned_defaults_rows 和 CursorResult.inserted_primary_key_rows 访问器将返回插入的 defaults 和 primary key。

1.4 版本中的新功能：添加 CursorResult.returned_defaults_rows 和 CursorResult.inserted_primary_key_rows 访问。在 2.0 版本中，获取和填充这些属性的数据的底层实现被推广为大多数后端支持，而在 1.4 中，它们仅受 psycopg2 驱动程序支持。

参数

cols¶—— 可选的列键名称列表或 充当将要获取的列的筛选器的列。
supplemental_cols¶ –

可选的 RETURNING 表达式列表，其形式与传递给 UpdateBase.returning（） 方法。如果存在，则附加的 columns 将包含在 RETURNING 子句中，并且 CursorResult 对象在返回时将被“倒带”，因此像 CursorResult.all（） 这样的方法将返回新行，就像语句使用 UpdateBase.returning（） 一样径直。但是，与使用 UpdateBase.returning（） 时不同的是直接，列的顺序是未定义的，因此只能使用 names 或 Row._mapping 键进行定位;他们不能可靠地成为位置目标。

2.0 版的新Function。
sort_by_parameter_order¶ –

对于针对多个参数集执行的批处理 INSERT，组织 RETURNING 的结果，以便返回的行与传入的参数集的顺序相对应。这仅适用于 executemany 执行以支持方言，并且通常使用 insertmanyValues 功能。

在 2.0.10 版本加入.

另请参阅

将 RETURNING 行与参数集相关联 - 批量 INSERT 的 RETURNING 行排序的背景

另请参阅

UpdateBase.returning（）

CursorResult.returned_defaults

CursorResult.returned_defaults_rows

CursorResult.inserted_primary_key

CursorResult.inserted_primary_key_rows

method sqlalchemy.sql.expression.UpdateBase. returning（*cols： _ColumnsClauseArgument[Any]， sort_by_parameter_order： bool = False， **_UpdateBase__kw： Any）→ 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 版本中的新功能：可以多次调用该方法，以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应派生自 table 的 SET 作为 INSERT、UPDATE 或 DELETE 的目标。而 列对象是典型的，元素也可以是表达式：

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

编译时，将在语句中呈现 RETURNING 子句或数据库等效项。对于 INSERT 和 UPDATE，值是新插入/更新的值。对于 DELETE，值是已删除的行的值。

执行时，将生成要返回的列的值可通过结果集进行迭代，并且可以使用 CursorResult.fetchone（） 等。对于本身不支持返回值（即 cx_oracle）的 DBAPI，SQLAlchemy 将在结果级别近似此行为，以便提供合理数量的行为中立性。

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

参数

*cols¶ – 要返回的一系列列、SQL 表达式或整个表实体。
sort_by_parameter_order¶ –

对于针对多个参数集执行的批处理 INSERT，组织 RETURNING 的结果，以便返回的行与传入的参数集的顺序相对应。这仅适用于 executemany 执行以支持方言，并且通常使用 insertmanyValues 功能。

在 2.0.10 版本加入.

另请参阅

将 RETURNING 行与参数集相关联 - 批量 INSERT 的 RETURNING 行排序的背景（核心级别讨论）

将 RETURNING 记录与输入数据顺序相关联 - 与 ORM 批量 INSERT 语句一起使用的示例（ORM 级别讨论）

另请参阅

UpdateBase.return_defaults（） - 一种为高效获取服务器端默认值和单行 INSERT 或 UPDATE 触发器而定制的替代方法。

插入。。。RETURNING - 在 SQLAlchemy Unified Tutorial 中

属性 sqlalchemy.sql.expression.UpdateBase. returning_column_descriptions¶

返回此 DML 构造 RETURNING 所针对的列的启用插件的描述，换句话说，作为 UpdateBase.returning（） 的一部分建立的表达式。

此属性在使用 ORM 时通常很有用，因为会返回包含有关映射实体信息的扩展结构。检查启用 ORM 的 SELECT 和 DML 语句中的实体和列部分包含更多背景。

对于 Core 语句，此访问器返回的结构为派生自 UpdateBase.exported_columns 访问器：

>>> stmt = insert(user_table).returning(user_table.c.id, user_table.c.name)
>>> stmt.entity_description
[
    {
        "name": "id",
        "type": Integer,
        "expr": Column("id", Integer(), table=<user>, ...)
    },
    {
        "name": "name",
        "type": String(),
        "expr": Column("name", String(), table=<user>, ...)
    },
]

在 1.4.33 版本加入.

另请参阅

UpdateBase.entity_description

Select.column_descriptions - select（） 结构的实体信息

检查支持 ORM 的 SELECT 和 DML 语句中的实体和列 - ORM 背景

方法 sqlalchemy.sql.expression.UpdateBase. with_dialect_options（**opt： Any）→ Self¶

向此 INSERT/UPDATE/DELETE 对象添加方言选项。

例如：

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

方法 sqlalchemy.sql.expression.UpdateBase. with_hint（text： str， selectable：_DMLTableArgumentNone=None， dialect_name： str = '*'）→ Self¶

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

注意

UpdateBase.with_hint（） 目前仅适用于 Microsoft SQL Server。对于 MySQL INSERT/UPDATE/DELETE 提示，请使用 UpdateBase.prefix_with（） 中。

提示的文本将呈现在正在使用的数据库后端的适当位置，相对于作为此主题的 Table 语句，或者选择性地转换为给定 作为 selectable 参数传递的 Table。

dialect_name 选项将特定提示的渲染限制为特定后端。例如，要添加仅对 SQL Server 生效的提示：

mytable.insert().with_hint("WITH (PAGLOCK)", dialect_name="mssql")

参数

text¶- 提示的文本。
可选¶ - 可选的 Table，指定 UPDATE 或 DELETE 中 FROM 子句的元素作为提示的主题 - 仅适用于某些后端。
dialect_name¶ – 默认为 *，如果指定为特定方言的名称，则仅在使用该方言时应用这些提示。

类 sqlalchemy.sql.expression 中。ValuesBase¶

为 INSERT 和 UPDATE 构造提供对 ValuesBase.values（） 的支持。

成员

select、values（）

类签名

类 sqlalchemy.sql.expression.ValuesBase （ sqlalchemy.sql.expression.UpdateBase ）

attribute sqlalchemy.sql.expression.ValuesBase. select：Select[Any]None = None¶: SELECT 语句 INSERT ..从选择

method sqlalchemy.sql.expression.ValuesBase. values（*args：_DMLColumnKeyMapping[Any]Sequence[Any]， **kwargs： Any）→ Self¶

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

请注意，Insert 和 更新 构造支持 VALUES 和/或 SET 子句的每次执行时间格式，基于传递给 Connection.execute（） 的参数。但是，ValuesBase.values（） 方法可用于将一组特定的参数“修复”到语句中。

多次调用 ValuesBase.values（） 将生成一个新的结构，每次调用都修改了参数列表以包含发送的新参数。在单个参数字典的典型情况下，新传递的键将替换上一个构造中的相同键。在基于列表的 “multiple 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 或 更新 构造，则可以传递单个字典，其工作原理与 kwargs 形式的：
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
也适用于任一形式，但更常见的是 Insert 构造，则还接受包含表中每一列的条目的 Tuples：
```
users.insert().values((5, "some name"))
```
Insert 结构还支持传递字典或全表元组列表，这在服务器上将呈现不太常见的 SQL 语法“多个值” - 此语法在 SQLite、PostgreSQL、MySQL 等后端受支持，但不一定支持其他语法：
```
users.insert().values(
    [
        {"name": "some name"},
        {"name": "some other name"},
        {"name": "yet another name"},
    ]
)
```
上述表单将呈现类似于以下内容的多个 VALUES 语句：
```
INSERT INTO users (name) VALUES
                (:name_1),
                (:name_2),
                (:name_3)
```
请务必注意，传递多个值是与使用传统的 executemany（）形式不同。上述语法是通常不使用的特殊语法。要发出 INSERT 语句，通常的方法是要将多个值列表传递给 Connection.execute（） 方法，所有数据库后端都支持该方法，并且通常对于大量参数更有效。

另请参阅

发送多个参数 - 介绍 INSERT 和其他语句的多参数集调用的传统 Core 方法。

UPDATE 构造还支持渲染 SET 参数按特定顺序。有关此功能，请参阅 Update.ordered_values（） 方法。

另请参阅

Update.ordered_values（）

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

插入、更新、删除¶

DML 基础构造函数¶

DML 类文档构造函数¶