SqlAlchemy 2.0 中文文档（四十四）（5）

SqlAlchemy 2.0 中文文档（四十四）（4）https://developer.aliyun.com/article/1563071

类签名

类sqlalchemy.engine.RootTransaction（sqlalchemy.engine.Transaction）

method close() → None

继承自Transaction.close() 方法的 Transaction

关闭此 Transaction。

如果此事务是嵌套在 begin/commit 中的基本事务，则事务将回滚()。否则，该方法返回。

这用于取消事务，而不影响封闭事务的范围。

method commit() → None

继承自Transaction.commit() 方法的 Transaction

提交此 Transaction。

实现可能根据正在使用的事务类型而变化：

• 对于简单的数据库事务（例如RootTransaction），它对应于一个 COMMIT。
  
• 对于 NestedTransaction，它对应于“RELEASE SAVEPOINT”操作。
  
• 对于 TwoPhaseTransaction，可以使用特定于 DBAPI 的两阶段事务方法。
  

method rollback() → None

继承自Transaction.rollback() 方法的 Transaction

回滚此 Transaction。

实现可能根据正在使用的事务类型而变化：

• 对于简单的数据库事务（例如RootTransaction），它对应于一个 ROLLBACK。
  
• 对于 NestedTransaction，它对应于“ROLLBACK TO SAVEPOINT”操作。
  
• 对于 TwoPhaseTransaction，可以使用特定于 DBAPI 的两阶段事务方法。
  

class sqlalchemy.engine.Transaction

表示正在进行的数据库事务。

调用 Connection.begin() 方法的 Connection 获得 Transaction 对象：

from sqlalchemy import create_engine
engine = create_engine("postgresql+psycopg2://scott:tiger@localhost/test")
connection = engine.connect()
trans = connection.begin()
connection.execute(text("insert into x (a, b) values (1, 2)"))
trans.commit()

该对象提供了rollback()和commit()方法以控制事务边界。它还实现了上下文管理器接口，以便 Python with语句可以与Connection.begin()方法一起使用：

with connection.begin():
    connection.execute(text("insert into x (a, b) values (1, 2)"))

Transaction 对象不是线程安全的。

成员

close()，commit()，rollback()

另请参阅

Connection.begin()

Connection.begin_twophase()

Connection.begin_nested()

类签名

类sqlalchemy.engine.Transaction（sqlalchemy.engine.util.TransactionalContext）

method close() → None

关闭此Transaction。

如果此事务是 begin/commit 嵌套中的基本事务，则事务将回滚()。否则，该方法返回。

这用于取消 Transaction 而不影响封闭事务的范围。

method commit() → Non

提交此Transaction。

其实现可能根据使用的事务类型而变化：

• 对于简单的数据库事务（例如RootTransaction），它对应于 COMMIT。
  
• 对于NestedTransaction，它对应于“RELEASE SAVEPOINT”操作。
  
• 对于TwoPhaseTransaction，可能会使用特定于 DBAPI 的两阶段事务方法。
  

method rollback() → None

回滚此Transaction。

其实现可能根据使用的事务类型而变化：

• 对于简单的数据库事务（例如RootTransaction），它对应于 ROLLBACK。
  
• 对于NestedTransaction，它对应于“ROLLBACK TO SAVEPOINT”操作。
  
• 对于TwoPhaseTransaction，可能会使用特定于 DBAPI 的两阶段事务方法。
  

class sqlalchemy.engine.TwoPhaseTransaction

表示两阶段事务。

可以使用 Connection.begin_twophase() 方法获取新的 TwoPhaseTransaction 对象。

接口与 Transaction 相同，只增加了 prepare() 方法。

成员

close(), commit(), prepare(), rollback()

类签名

类 sqlalchemy.engine.TwoPhaseTransaction (sqlalchemy.engine.RootTransaction)

method close() → None

继承自 Transaction.close() 方法的 Transaction

关闭此 Transaction。

如果此事务是开始/提交嵌套中的基本事务，则事务将回滚()。否则，该方法返回。

这用于取消事务，而不影响封闭事务的范围。

method commit() → None

继承自 Transaction.commit() 方法的 Transaction

提交此 Transaction。

其实现可能会根据所使用的事务类型而变化：

• 对于简单的数据库事务（例如 RootTransaction），它对应于 COMMIT。
  
• 对于 NestedTransaction，它对应于“RELEASE SAVEPOINT”操作。
  
• 对于 TwoPhaseTransaction，可以使用特定于 DBAPI 的两阶段事务方法。
  

method prepare() → None

准备此 TwoPhaseTransaction。

在 PREPARE 之后，可以提交事务。

method rollback() → None

继承自 Transaction.rollback() 方法的 Transaction

回滚此 Transaction。

实现可能会根据使用的事务类型而有所不同：

• 对于简单的数据库事务（例如RootTransaction），它对应于 ROLLBACK。
  
• 对于NestedTransaction，它对应于“ROLLBACK TO SAVEPOINT”操作。
  
• 对于TwoPhaseTransaction，可以使用特定于 DBAPI 的方法进行两阶段事务。
  

Result Set API

class sqlalchemy.engine.ChunkedIteratorResult

一个从生成迭代器的可调用对象中工作的 IteratorResult。

给定的 chunks 参数是一个函数，该函数给出每个块中要返回的行数，或者为 None 以返回所有行。该函数应返回一个未使用的列表迭代器，每个列表的大小为请求的大小。

可以在任何时候再次调用该函数，在这种情况下，它应从相同的结果集继续，但根据给定的块大小进行调整。

自 1.4 版开始。

成员

yield_per()

类签名

类 sqlalchemy.engine.ChunkedIteratorResult (sqlalchemy.engine.IteratorResult)

method yield_per(num: int) → Self

配置行提取策略，以一次提取 num 行。

这会影响结果在迭代结果对象时的基础行为，或者在使用诸如 Result.fetchone() 这样一次返回一行的方法时进行使用。来自底层游标或其他数据源的数据将在内存中缓冲到这么多行，并且缓冲集合然后将一行一次或请求的行数作为输出。每次缓冲清除时，它都将刷新为这么多行或如果剩余的行数少于这么多行则为剩余的行数。

Result.yield_per() 方法通常与 Connection.execution_options.stream_results 执行选项一起使用，该选项将允许正在使用的数据库方言使用服务器端游标，如果 DBAPI 支持与其默认操作模式分离的特定“服务器端游标”模式。

提示

考虑使用 Connection.execution_options.yield_per 执行选项，它将同时设置 Connection.execution_options.stream_results 以确保使用服务器端游标，并自动调用 Result.yield_per() 方法一次性建立固定的行缓冲区大小。

Connection.execution_options.yield_per 执行选项可用于 ORM 操作，其与Session相关的用法在使用 Yield Per 获取大型结果集中进行了描述。与Connection配合使用的仅限于 Core 的版本是 SQLAlchemy 1.4.40 的新功能。

1.4 版中的新功能。

参数：

num – 每次重新填充缓冲区时要获取的行数。如果设置为小于 1 的值，则获取下一个缓冲区的所有行。

另请参阅

使用服务器端游标（又名流式结果） - 描述了Result.yield_per()的核心行为。

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南中

class sqlalchemy.engine.CursorResult

表示来自 DBAPI 游标的状态的 Result。

自 1.4 版更改：CursorResult 类取代了以前的 ResultProxy 接口。这些类基于Result调用 API，为 SQLAlchemy Core 和 SQLAlchemy ORM 提供了更新的使用模型和调用外观。

通过Row类返回数据库行，该类在 DBAPI 返回的原始数据之上提供了其他 API 功能和行为。通过诸如Result.scalars()方法之类的过滤器，还可以返回其他类型的对象。

另请参阅

使用 SELECT 语句 - 用于访问CursorResult和Row对象的入门材料。

成员

all(), close(), columns(), fetchall(), fetchmany(), fetchone(), first(), freeze(), inserted_primary_key, inserted_primary_key_rows, is_insert, keys(), last_inserted_params(), last_updated_params(), lastrow_has_defaults(), lastrowid, mappings(), merge(), one(), one_or_none(), partitions(), postfetch_cols(), prefetch_cols(), returned_defaults, returned_defaults_rows, returns_rows, rowcount, scalar(), scalar_one(), scalar_one_or_none(), scalars(), splice_horizontally(), splice_vertically(), supports_sane_multi_rowcount(), supports_sane_rowcount(), t, tuples(), unique(), yield_per()

类签名

类 sqlalchemy.engine.CursorResult (sqlalchemy.engine.Result)

method all() → Sequence[Row[_TP]]

继承自 Result.all() 方法的 Result

返回序列中的所有行。

调用后关闭结果集。后续调用将返回一个空序列。

版本 1.4 中的新功能。

返回：

一系列 Row 对象。

另请参见

使用服务器端游标（又称流式结果） - 如何在 Python 中流式传输大型结果集而不完全加载它。

method close() → Any

关闭此 CursorResult。

如果仍然存在底层 DBAPI 游标，则关闭该游标对应的语句执行。请注意，当 CursorResult 耗尽所有可用行时，DBAPI 游标会自动释放。通常，CursorResult.close() 是一个可选方法，除非在丢弃一个仍具有待提取的附加行的 CursorResult 时。

调用此方法后，再调用提取方法将不再有效，并且在后续使用时会引发 ResourceClosedError。

另请参见

使用引擎和连接

method columns(*col_expressions: _KeyIndexType) → Self

继承自 Result.columns() 方法的 Result

确定每行应返回的列。

此方法可用于限制返回的列，也可用于重新排序列。给定的表达式列表通常是一系列整数或字符串键名。它们也可以是适当的 ColumnElement 对象，这些对象对应于给定的语句构造。

2.0 版本中的更改：由于 1.4 版本中的一个错误，Result.columns() 方法具有了错误的行为，仅使用一个索引调用该方法会导致 Result 对象生成标量值，而不是 Row 对象。在 2.0 版本中，已经纠正了这种行为，调用 Result.columns() 时使用单个索引将产生一个继续生成 Row 对象的 Result 对象，该对象仅包含单个列。

例如：

statement = select(table.c.x, table.c.y, table.c.z)
result = connection.execute(statement)
for z, y in result.columns('z', 'y'):
    # ...

使用语句本身的列对象的示例：

for z, y in result.columns(
        statement.selected_columns.c.z,
        statement.selected_columns.c.y
):
    # ...

1.4 版本中的新内容。

参数：

*col_expressions – 表示要返回的列。元素可以是整数行索引、字符串列名称或与选择构造相对应的适当 ColumnElement 对象。

返回：

带有给定修改的此 Result 对象。

method fetchall() → Sequence[Row[_TP]]

继承自 Result.fetchall() 方法的 Result

Result.all() 方法的同义词。

method fetchmany(size: int | None = None) → Sequence[Row[_TP]]

继承自 Result.fetchmany() 方法的 Result

获取多行。

当所有行都用完时，返回空序列。

此方法用于向后兼容 SQLAlchemy 1.x.x。

要按组获取行，请使用 Result.partitions() 方法。

返回：

一系列 Row 对象。

另请参阅

Result.partitions()

method fetchone() → Row[_TP] | None

继承自 Result.fetchone() 方法的 Result

获取一行。

当所有行都用完时，返回 None。

此方法用于向后兼容 SQLAlchemy 1.x.x。

要仅获取结果的第一行，请使用 Result.first() 方法。要遍历所有行，请直接遍历 Result 对象。

返回：

如果未应用任何过滤器，则返回一个 Row 对象，否则返回 None。

method first() → Row[_TP] | None

继承自 Result.first() 方法的 Result

获取第一行或者如果不存在行则返回 None。

关闭结果集并丢弃剩余行。

注意

默认情况下，此方法返回一行，例如元组。要返回确切的一个单一标量值，即第一行的第一列，请使用 Result.scalar() 方法，或组合 Result.scalars() 和 Result.first()。

此外，与传统 ORM Query.first() 方法的行为相比，不会应用限制到用于生成此 Result 的 SQL 查询；对于在生成行之前在内存中缓冲结果的 DBAPI 驱动程序，所有行将被发送到 Python 进程，并且除了第一行之外的所有行都将被丢弃。

另请参阅

ORM 查询与核心选择统一

返回：

一个 Row 对象，如果没有剩余行则为 None。

另请参阅

Result.scalar()

Result.one()

method freeze() → FrozenResult[_TP]

继承自 Result.freeze() 方法的 Result

返回一个可调用对象，当调用时将产生此 Result 的副本。

返回的可调用对象是 FrozenResult 的实例。

用于结果集缓存。必须在结果未被消耗时调用该方法，并且调用该方法将完全消耗结果。当从缓存中检索到 FrozenResult 时，可以任意多次调用它，每次对其存储的行集产生一个新的 Result 对象。

另请参阅

重新执行语句 - 在 ORM 中示例用法以实现结果集缓存。

attribute inserted_primary_key

返回刚刚插入行的主键。

返回值是一个按照源 Table 中配置的主键列顺序表示的 Row 对象的命名元组。

从版本 1.4.8 开始更改：- CursorResult.inserted_primary_key 值现在是通过 Row 类的命名元组，而不是普通元组。

此访问器仅适用于未明确指定Insert.returning()的单行insert()构造。对于多行插入，虽然大多数后端尚不支持，但可以使用CursorResult.inserted_primary_key_rows访问器。

请注意，指定了 server_default 子句或以其他方式不符合“自增”列（请参阅Column中的注释），并且是使用数据库端默认值生成的主键列，除非后端支持“returning”并且执行了启用“隐式 returning”的插入语句，否则将在此列表中显示为None。

如果执行的语句不是编译的表达式构造或不是 insert() 构造，则引发InvalidRequestError。

attribute inserted_primary_key_rows

返回CursorResult.inserted_primary_key的值，作为包含在列表中的行；一些方言可能还支持多行形式。

注意

如下所示，在当前的 SQLAlchemy 版本中，仅当使用 psycopg2 方言时，此访问器才有用。未来的版本希望将此功能推广到更多的方言。

此访问器被添加以支持目前仅由 Psycopg2 快速执行助手功能实现的方言，目前仅适用于 psycopg2 方言，它允许一次插入多行同时仍保留能够返回服务器生成的主键值的行为。

• 当使用 psycopg2 方言或其他可能在即将发布的版本中支持“快速 executemany”样式插入的方言时：在调用 INSERT 语句时，将行列表作为第二个参数传递给Connection.execute()时，此访问器将提供一个行列表，其中每一行包含被插入的每一行的主键值。
  
• 当使用所有其他尚不支持此功能的方言/后端时：此访问器仅对单行 INSERT 语句有用，并返回与CursorResult.inserted_primary_key相同的信息，放在一个单元素列表中。当 INSERT 语句与要插入的行的列表一起执行时，列表将包含语句中插入的每一行，但对于任何服务器生成的值，它将包含None。
  

未来的 SQLAlchemy 版本将进一步将 psycopg2 的“快速执行助手”功能泛化以适应其他方言，从而使此访问器更具一般性。

在 1.4 版本中新增。

另请参阅

CursorResult.inserted_primary_key

attribute is_insert

如果此CursorResult是执行表达式语言编译的insert()构造的结果，则返回 True。

当为 True 时，这意味着可以访问inserted_primary_key属性，假设语句未包含用户定义的“returning”构造。

method keys() → RMKeyView

继承自 sqlalchemy.engine._WithKeys.keys 方法的 sqlalchemy.engine._WithKeys

返回一个可迭代的视图，该视图产生每个Row表示的字符串键。

键可以表示核心语句返回的列的标签或 ORM 执行返回的 ORM 类的名称。

该视图还可以使用 Python 的in运算符进行键包含性测试，该运算符将测试视图中表示的字符串键，以及列对象等备用键。

在 1.4 版本中更改：返回一个键视图对象，而不是一个普通列表。

method last_inserted_params()

从此执行返回插入的参数集合。

如果执行的语句不是编译的表达式构造或不是 insert()构造，则引发InvalidRequestError。

method last_updated_params()

从此执行返回更新的参数集合。

如果执行的语句不是编译的表达式构造或不是 update()构造，则引发InvalidRequestError。

method lastrow_has_defaults()

从底层的ExecutionContext返回lastrow_has_defaults()。

有关详细信息，请参阅ExecutionContext。

attribute lastrowid

返回 DBAPI 游标上的 ‘lastrowid’ 访问器。

这是一个特定于 DBAPI 的方法，仅在支持的后端中才起作用，适用于适当的语句。其行为在各后端之间不一致。

在使用 insert() 表达式构造时，通常不需要使用此方法；CursorResult.inserted_primary_key 属性提供了一个新插入行的主键值元组，无论数据库后端如何。

method mappings() → MappingResult

继承自 Result.mappings() 方法的 Result

应用一个映射过滤器到返回的行，返回一个 MappingResult 实例。

当应用此过滤器时，获取行将返回 RowMapping 对象而不是 Row 对象。

新版本 1.4 中新增。

返回：

一个指向此 Result 对象的新 MappingResult 过滤对象。

method merge(*others: Result[Any]) → MergedResult[Any]

将此Result与其他兼容的结果对象合并。

返回的对象是一个 MergedResult 的实例，它将由给定结果对象的迭代器组成。

新结果将使用此结果对象的元数据。后续的结果对象必须针对相同的结果/游标元数据集，否则行为是未定义的。

method one() → Row[_TP]

继承自 Result.one() 方法的 Result

仅返回一行数据或引发异常。

如果结果没有返回行，则引发 NoResultFound，如果返回多行，则引发 MultipleResultsFound。

注意

此方法默认返回一个 行，例如元组。要返回确切的一个单一标量值，即第一行的第一列，请使用 Result.scalar_one() 方法，或者结合使用 Result.scalars() 和 Result.one()。

新版本 1.4 中新增。

返回：

第一个 Row。

引发：

MultipleResultsFound, NoResultFound

另请参阅

Result.first()

Result.one_or_none()

Result.scalar_one()

method one_or_none() → Row[_TP] | None

继承自 Result.one_or_none() 方法的 Result

返回至多一个结果或引发异常。

如果结果没有行，则返回 None。如果返回多行，则引发 MultipleResultsFound。

版本 1.4 中的新功能。

返回：

第一个 Row 或 None（如果没有可用行）。

引发：

MultipleResultsFound

另请参阅

Result.first()

Result.one()

method partitions(size: int | None = None) → Iterator[Sequence[Row[_TP]]]

继承自 Result.partitions() 方法的 Result

迭代给定大小的行子列表。

每个列表将具有给定的大小，最后一个要产生的列表除外，该列表可能具有少量行。不会产生空列表。

迭代器完全消耗时，结果对象会自动关闭。

请注意，除非使用了 Connection.execution_options.stream_results 执行选项指示驱动程序不应在可能的情况下预先缓冲结果，否则后端驱动程序通常会提前缓冲整个结果。不是所有驱动程序都支持此选项，对于不支持此选项的驱动程序，该选项会被静默忽略。

在使用 ORM 时，Result.partitions() 方法通常在内存方面更有效，当与 yield_per execution option 结合使用时，该方法指示 DBAPI 驱动程序在可用时使用服务器端游标，并指示 ORM 加载内部仅在每次从结果中产生一定数量的 ORM 对象之前构建一定数量的 ORM 对象。

版本 1.4 中的新功能。

参数：

size – 表示每个生成的列表中应该存在的最大行数。如果为 None，则使用由 Result.yield_per() 方法设置的值，如果已调用，或者使用等效的 Connection.execution_options.yield_per 执行选项。如果未设置 yield_per，则使用 Result.fetchmany() 的默认值，这可能是特定于后端的并且不太定义明确的。

返回：

列表的迭代器

另请参阅

使用服务器端游标（也称为流式结果）

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南 中

method postfetch_cols()

从底层 ExecutionContext 返回 postfetch_cols()。

详细信息请参阅 ExecutionContext。

如果执行的语句不是编译后的表达式构造或不是 insert() 或 update() 构造，则会引发InvalidRequestError。

method prefetch_cols()

从底层 ExecutionContext 返回 prefetch_cols()。

详细信息请参阅 ExecutionContext。

如果执行的语句不是编译后的表达式构造或不是 insert() 或 update() 构造，则会引发InvalidRequestError。

attribute returned_defaults

返回使用 ValuesBase.return_defaults() 功能提取的默认列的值。

如果 ValuesBase.return_defaults() 未使用或后端不支持 RETURNING，则值为 Row 的实例，或者为 None。

另请参阅

ValuesBase.return_defaults()

attribute returned_defaults_rows

返回包含使用 ValuesBase.return_defaults() 功能提取的默认列的值的行列表。

返回值是 Row 对象的列表。

版本 1.4 中的新功能。

attribute returns_rows

如果此 CursorResult 返回零个或多个行，则为 True。

即如果可以调用方法 CursorResult.fetchone(), CursorResult.fetchmany() CursorResult.fetchall().

总的来说，CursorResult.returns_rows 的值应该始终与 DBAPI 游标是否具有 .description 属性同义，指示结果列的存在，需要注意的是，即使游标返回零行，如果发出了返回行的语句，游标仍然具有 .description。

这个属性对于所有针对 SELECT 语句的结果都应该为 True，以及对于使用 RETURNING 的 DML 语句 INSERT/UPDATE/DELETE 也应该为 True。对于没有使用 RETURNING 的 INSERT/UPDATE/DELETE 语句，该值通常为 False，但是有一些方言特定的例外情况，比如使用 MSSQL / pyodbc 方言时，会内联发出一个 SELECT 来检索插入的主键值。

attribute rowcount

返回此结果的 ‘rowcount’。

‘rowcount’ 的主要目的是报告执行一次 UPDATE 或 DELETE 语句的 WHERE 条件匹配的行数（即对于单个参数集），然后可以将其与预期更新或删除的行数进行比较，作为断言数据完整性的手段。

此属性是从 DBAPI 的 cursor.rowcount 属性转移而来，之后游标关闭，以支持不在游标关闭后提供此值的 DBAPI。一些 DBAPI 可能为其他类型的语句（例如 INSERT 和 SELECT 语句）提供有意义的值。为了检索这些语句的 cursor.rowcount，将 Connection.execution_options.preserve_rowcount 执行选项设置为 True，这将导致在返回任何结果或游标关闭之前，无条件地缓存 cursor.rowcount 值，无论语句类型如何。

对于 DBAPI 不支持某种类型的语句和/或执行的情况，返回的值将为 -1，这是直接从 DBAPI 传递的，是 PEP 249 的一部分。所有 DBAPI 都应支持单参数集 UPDATE 和 DELETE 语句的 rowcount，但是。

注意

有关 CursorResult.rowcount 的注意事项：

• 此属性返回匹配的行数，这不一定与实际修改的行数相同。例如，如果 UPDATE 语句中的 SET 值与行中已存在的值相同，则对给定行可能没有净变化。这样的行将被匹配但不会被修改。在具有两种样式的后端（例如 MySQL）上，rowcount 被配置为在所有情况下返回匹配计数。
  
• 在默认情况下，CursorResult.rowcount 仅在与 UPDATE 或 DELETE 语句结合使用时才有用，并且仅适用于单组参数。对于其他类型的语句，除非使用Connection.execution_options.preserve_rowcount执行选项，否则 SQLAlchemy 不会尝试预先缓存该值。请注意，与PEP 249相反，许多 DBAPI 不支持不是 UPDATE 或 DELETE 的语句的 rowcount 值，特别是当返回的行没有完全预先缓冲时。不支持某种语句类型的 rowcount 的 DBAPI 应为这些语句返回值-1。
  
• 在执行具有多个参数集的单个语句（即 executemany）时，CursorResult.rowcount可能没有意义。大多数 DBAPI 不会跨多个参数集对“rowcount”值求和，并在访问时返回-1。
  
• SQLAlchemy 的“INSERT 语句的多值插入”行为功能在设置Connection.execution_options.preserve_rowcount执行选项为 True 时支持正确填充CursorResult.rowcount。
  
• 使用 RETURNING 的语句可能不支持 rowcount，而是返回值-1。
  

另请参阅

从 UPDATE、DELETE 获取受影响的行数 - 在 SQLAlchemy 统一教程中

Connection.execution_options.preserve_rowcount

method scalar() → Any

继承自 Result.scalar() 方法的 Result

获取第一行的第一列，并关闭结果集。

如果没有要获取的行，则返回None。

不执行验证以测试是否还有其他行。

调用此方法后，对象已完全关闭，例如已调用 CursorResult.close() 方法。

返回：

一个 Python 标量值，或者如果没有剩余行则为 None。

method scalar_one() → Any

继承自 Result.scalar_one() 方法的 Result

返回确切的一个标量结果或引发异常。

这等同于调用 Result.scalars() 然后调用 Result.one()。

参见

Result.one()

Result.scalars()

method scalar_one_or_none() → Any | None

继承自 Result.scalar_one_or_none() 方法的 Result

返回确切的一个标量结果或 None。

这等同于调用 Result.scalars() 然后调用 Result.one_or_none()。

参见

Result.one_or_none()

Result.scalars()

method scalars(index: _KeyIndexType = 0) → ScalarResult[Any]

继承自 Result.scalars() 方法的 Result

返回一个 ScalarResult 过滤对象，该对象将返回单个元素而不是 Row 对象。

例如：

>>> result = conn.execute(text("select int_id from table"))
>>> result.scalars().all()
[1, 2, 3]

当结果从 ScalarResult 过滤对象中提取时，将返回 Result 将返回的单列行作为列的值。

1.4 版本新增。

参数：

index – 表示要从每行提取的列的整数或行键，默认为 0 表示第一列。

返回：

一个新的 ScalarResult 过滤对象，指向此 Result 对象。

method splice_horizontally(other)

返回一个新的CursorResult，“水平拼接”这个CursorResult的行与另一个CursorResult的行。

提示

此方法用于 SQLAlchemy ORM 的利益，并不适用于一般用途。

“水平拼接”意味着对于第一个和第二个结果集中的每一行，都会产生一个新行，该行将两行连接在一起，然后成为新行。传入的CursorResult必须具有相同数量的行。通常期望两个结果集也来自相同的排序顺序，因为结果行是基于它们在结果中的位置进行拼接的。

预期的用例是，针对不同表的多个 INSERT…RETURNING 语句（肯定需要排序）可以产生一个看起来像这两个表的 JOIN 的单个结果。

例如：

r1 = connection.execute(
    users.insert().returning(
        users.c.user_name,
        users.c.user_id,
        sort_by_parameter_order=True
    ),
    user_values
)
r2 = connection.execute(
    addresses.insert().returning(
        addresses.c.address_id,
        addresses.c.address,
        addresses.c.user_id,
        sort_by_parameter_order=True
    ),
    address_values
)
rows = r1.splice_horizontally(r2).all()
assert (
    rows ==
    [
        ("john", 1, 1, "foo@bar.com", 1),
        ("jack", 2, 2, "bar@bat.com", 2),
    ]
)

2.0 版中的新功能。

另请参阅

CursorResult.splice_vertically()

method splice_vertically(other)

返回一个新的CursorResult，“垂直拼接”，即“扩展”，这个CursorResult的行与另一个CursorResult的行。

提示

此方法用于 SQLAlchemy ORM 的利益，并不适用于一般用途。

“垂直拼接”意味着给定结果的行附加到此游标结果的行。传入的CursorResult必须具有与此CursorResult中列的相同列表和相同顺序的行。

2.0 版中的新功能。

另请参阅

CursorResult.splice_horizontally()

method supports_sane_multi_rowcount()

从方言返回supports_sane_multi_rowcount。

有关背景，请参阅CursorResult.rowcount。

method supports_sane_rowcount()

从方言返回supports_sane_rowcount。

有关背景，请参阅CursorResult.rowcount。

attribute t

继承自 Result 的 Result.t 属性

对返回的行应用“类型化元组”类型过滤器。

Result.t 属性是调用 Result.tuples() 方法的同义词。

新增于版本 2.0。

method tuples() → TupleResult[_TP]

继承自 Result.tuples() 方法的 Result

对返回的行应用“类型化元组”类型过滤器。

此方法在运行时返回相同的 Result 对象，但标注为返回 TupleResult 对象，该对象将指示PEP 484类型工具返回普通类型的 Tuple 实例，而不是行。这允许元组解包和对 Row 对象的 __getitem__ 访问进行类型标注，用于语句本身包含类型信息的情况。

新增于版本 2.0。

返回：

在编写时查看 TupleResult 类型。

另请参阅

Result.t - 缩写同义词

Row._t - Row 版本

method unique(strategy: Callable[[Any], Any] | None = None) → Self

继承自 Result.unique() 方法的 Result

对此 Result 返回的对象应用唯一过滤。

当不带参数应用此过滤器时，返回的行或对象将被过滤，使得每行唯一。用于确定此唯一性的算法默认为整个元组的 Python 哈希标识。在某些情况下，可能会使用专门针对每个实体的哈希方案，例如当使用 ORM 时，将应用一种针对返回对象的主键标识的方案。

唯一过滤器是在所有其他过滤器之后应用的，这意味着如果通过方法如 Result.columns() 或 Result.scalars() 对返回的列进行了细化，唯一性将仅应用于返回的列或列。这将发生在对 Result 对象调用这些方法的顺序无关紧要的情况下。

唯一过滤器还会更改像Result.fetchmany()和Result.partitions()这样的方法的计算。在使用Result.unique()时，这些方法将继续提供请求的行数或对象数，在应用唯一性后。然而，这必然会影响底层游标或数据源的缓冲行为，以便可能需要多次底层调用cursor.fetchmany()，以便累积足够的对象以提供所请求大小的唯一集合。

参数：

策略 – 一个可应用于正在迭代的行或对象的可调用函数，它应返回表示行的唯一值的对象。Python 的set()用于存储这些标识。如果未传递，则使用默认的唯一性策略，该策略可能已由此Result对象的来源组装。

method yield_per(num: int) → Self

将行提取策略配置为一次提取num行。

当在结果对象上进行迭代或以其他方式利用诸如Result.fetchone()这样一次返回一行的方法时，此参数会影响结果的基础行为。来自底层游标或其他数据源的数据将在内存中缓冲多达这么多行，然后缓冲集合将一次提供一行或根据请求提供尽可能多的行。每次缓冲清除时，它将刷新为这么多行或者如果剩余的行数较少，则刷新为剩余的行数。

Result.yield_per()方法通常与Connection.execution_options.stream_results执行选项一起使用，该选项允许使用的数据库方言利用服务器端游标，如果 DBAPI 支持与其默认操作模式不同的特定“服务器端游标”模式。

提示

考虑使用Connection.execution_options.yield_per执行选项，该选项将同时设置Connection.execution_options.stream_results以确保使用服务器端游标，并自动调用Result.yield_per()方法一次性建立固定的行缓冲大小。

Connection.execution_options.yield_per 执行选项适用于 ORM 操作，在 使用 Yield Per 获取大型结果集 中描述了面向 Session 使用的方法。与 Connection 兼容的仅核心版本是 SQLAlchemy 1.4.40 中的新功能。

新版本为 1.4。

参数：

num – 在重新填充缓冲区时每次提取的行数。如果设置为小于 1 的值，则提取下一个缓冲区的所有行。

另请参阅

使用服务器端游标（也称为流式结果） - 描述了 Result.yield_per() 的核心行为

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南 中

class sqlalchemy.engine.FilterResult

一个对 Result 的包装器，返回除 Row 对象以外的对象，例如字典或标量对象。

FilterResult 是额外结果 API 的通用基础，包括 MappingResult、ScalarResult 和 AsyncResult。

成员

close(), closed, yield_per()

类签名

类 sqlalchemy.engine.FilterResult (sqlalchemy.engine.ResultInternal)

method close() → None

关闭此 FilterResult。

新版本为 1.4.43。

attribute closed

如果底层 Result 报告已关闭，则返回 True。

新版本为 1.4.43。

method yield_per(num: int) → Self

配置每次填充缓冲区时获取 num 行的行提取策略。

FilterResult.yield_per() 方法是对 Result.yield_per() 方法的传递。请参阅该方法的文档以获取使用说明。

新版本为 1.4.40：- 添加 FilterResult.yield_per()，以便在所有结果集实现中都可用此方法

另请参阅

使用服务器端游标（即流式结果） - 描述Result.yield_per()的核心行为

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南中的 ORM 查询指南中

class sqlalchemy.engine.FrozenResult

表示一个适用于缓存的“冻结”状态的Result对象。

Result.freeze()方法返回Result对象的FrozenResult对象。

每次将FrozenResult作为可调用对象调用时，都会从固定数据集生成一个新的可迭代的Result对象：

result = connection.execute(query)
frozen = result.freeze()
unfrozen_result_one = frozen()
for row in unfrozen_result_one:
    print(row)
unfrozen_result_two = frozen()
rows = unfrozen_result_two.all()
# ... etc

新版本 1.4 中新增。

另请参见

重新执行语句 - 在 ORM 中的示例用法来实现结果集缓存。

merge_frozen_result() - 将冻结的结果合并回Session的 ORM 函数。

类签名

类sqlalchemy.engine.FrozenResult（typing.Generic）

class sqlalchemy.engine.IteratorResult

从 Python 迭代器或类似行数据的Row对象获取数据的Result。

新版本 1.4 中新增。

成员

关闭

类签名

类sqlalchemy.engine.IteratorResult（sqlalchemy.engine.Result）

attribute closed

如果此IteratorResult已关闭，则返回True。

新版本 1.4.43 中新增。

class sqlalchemy.engine.MergedResult

从任意数量的Result对象合并的Result。

由Result.merge()方法返回。

新版本 1.4 中新增。

类签名

类sqlalchemy.engine.MergedResult（sqlalchemy.engine.IteratorResult）

class sqlalchemy.engine.Result

表示一组数据库结果。

版本 1.4 中的新内容：Result对象为 SQLAlchemy 核心和 SQLAlchemy ORM 提供了一个完全更新的使用模型和调用外观。在核心中，它构成了取代先前ResultProxy接口的CursorResult对象的基础。在使用 ORM 时，通常使用一个称为ChunkedIteratorResult的更高级对象。

注意

在 SQLAlchemy 1.4 及以上版本中，此对象用于由Session.execute()返回的 ORM 结果，可以逐个返回 ORM 映射对象的实例或在元组行内。请注意，与旧的Query对象相比，Result对象不会自动对实例或行进行去重。要在 Python 中对实例或行进行去重，请使用Result.unique()修改器方法。

另请参阅

获取行 - 在 SQLAlchemy 统一教程中

成员

all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), freeze(), keys(), mappings(), merge(), one(), one_or_none(), partitions(), scalar(), scalar_one(), scalar_one_or_none(), scalars(), t, tuples(), unique(), yield_per()

类签名

类sqlalchemy.engine.Result (sqlalchemy.engine._WithKeys, sqlalchemy.engine.ResultInternal)

method all() → Sequence[Row[_TP]]

返回序列中的所有行。

在调用后关闭结果集。后续调用将返回一个空序列。

版本 1.4 中的新内容。

返回：

一系列Row对象。

另请参阅

使用服务器端游标（又名流式结果） - 如何在 Python 中流式传输大型结果集而不完全加载它。

method close() → None

关闭此 Result。

此方法的行为是特定于实现的，并且默认情况下未实现。该方法通常应结束结果对象正在使用的资源，并且还应导致任何后续迭代或行获取引发 ResourceClosedError。

版本 1.4.27 中的新功能：- .close() 以前通常不适用于所有 Result 类，而是仅适用于返回给核心语句执行的 CursorResult。由于几乎所有其他结果对象，即 ORM 使用的结果对象，在任何情况下都在代理 CursorResult，因此这允许从外部外观关闭底层游标结果，以处理 ORM 查询使用了 yield_per 执行选项的情况，其中它不会立即耗尽和自动关闭数据库游标。

attribute closed

如果此 Result 报告已关闭，则返回 True。

版本 1.4.43 中的新功能。

method columns(*col_expressions: _KeyIndexType) → Self

确定应在每行中返回的列。

此方法可用于限制返回的列，以及重新排序它们。给定的表达式列表通常是一系列整数或字符串键名。它们也可以是适当的 ColumnElement 对象，这些对象对应于给定的语句构造。

自版本 2.0 更改：由于 1.4 版本中的一个错误，Result.columns() 方法存在错误行为，即仅使用一个索引调用该方法将导致 Result 对象产生标量值，而不是 Row 对象。在 2.0 版本中，已修正此行为，使得使用单个索引调用 Result.columns() 将产生一个继续生成 Row 对象的 Result 对象，该对象仅包含单个列。

例如：

statement = select(table.c.x, table.c.y, table.c.z)
result = connection.execute(statement)
for z, y in result.columns('z', 'y'):
    # ...

从语句本身使用列对象的示例：

for z, y in result.columns(
        statement.selected_columns.c.z,
        statement.selected_columns.c.y
):
    # ...

版本 1.4 中的新功能。

参数：

*col_expressions – 表示要返回的列。元素可以是整数行索引、字符串列名，或者与选择构造对应的适当ColumnElement对象。

返回：

使用给定的修改项返回此Result对象。

method fetchall() → Sequence[Row[_TP]]

Result.all()方法的同义词。

method fetchmany(size: int | None = None) → Sequence[Row[_TP]]

获取多行。

当所有行都已耗尽时，返回一个空序列。

此方法是为了与 SQLAlchemy 1.x.x 向后兼容而提供的。

要以组的形式获取行，请使用Result.partitions()方法。

返回：

一个Row对象的序列。

另请参阅

Result.partitions()

method fetchone() → Row[_TP] | None

获取一行。

当所有行都已耗尽时，返回 None。

此方法是为了与 SQLAlchemy 1.x.x 向后兼容而提供的。

要仅获取结果的第一行，请使用Result.first()方法。要遍历所有行，请直接迭代Result对象。

返回：

如果未应用过滤器，则返回Row对象，如果没有行剩余则返回None。

method first() → Row[_TP] | None

获取第一行或者如果没有行存在则返回None。

关闭结果集并丢弃剩余的行。

注意

默认情况下，此方法返回一个行，例如元组。要返回确切的单个标量值，即第一行的第一列，请使用Result.scalar()方法，或者结合Result.scalars()和Result.first()。

此外，与传统的 ORM Query.first()方法的行为相比，SQL 查询未应用任何限制，以产生此Result; 对于在向 Python 进程发送行之前在内存中缓冲结果的 DBAPI 驱动程序，所有行都将发送到 Python 进程，除了第一行外所有行都将被丢弃。

另请参阅

ORM 查询与核心选择合并

返回：

Row对象，如果没有行剩余则返回 None。

另请参阅

Result.scalar()

Result.one()

method freeze() → FrozenResult[_TP]

返回一个可调用对象，当调用时将产生此Result的副本。

返回的可调用对象是一个FrozenResult的实例。

这用于结果集缓存。当结果尚未被消耗时，必须在结果上调用该方法，并且调用该方法将完全消耗结果。当从缓存中检索到FrozenResult时，可以调用任意次数，它将每次产生一个新的Result对象，针对其存储的行集。

另请参阅

重新执行语句 - 在 ORM 中实现结果集缓存的示例用法。

method keys() → RMKeyView

从 sqlalchemy.engine._WithKeys 的 sqlalchemy.engine._WithKeys.keys 方法继承

返回一个可迭代的视图，该视图会产生每个Row表示的字符串键。

键可以表示核心语句返回的列的标签，或者 ORM 执行返回的 orm 类的名称。

这个视图也可以使用 Python in 运算符进行键包含测试，该运算符将测试视图中表示的字符串键，以及列对象等备用键。

版本 1.4 中的更改：返回一个键视图对象，而不是普通列表。

method mappings() → MappingResult

对返回的行应用映射过滤器，返回一个MappingResult的实例。

应用此过滤器时，获取行将返回RowMapping对象，而不是Row对象。

版本 1.4 中的新内容。

返回：

一个新的指向这个Result对象的MappingResult过滤对象。

method merge(*others: Result[Any]) → MergedResult[_TP]

将此Result与其他兼容的结果对象合并。

返回的对象是一个MergedResult的实例，它将由给定结果对象的迭代器组成。

新的结果将使用此结果对象的元数据。后续结果对象必须针对相同的结果/游标元数据进行，否则行为未定义。

method one() → Row[_TP]

返回一行或抛出异常。

如果结果没有返回任何行，则引发NoResultFound，如果返回多行，则引发MultipleResultsFound。

注意

此方法默认返回一个行，例如元组。要返回确切的单个标量值，即第一行的第一列，请使用Result.scalar_one()方法，或者结合使用Result.scalars()和Result.one()。

版本 1.4 中的新功能。

返回：

第一个Row。

引发：

MultipleResultsFound, NoResultFound

另请参阅

Result.first()

Result.one_or_none()

Result.scalar_one()

method one_or_none() → Row[_TP] | None

返回最多一个结果或引发异常。

如果结果没有行，则返回None。如果返回多行，则引发MultipleResultsFound。

版本 1.4 中的新功能。

返回：

第一个Row或None（如果没有可用行）。

引发：

MultipleResultsFound

另请参阅

Result.first()

Result.one()

method partitions(size: int | None = None) → Iterator[Sequence[Row[_TP]]]

遍历给定大小的子行列表。

每个列表将具有给定的大小，不包括最后一个将被产生的列表，该列表可能有少量行。不会产生空列表。

当迭代器完全消耗时，结果对象将自动关闭。

请注意，除非使用了Connection.execution_options.stream_results执行选项指示驱动程序不应预先缓冲结果，否则后端驱动程序通常会预先缓冲整个结果。并非所有驱动程序都支持此选项，对于不支持的驱动程序，该选项将被静默忽略。

在使用 ORM 时，当与 yield_per 执行选项结合使用时，Result.partitions()方法通常在内存方面更有效，该选项指示 DBAPI 驱动程序使用服务器端游标（如果可用），以及指示 ORM 加载内部一次只构建某些数量的 ORM 对象结果然后将其输出。

新版本中新增。

参数：

size – 指示每个生成的列表中应存在的最大行数。如果为 None，则使用 Result.yield_per() 设置的值（如果调用了该方法），或者 Connection.execution_options.yield_per 执行选项，在这方面是等效的。如果未设置 yield_per，则使用 Result.fetchmany() 的默认值，该值可能是特定于后端并且未明确定义的。

返回：

列表的迭代器

另请参阅

使用服务器端游标（也称为流式结果）

使用 Yield Per 获取大型结果集 - 在 ORM 查询指南 中

method scalar() → Any

获取第一行的第一列，并关闭结果集。

如果没有要提取的行，则返回None。

不执行任何验证以测试是否存在其他行。

调用此方法后，对象将完全关闭，例如 CursorResult.close() 方法将被调用。

返回：

一个 Python 标量值，或者如果没有剩余行，则为None。

method scalar_one() → Any

返回确切的一个标量结果或引发异常。

这等同于调用 Result.scalars() 然后调用 Result.one()。

另请参阅

Result.one()

Result.scalars()

method scalar_one_or_none() → Any | None

返回确切的一个标量结果或None。

这相当于调用 Result.scalars() 然后调用 Result.one_or_none()。

另请参阅

Result.one_or_none()

Result.scalars()

method scalars(index: _KeyIndexType = 0) → ScalarResult[Any]

返回一个 ScalarResult 过滤对象，该对象将返回单个元素而不是 Row 对象。

例如：

>>> result = conn.execute(text("select int_id from table"))
>>> result.scalars().all()
[1, 2, 3]

当从 ScalarResult 过滤对象中获取结果时，将返回由 Result 返回的单列行作为列的值。

新版本中新增。

参数：

index – 表示要从每行提取的列的整数或行键，默认为0表示第一列。

返回：

一个新的指向此Result对象的ScalarResult过滤对象。

attribute t

对返回的行应用“类型化元组”类型筛选。

Result.t属性是调用Result.tuples()方法的同义词。

从版本 2.0 开始新增。

method tuples() → TupleResult[_TP]

对返回的行应用“类型化元组”类型筛选。

此方法在运行时返回相同的Result对象，但会注释为返回一个TupleResult对象，这将指示PEP 484类型工具返回普通的类型化Tuple实例而不是行。这允许元组拆包和对Row对象的__getitem__访问进行类型化，对于那些语句本身包含了类型信息的情况。

从版本 2.0 开始新增。

返回：

在编写时引用TupleResult类型。

另见

Result.t - 更短的同义词

Row._t - Row 版本

method unique(strategy: Callable[[Any], Any] | None = None) → Self

对此Result返回的对象应用唯一过滤。

当此过滤器应用时没有参数时，返回的行或对象将被过滤，以确保每行都是唯一的。确定此唯一性的算法默认情况下是整个元组的 Python 哈希标识。在某些情况下，可能会使用专门的每实体哈希方案，例如当使用 ORM 时，将应用一种针对返回对象的主键标识的方案。

唯一过滤器应用在所有其他过滤器之后，这意味着如果返回的列已经通过诸如Result.columns()或Result.scalars()等方法进行了细化，则唯一性仅应用于返回的列或列。这发生在这些方法被调用在Result对象上的任何顺序之后。

唯一过滤器还改变了像Result.fetchmany()和Result.partitions()这样的方法所使用的计算方法。当使用Result.unique()时，这些方法将在应用唯一性后继续返回请求的行数或对象数。然而，这必然会影响底层游标或数据源的缓冲行为，因此可能需要多次底层调用cursor.fetchmany()以累积足够数量的对象，以便提供请求大小的唯一集合。

参数：

strategy – 一个可调用的函数，将应用于正在迭代的行或对象，它应返回一个表示行的唯一值的对象。一个 Python set() 用于存储这些标识。如果未传递，则使用默认的唯一性策略，该策略可能已由此 Result 对象的源代码组装。

method yield_per(num: int) → Self

配置行提取策略以一次提取num行。

这会影响在迭代结果对象或者其他使用Result.fetchone()等返回一行的方法时的底层行为。来自底层游标或其他数据源的数据将被缓冲到内存中的这么多行，并且缓冲集合将以一行或者请求的行数的方式逐行返回。每次缓冲清空时，它将被刷新到这么多行，或者如果剩余行数更少则刷新为剩余行数。

Result.yield_per()方法通常与Connection.execution_options.stream_results执行选项一起使用，该选项允许使用中的数据库方言使用服务器端游标，如果 DBAPI 支持与默认操作模式分离的特定“服务器端游标”模式。

提示

考虑使用Connection.execution_options.yield_per执行选项，它将同时设置Connection.execution_options.stream_results以确保使用服务器端游标，同时自动调用Result.yield_per()方法一次性建立固定的行缓冲区大小。

Connection.execution_options.yield_per 执行选项适用于 ORM 操作，具有在 使用 Yield Per 获取大型结果集 中描述的针对 Session 的用法。仅适用于与 Connection 配合使用的 Core 版本是 SQLAlchemy 1.4.40 的新功能。

自版本 1.4 新增。

SqlAlchemy 2.0 中文文档（四十四）（6）https://developer.aliyun.com/article/1563073