插入、更新、删除¶

INSERT、UPDATE 和 DELETE 语句基于以 UpdateBase 为起点的层次结构。 Insert 和 Update 构造基于中间的 ValuesBase.

DML 基础构造函数¶

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

对象名称	描述
delete(table)	构造 `Delete` 对象。
insert(table)	构造一个 `Insert` 对象。
update(table)	构造一个 `Update` 对象。

function sqlalchemy.sql.expression.delete(table: _DMLTableArgument) → Delete¶

构造 Delete 对象。

例如：

from sqlalchemy import delete

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

类似的功能可通过 TableClause.delete() 方法在 Table 上使用。

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

另请参见

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

function sqlalchemy.sql.expression.insert(table: _DMLTableArgument) → Insert¶

构造一个 Insert 对象。

例如：

from sqlalchemy import insert

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

类似的功能可通过 TableClause.insert() 方法在 Table 上使用。

另请参见

使用 INSERT 语句 - 在 SQLAlchemy 统一教程中

参数:

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

如果同时存在 insert.values 和编译时绑定参数，编译时绑定参数将按键覆盖 insert.values 中指定的信息。

Insert.values 中的键可以是 Column 对象或它们的字符串标识符。每个键可以引用以下之一

文字数据值（即字符串、数字等）；
Column 对象；
SELECT 语句。

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

另请参见

使用 INSERT 语句 - 在 SQLAlchemy 统一教程中

function sqlalchemy.sql.expression.update(table: _DMLTableArgument) → Update¶

构造一个 Update 对象。

例如：

from sqlalchemy import update

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

类似的功能可通过 TableClause.update() 方法在 Table 上使用。

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

另请参见

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

DML 类文档构造函数¶

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

对象名称	描述
Delete	表示 DELETE 构造。
Insert	表示 INSERT 构造。
Update	表示 Update 构造。
UpdateBase	构成`INSERT`、`UPDATE` 和 `DELETE` 语句的基础。
ValuesBase	为 `ValuesBase.values()` 提供对 INSERT 和 UPDATE 结构的支持。

class sqlalchemy.sql.expression.Delete¶

表示 DELETE 构造。

使用 delete() 函数创建 Delete 对象。

成员

where()、returning()

类签名

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

method sqlalchemy.sql.expression.Delete.where(*whereclause: _ColumnExpressionArgument[bool]) → Self¶

继承自 DMLWhereBase.where() 方法的 DMLWhereBase

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

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

另请参见

相关更新

UPDATE..FROM

多表删除

method sqlalchemy.sql.expression.Delete.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

继承自 UpdateBase.returning() 方法的 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 版新增：该方法可以被多次调用以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应来自 INSERT、UPDATE 或 DELETE 的目标表。虽然 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

在编译时，一个 RETURNING 子句或数据库等效子句将被渲染在语句中。对于 INSERT 和 UPDATE，这些值是新插入/更新的值。对于 DELETE，这些值是已删除行的值。

在执行时，要返回的列的值通过结果集提供，并且可以使用 CursorResult.fetchone() 及类似方法进行迭代。对于那些没有原生支持返回值的 DBAPI（即 cx_oracle），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 有效获取服务器端默认值和触发器的方法。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

class sqlalchemy.sql.expression.Insert¶

表示 INSERT 构造。

使用 insert() 函数创建 Insert 对象。

成员

values()、returning()、from_select()、inline()、select

类签名

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

方法 sqlalchemy.sql.expression.Insert.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self¶

继承自 ValuesBase.values() 方法 ValuesBase

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

请注意，Insert 和 Update 结构支持基于传递给 Connection.execute() 的参数，在每次执行时对 VALUES 和/或 SET 子句进行格式化。但是，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 形式相同
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
对于两种形式，但更常见的是 Insert 结构，也可以接受包含表中每列的条目的元组
```
users.insert().values((5, "some name"))
```
The 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 和其他语句的多参数集调用的传统核心方法。

UPDATE 结构还支持以特定顺序渲染 SET 参数。有关此功能，请参阅 Update.ordered_values() 方法。

另请参见

Update.ordered_values()

方法 sqlalchemy.sql.expression.Insert.returning(*cols: _ColumnsClauseArgument[Any], sort_by_parameter_order: bool = False, **_UpdateBase__kw: Any) → UpdateBase¶

继承自 UpdateBase.returning() 方法的 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 版新增：该方法可以被多次调用以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应来自 INSERT、UPDATE 或 DELETE 的目标表。虽然 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

在编译时，一个 RETURNING 子句或数据库等效子句将被渲染在语句中。对于 INSERT 和 UPDATE，这些值是新插入/更新的值。对于 DELETE，这些值是已删除行的值。

在执行时，要返回的列的值通过结果集提供，并且可以使用 CursorResult.fetchone() 及类似方法进行迭代。对于那些没有原生支持返回值的 DBAPI（即 cx_oracle），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 有效获取服务器端默认值和触发器的方法。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

方法 sqlalchemy.sql.expression.Insert.from_select(names: Sequence[_DMLColumnArgument], select: Selectable, include_defaults: bool = True) → Self¶

返回一个新的 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，则不会在名称列表中指定的 Column 对象上指定的非服务器默认值和 SQL 表达式（如 Column INSERT/UPDATE Defaults 中所述）将被渲染到 INSERT 和 SELECT 语句中，以便这些值也被包含在要插入的数据中。

注意

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

方法 sqlalchemy.sql.expression.Insert.inline() → Self¶

使此 Insert 结构“内联”。

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

在版本 1.4 中更改: the Insert.inline parameter is now superseded by the Insert.inline() method.

attribute sqlalchemy.sql.expression.Insert.select: Select[Any] | None = None¶: INSERT .. FROM SELECT 的 SELECT 语句

class sqlalchemy.sql.expression.Update¶

表示 Update 构造。

The Update object is created using the update() function.

成员

returning(), where(), values(), inline(), ordered_values()

类签名

class 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.returning() 方法的 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 版新增：该方法可以被多次调用以将新条目添加到要返回的表达式列表中。

给定的列表达式集合应来自 INSERT、UPDATE 或 DELETE 的目标表。虽然 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

在编译时，一个 RETURNING 子句或数据库等效子句将被渲染在语句中。对于 INSERT 和 UPDATE，这些值是新插入/更新的值。对于 DELETE，这些值是已删除行的值。

在执行时，要返回的列的值通过结果集提供，并且可以使用 CursorResult.fetchone() 及类似方法进行迭代。对于那些没有原生支持返回值的 DBAPI（即 cx_oracle），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 有效获取服务器端默认值和触发器的方法。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

method sqlalchemy.sql.expression.Update.where(*whereclause: _ColumnExpressionArgument[bool]) → Self¶

继承自 DMLWhereBase.where() 方法的 DMLWhereBase

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

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

另请参见

相关更新

UPDATE..FROM

多表删除

method sqlalchemy.sql.expression.Update.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self¶

继承自 ValuesBase.values() 方法 ValuesBase

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

请注意，Insert 和 Update 结构支持基于传递给 Connection.execute() 的参数，在每次执行时对 VALUES 和/或 SET 子句进行格式化。但是，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 形式相同
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
对于两种形式，但更常见的是 Insert 结构，也可以接受包含表中每列的条目的元组
```
users.insert().values((5, "some name"))
```
The 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 和其他语句的多参数集调用的传统核心方法。

UPDATE 结构还支持以特定顺序渲染 SET 参数。有关此功能，请参阅 Update.ordered_values() 方法。

另请参见

Update.ordered_values()

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

Make this Update construct “inline” .

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

在版本 1.4 中更改: the update.inline parameter is now superseded by the Update.inline() method.

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

另请参见

Parameter Ordered Updates - Update.ordered_values() 方法的完整示例。

在版本 1.4 中更改: The Update.ordered_values() method supersedes the update.preserve_parameter_order parameter, which will be removed in SQLAlchemy 2.0.

class sqlalchemy.sql.expression.UpdateBase¶

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

成员

entity_description, exported_columns, params(), return_defaults(), returning(), returning_column_descriptions, with_dialect_options(), with_hint()

类签名

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.Generative, sqlalchemy.sql.expression.ExecutableReturnsRows, sqlalchemy.sql.expression.ClauseElement)

attribute 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 背景信息

attribute 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) → Self¶

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

深度炼金术

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

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

但是，当在执行语句之前通过调用 UpdateBase.return_defaults() 修改语句时，只有对于支持 RETURNING 的后端以及 Table 对象（其 Table.implicit_returning 参数保持在默认值 True）才会发生其他行为。在这些情况下，当从语句的执行返回 CursorResult 时，不仅会填充 CursorResult.inserted_primary_key，还会填充 CursorResult.returned_defaults 属性，该属性包含一个 Row 命名元组，表示来自该单行的服务器生成的完整范围的值，包括任何指定了 Column.server_default 或使用 Column.default（使用 SQL 表达式）的列的值。

当使用 insertmanyvalues 对多行使用 INSERT 语句时，UpdateBase.return_defaults() 修饰符的效果是 CursorResult.inserted_primary_key_rows 和 CursorResult.returned_defaults_rows 属性将完全填充，其中包含 Row 对象的列表，表示新插入的主键值以及为每行插入的新插入的服务器生成的值。 CursorResult.inserted_primary_key 和 CursorResult.returned_defaults 属性也将继续填充这两个集合的第一行。

如果后端不支持 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() 也支持 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。对于不支持 RETURNING 或目标 Table 将 Table.implicit_returning 设置为 False 的后端，CursorResult.returned_defaults 的返回值将为 None。
如果后端数据库驱动程序支持 insertmanyvalues 功能（现在大多数 SQLAlchemy 包含的后端都支持），则可以使用 executemany() 调用 INSERT 语句。当使用 executemany 时，CursorResult.returned_defaults_rows 和 CursorResult.inserted_primary_key_rows 访问器将返回插入的默认值和主键。

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

参数:

cols¶ – 可选的列键名称列表或 Column，充当将要获取的列的过滤器。
supplemental_cols¶ –
可选的 RETURNING 表达式列表，与传递给 UpdateBase.returning() 方法的形式相同。当存在时，附加的列将被包含在 RETURNING 子句中，并且 CursorResult 对象将在返回时被“倒带”，以便像 CursorResult.all() 这样的方法将返回新的行，就像该语句直接使用 UpdateBase.returning() 一样。但是，与直接使用 UpdateBase.returning() 不同，列的顺序是不确定的，因此只能使用名称或 Row._mapping 键来定位它们；它们不能可靠地按位置定位。

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

给定的列表达式集合应来自 INSERT、UPDATE 或 DELETE 的目标表。虽然 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

在编译时，一个 RETURNING 子句或数据库等效子句将被渲染在语句中。对于 INSERT 和 UPDATE，这些值是新插入/更新的值。对于 DELETE，这些值是已删除行的值。

在执行时，要返回的列的值通过结果集提供，并且可以使用 CursorResult.fetchone() 及类似方法进行迭代。对于那些没有原生支持返回值的 DBAPI（即 cx_oracle），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 有效获取服务器端默认值和触发器的方法。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

attribute 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 背景信息

method 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: _DMLTableArgument | None = 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¶ – 提示文本。
selectable¶ – 可选的 Table，指定 UPDATE 或 DELETE 中 FROM 子句的元素作为提示主题 - 仅适用于某些后端。
dialect_name¶ – 默认值为 *，如果指定为特定方言的名称，则仅在使用该方言时应用这些提示。

类 sqlalchemy.sql.expression.ValuesBase¶

为 ValuesBase.values() 提供对 INSERT 和 UPDATE 结构的支持。

成员

select, values()

类签名

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

属性 sqlalchemy.sql.expression.ValuesBase.select: Select[Any] | None = None¶: INSERT .. FROM SELECT 的 SELECT 语句

方法 sqlalchemy.sql.expression.ValuesBase.values(*args: _DMLColumnKeyMapping[Any] | Sequence[Any], **kwargs: Any) → Self¶

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

请注意，Insert 和 Update 结构支持基于传递给 Connection.execute() 的参数，在每次执行时对 VALUES 和/或 SET 子句进行格式化。但是，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 形式相同
```
users.insert().values({"name": "some name"})

users.update().values({"name": "some new name"})
```
对于两种形式，但更常见的是 Insert 结构，也可以接受包含表中每列的条目的元组
```
users.insert().values((5, "some name"))
```
The 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 和其他语句的多参数集调用的传统核心方法。

UPDATE 结构还支持以特定顺序渲染 SET 参数。有关此功能，请参阅 Update.ordered_values() 方法。

另请参见

Update.ordered_values()

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

插入、更新、删除¶

DML 基础构造函数¶

DML 类文档构造函数¶