插入、更新、删除¶

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

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

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

另请参阅

相关更新

UPDATE..FROM

多表删除

method sqlalchemy.sql.expression.Delete.with_dialect_options(**opt: Any) → Self¶

继承自 UpdateBase.with_dialect_options() 方法，来自 UpdateBase

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

例如：

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

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 行排序的背景（Core 级别讨论）

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

另请参阅

UpdateBase.return_defaults() - 一种替代方法，专为高效获取服务器端默认值和单行 INSERT 或 UPDATE 的触发器而设计。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

class sqlalchemy.sql.expression.Insert¶

代表 INSERT 构造。

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

成员

with_dialect_options(), values(), returning(), from_select(), inline(), select

类签名

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

method sqlalchemy.sql.expression.Insert.with_dialect_options(**opt: Any) → Self¶

继承自 UpdateBase.with_dialect_options() 方法，来自 UpdateBase

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

例如：

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

method 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"))
```
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() 方法，所有数据库后端都支持该方法，并且对于大量参数通常更有效。

另请参阅

发送多个参数 - 传统 Core 方法的介绍，用于 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 行排序的背景（Core 级别讨论）

将 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 表达式（如列 INSERT/UPDATE 默认值中所述）如果未在名称列表中另行指定，则将呈现到 INSERT 和 SELECT 语句中，以便这些值也包含在要插入的数据中。

注意

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

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

使此 Insert 构造 “inline” 。

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

在版本 1.4 中变更: Insert.inline 参数现在已被 Insert.inline() 方法取代。

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

类 sqlalchemy.sql.expression.Update¶

代表 Update 构造。

Update 对象是使用 update() 函数创建的。

成员

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

类签名

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

方法 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 行排序的背景（Core 级别讨论）

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

另请参阅

UpdateBase.return_defaults() - 一种替代方法，专为高效获取服务器端默认值和单行 INSERT 或 UPDATE 的触发器而设计。

INSERT…RETURNING - 在 SQLAlchemy 统一教程中

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

继承自 DMLWhereBase.where() 方法，来自 DMLWhereBase

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

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

另请参阅

相关更新

UPDATE..FROM

多表删除

方法 sqlalchemy.sql.expression.Update.with_dialect_options(**opt: Any) → Self¶

继承自 UpdateBase.with_dialect_options() 方法，来自 UpdateBase

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

例如：

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

方法 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"))
```
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() 方法，所有数据库后端都支持该方法，并且对于大量参数通常更有效。

另请参阅

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

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

另请参阅

Update.ordered_values()

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

使此 Update 构造 “inline” 。

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

在版本 1.4 中变更: update.inline 参数现在已被 Update.inline() 方法取代。

方法 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, is_derived_from(), 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)

属性 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 中新增。

方法 sqlalchemy.sql.expression.UpdateBase.is_derived_from(fromclause: FromClause | None) → bool¶

如果此 ReturnsRows 是从给定的 FromClause “派生” 而来，则返回 True。

由于这些是 DML，我们不希望此类语句被适配，因此我们为派生返回 False。

方法 sqlalchemy.sql.expression.UpdateBase.params(*arg: Any, **kw: Any) → NoReturn¶

设置语句的参数。

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

方法 sqlalchemy.sql.expression.UpdateBase.return_defaults(*cols: _DMLColumnArgument, supplemental_cols: Iterable[_DMLColumnArgument] | None = None, sort_by_parameter_order: bool = False) → Self¶

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

深度炼金术

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

通常，单行 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 或使用 SQL 表达式的 Column.default 的任何列的值。

当使用 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 行排序的背景（Core 级别讨论）

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

method 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¶ – 默认为 *，如果指定为特定方言的名称，则仅当使用该方言时才应用这些提示。

class sqlalchemy.sql.expression.ValuesBase¶

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

成员

select, values()

类签名

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

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

method 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"))
```
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() 方法，所有数据库后端都支持该方法，并且对于大量参数通常更有效。

另请参阅

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

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

另请参阅

Update.ordered_values()

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

插入、更新、删除¶

DML 基础构造器¶

DML 类文档构造器¶