sqlalchemy.engine.cursor.CursorResult

class documentation

class CursorResult(BaseCursorResult, Result):

Known subclasses: sqlalchemy.engine.cursor.LegacyCursorResult

A Result that is representing state from a DBAPI cursor.

Changed in version 1.4: The .CursorResult and .LegacyCursorResult classes replace the previous .ResultProxy interface. These classes are based on the .Result calling API which provides an updated usage model and calling facade for SQLAlchemy Core and SQLAlchemy ORM.

Returns database rows via the .Row class, which provides additional API features and behaviors on top of the raw data returned by the DBAPI. Through the use of filters such as the .Result.scalars method, other kinds of objects may also be returned.

Within the scope of the 1.x series of SQLAlchemy, Core SQL results in version 1.4 return an instance of ._engine.LegacyCursorResult which takes the place of the CursorResult class used for the 1.3 series and previously. This object returns rows as .LegacyRow objects, which maintains Python mapping (i.e. dictionary) like behaviors upon the object itself. Going forward, the .Row._mapping attribute should be used for dictionary behaviors.

See Also

:ref:`coretutorial_selecting` - introductory material for accessing _engine.CursorResult and .Row objects.

Method	`_fetchall_impl`	Undocumented
Method	`_fetchiter_impl`	Undocumented
Method	`_fetchmany_impl`	Undocumented
Method	`_fetchone_impl`	Undocumented
Method	`_raw_row_iterator`	Return a safe iterator that yields raw row data.
Method	`close`	Close this `_engine.CursorResult`.
Method	`merge`	Merge this `.Result` with other compatible result objects.
Method	`yield_per`	Configure the row-fetching strategy to fetch num rows at a time.
Instance Variable	`_yield_per`	Undocumented

Inherited from BaseCursorResult:

Method	`__init__`	Undocumented
Method	`_init_metadata`	Undocumented
Method	`_soft_close`	Soft close this `_engine.CursorResult`.
Method	`last_inserted_params`	Return the collection of inserted parameters from this execution.
Method	`last_updated_params`	Return the collection of updated parameters from this execution.
Method	`lastrow_has_defaults`	Return `lastrow_has_defaults()` from the underlying `.ExecutionContext`.
Method	`postfetch_cols`	Return `postfetch_cols()` from the underlying `.ExecutionContext`.
Method	`prefetch_cols`	Return `prefetch_cols()` from the underlying `.ExecutionContext`.
Method	`supports_sane_multi_rowcount`	Return `supports_sane_multi_rowcount` from the dialect.
Method	`supports_sane_rowcount`	Return `supports_sane_rowcount` from the dialect.
Class Variable	`out_parameters`	Undocumented
Instance Variable	`_echo`	Undocumented
Instance Variable	`_metadata`	Undocumented
Instance Variable	`_row_logging_fn`	Undocumented
Instance Variable	`_soft_closed`	Undocumented
Instance Variable	`closed`	Undocumented
Instance Variable	`connection`	Undocumented
Instance Variable	`context`	Undocumented
Instance Variable	`cursor`	Undocumented
Instance Variable	`cursor_strategy`	Undocumented
Instance Variable	`dialect`	Undocumented
Property	`inserted_primary_key`	Return the primary key for the row just inserted.
Property	`inserted_primary_key_rows`	Return the value of `_engine.CursorResult.inserted_primary_key` as a row contained within a list; some dialects may support a multiple row form as well.
Property	`is_insert`	True if this `_engine.CursorResult` is the result of a executing an expression language compiled `_expression.insert` construct.
Property	`lastrowid`	Return the 'lastrowid' accessor on the DBAPI cursor.
Property	`returned_defaults`	Return the values of default columns that were fetched using the `.ValuesBase.return_defaults` feature.
Property	`returned_defaults_rows`	Return a list of rows each containing the values of default columns that were fetched using the `.ValuesBase.return_defaults` feature.
Property	`returns_rows`	True if this `_engine.CursorResult` returns zero or more rows.
Property	`rowcount`	Return the 'rowcount' for this result.

Inherited from Result:

Method	`__init__`	Undocumented
Method	`__iter__`	Undocumented
Method	`__next__`	Undocumented
Method	`_getter`	return a callable that will retrieve the given key from a `.Row`.
Method	`_soft_close`	Undocumented
Method	`_tuple_getter`	return a callable that will retrieve the given keys from a `.Row`.
Method	`all`	Return all rows in a list.
Method	`columns`	Establish the columns that should be returned in each row.
Method	`fetchall`	A synonym for the `_engine.Result.all` method.
Method	`fetchmany`	Fetch many rows.
Method	`fetchone`	Fetch one row.
Method	`first`	Fetch the first row or None if no row is present.
Method	`freeze`	Return a callable object that will produce copies of this `.Result` when invoked.
Method	`mappings`	Apply a mappings filter to returned rows, returning an instance of `_result.MappingResult`.
Method	`next`	Undocumented
Method	`one`	Return exactly one row or raise an exception.
Method	`one_or_none`	Return at most one result or raise an exception.
Method	`partitions`	Iterate through sub-lists of rows of the size given.
Method	`scalar`	Fetch the first column of the first row, and close the result set.
Method	`scalar_one`	Return exactly one scalar result or raise an exception.
Method	`scalar_one_or_none`	Return exactly one or no scalar result.
Method	`scalars`	Return a `_result.ScalarResult` filtering object which will return single elements rather than `_row.Row` objects.
Method	`unique`	Apply unique filtering to the objects returned by this `_engine.Result`.
Class Variable	`_attributes`	Undocumented
Class Variable	`_row_logging_fn`	Undocumented
Class Variable	`_source_supports_scalars`	Undocumented
Instance Variable	`_metadata`	Undocumented
Instance Variable	`_unique_filter_state`	Undocumented

Inherited from _WithKeys (via Result):

Method keys Return an iterable view which yields the string keys that would be represented by each .Row.

Inherited from ResultInternal (via Result):

Method	`_allrows`	Undocumented
Method	`_column_slices`	Undocumented
Method	`_iter_impl`	Undocumented
Method	`_iterator_getter`	Undocumented
Method	`_manyrow_getter`	Undocumented
Method	`_next_impl`	Undocumented
Method	`_onerow_getter`	Undocumented
Method	`_only_one_row`	Undocumented
Method	`_raw_all_rows`	Undocumented
Method	`_row_getter`	Undocumented
Method	`_unique_strategy`	Undocumented
Class Variable	`_post_creational_filter`	Undocumented
Class Variable	`_real_result`	Undocumented
Instance Variable	`_generate_rows`	Undocumented

Inherited from InPlaceGenerative (via Result, ResultInternal):

Method _generate Undocumented

def _fetchall_impl(self):

overrides sqlalchemy.engine.result.Result._fetchall_impl

Undocumented

def _fetchiter_impl(self):

overrides sqlalchemy.engine.result.Result._fetchiter_impl

Undocumented

def _fetchmany_impl(self, size=None):

overrides sqlalchemy.engine.result.Result._fetchmany_impl

Undocumented

def _fetchone_impl(self, hard_close=False):

overrides sqlalchemy.engine.result.Result._fetchone_impl

Undocumented

def _raw_row_iterator(self):

overrides sqlalchemy.engine.result.Result._raw_row_iterator

Return a safe iterator that yields raw row data.

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

def close(self):

overrides sqlalchemy.engine.result.Result.close

overridden in sqlalchemy.engine.cursor.LegacyCursorResult

Close this _engine.CursorResult.

This closes out the underlying DBAPI cursor corresponding to the statement execution, if one is still present. Note that the DBAPI cursor is automatically released when the _engine.CursorResult exhausts all available rows. _engine.CursorResult.close is generally an optional method except in the case when discarding a _engine.CursorResult that still has additional rows pending for fetch.

After this method is called, it is no longer valid to call upon the fetch methods, which will raise a .ResourceClosedError on subsequent use.

See Also

:ref:`connections_toplevel`

def merge(self, *others):

overrides sqlalchemy.engine.result.Result.merge

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.

@_generative
def yield_per(self, num):

overrides sqlalchemy.engine.result.Result.yield_per

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.

New in version 1.4.

Parameters
num	number of rows to fetch each time the buffer is refilled. If set to a value below 1, fetches all rows for the next buffer.

_yield_per =

overrides sqlalchemy.engine.result.Result._yield_per

Undocumented