sqlalchemy.engine.result.Result

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Undocumented

Return a safe iterator that yields raw row data.

This is used by the ._engine.Result.merge method to merge multiple compatible results together.

Undocumented

Return all rows in a list.

Closes the result set after invocation. Subsequent invocations will return an empty list.

close this _result.Result.

The behavior of this method is implementation specific, and is not implemented by default. The method should generally end the resources in use by the result object and also cause any subsequent iteration or row fetching to raise .ResourceClosedError.

Establish the columns that should be returned in each row.

This method may be used to limit the columns returned as well as to reorder them. The given list of expressions are normally a series of integers or string key names. They may also be appropriate .ColumnElement objects which correspond to a given statement construct.

E.g.:

statement = select(table.c.x, table.c.y, table.c.z)
result = connection.execute(statement)

for z, y in result.columns('z', 'y'):
    # ...

Example of using the column objects from the statement itself:

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

Fetch many rows.

When all rows are exhausted, returns an empty list.

This method is provided for backwards compatibility with SQLAlchemy 1.x.x.

To fetch rows in groups, use the ._result.Result.partitions method.

Fetch one row.

When all rows are exhausted, returns None.

This method is provided for backwards compatibility with SQLAlchemy 1.x.x.

To fetch the first row of a result only, use the _engine.Result.first method. To iterate through all rows, iterate the _engine.Result object directly.

Fetch the first row or None if no row is present.

Closes the result set and discards remaining rows.

Return a callable object that will produce copies of this .Result when invoked.

The callable object returned is an instance of _engine.FrozenResult.

This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method will consume the result fully. When the _engine.FrozenResult is retrieved from a cache, it can be called any number of times where it will produce a new _engine.Result object each time against its stored set of rows.

Apply a mappings filter to returned rows, returning an instance of _result.MappingResult.

When this filter is applied, fetching rows will return .RowMapping objects instead of .Row objects.

Merge this .Result with other compatible result objects.

The object returned is an instance of _engine.MergedResult, which will be composed of iterators from the given result objects.

The new result will use the metadata from this result object. The subsequent result objects must be against an identical set of result / cursor metadata, otherwise the behavior is undefined.

Undocumented

Return exactly one row or raise an exception.

Raises .NoResultFound if the result returns no rows, or .MultipleResultsFound if multiple rows would be returned.

Return at most one result or raise an exception.

Returns None if the result has no rows. Raises .MultipleResultsFound if multiple rows are returned.

Iterate through sub-lists of rows of the size given.

Each list will be of the size given, excluding the last list to be yielded, which may have a small number of rows. No empty lists will be yielded.

The result object is automatically closed when the iterator is fully consumed.

Note that the backend driver will usually buffer the entire result ahead of time unless the :paramref:`.Connection.execution_options.stream_results` execution option is used indicating that the driver should not pre-buffer results, if possible. Not all drivers support this option and the option is silently ignored for those who do not.

Fetch the first column of the first row, and close the result set.

Returns None if there are no rows to fetch.

No validation is performed to test if additional rows remain.

After calling this method, the object is fully closed, e.g. the _engine.CursorResult.close method will have been called.

Return exactly one scalar result or raise an exception.

This is equivalent to calling .Result.scalars and then .Result.one.

Return exactly one or no scalar result.

This is equivalent to calling .Result.scalars and then .Result.one_or_none.

Return a _result.ScalarResult filtering object which will return single elements rather than _row.Row objects.

E.g.:

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

When results are fetched from the _result.ScalarResult filtering object, the single column-row that would be returned by the _result.Result is instead returned as the column's value.

Apply unique filtering to the objects returned by this _engine.Result.

When this filter is applied with no arguments, the rows or objects returned will filtered such that each row is returned uniquely. The algorithm used to determine this uniqueness is by default the Python hashing identity of the whole tuple. In some cases a specialized per-entity hashing scheme may be used, such as when using the ORM, a scheme is applied which works against the primary key identity of returned objects.

The unique filter is applied after all other filters, which means if the columns returned have been refined using a method such as the _engine.Result.columns or _engine.Result.scalars method, the uniquing is applied to only the column or columns returned. This occurs regardless of the order in which these methods have been called upon the _engine.Result object.

The unique filter also changes the calculus used for methods like _engine.Result.fetchmany and _engine.Result.partitions. When using _engine.Result.unique, these methods will continue to yield the number of rows or objects requested, after uniquing has been applied. However, this necessarily impacts the buffering behavior of the underlying cursor or datasource, such that multiple underlying calls to cursor.fetchmany() may be necessary in order to accumulate enough objects in order to provide a unique collection of the requested size.

Configure the row-fetching strategy to fetch num rows at a time.

This impacts the underlying behavior of the result when iterating over the result object, or otherwise making use of methods such as _engine.Result.fetchone that return one row at a time. Data from the underlying cursor or other data source will be buffered up to this many rows in memory, and the buffered collection will then be yielded out one row at at time or as many rows are requested. Each time the buffer clears, it will be refreshed to this many rows or as many rows remain if fewer remain.

The _engine.Result.yield_per method is generally used in conjunction with the :paramref:`_engine.Connection.execution_options.stream_results` execution option, which will allow the database dialect in use to make use of a server side cursor, if the DBAPI supports it.

Most DBAPIs do not use server side cursors by default, which means all rows will be fetched upfront from the database regardless of the _engine.Result.yield_per setting. However, _engine.Result.yield_per may still be useful in that it batches the SQLAlchemy-side processing of the raw data from the database, and additionally when used for ORM scenarios will batch the conversion of database rows into ORM entity rows.