Results & Pagination¶

from sqlspec.core import (
    ArrowResult,
    CursorPagination,
    DMLResult,
    OffsetPagination,
    Pagination,
    SQLResult,
    StackResult,
    StatementResult,
    create_arrow_result,
    create_sql_result,
)

Result containers for row dictionaries, hydrated schema models, scalar values, Apache Arrow tables/batches, statement stacks, and offset/cursor pagination envelopes. See Querying and Arrow & Storage.

Statement Results¶

StatementResult ¶

Abstract base class for SQL statement execution results.

Provides a common interface for handling different types of SQL operation results. Subclasses implement specific behavior for SELECT, INSERT, UPDATE, DELETE, and script operations.

Attributes:

Name	Type	Description
`data`		The result data from the operation.
`rows_affected`		Number of rows affected by the operation.
`last_inserted_id`		Last inserted ID from INSERT operations.
`execution_time`		Time taken to execute the statement in seconds.
`metadata`		Additional metadata about the operation.

SQLResult ¶

Bases: StatementResult

Result class for SQL operations that return rows or affect rows.

Handles SELECT, INSERT, UPDATE, DELETE operations. For DML operations with RETURNING clauses, the returned data is stored in the data attribute. The operation_type attribute indicates the nature of the operation.

For script execution, tracks multiple statement results and errors.

all ¶

all(*, schema_type=None)

Return all rows as a list.

Parameters:

Name	Type	Description	Default
`schema_type`	`type[SchemaT] \| None`	Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.	`None`

Returns:

Type	Description
`list[SchemaT] \| list[dict[str, Any]]`	List of all rows (optionally transformed to schema_type)

one ¶

one(*, schema_type=None)

Return exactly one row.

Parameters:

Name	Type	Description	Default
`schema_type`	`type[SchemaT] \| None`	Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.	`None`

Returns:

Type	Description
`SchemaT \| dict[str, Any]`	The single row (optionally transformed to schema_type)

Raises:

Type	Description
`ValueError`	If no results or more than one result

one_or_none ¶

one_or_none(*, schema_type=None)

Return at most one row.

Parameters:

Name	Type	Description	Default
`schema_type`	`type[SchemaT] \| None`	Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.	`None`

Returns:

Type	Description
`SchemaT \| dict[str, Any] \| None`	The single row (optionally transformed to schema_type) or None if no results

Raises:

Type	Description
`MultipleResultsFoundError`	If more than one result.

scalar ¶

scalar()

Return the first column of the first row.

Returns:

Type	Description
`Any`	The scalar value from first column of first row

scalar_or_none ¶

scalar_or_none()

Return the first column of the first row, or None if no results.

Returns:

Type	Description
`Any`	The scalar value from first column of first row, or None

to_arrow ¶

to_arrow()

Convert result data to Apache Arrow Table.

Returns:

Type	Description
`ArrowTable`	Arrow Table containing the result data.

Raises:

Type	Description
`ValueError`	If no data available.

to_pandas ¶

to_pandas()

Convert result data to pandas DataFrame.

Returns:

Type	Description
`PandasDataFrame`	pandas DataFrame containing the result data.

Raises:

Type	Description
`ValueError`	If no data available.

to_polars ¶

to_polars()

Convert result data to Polars DataFrame.

Returns:

Type	Description
`PolarsDataFrame`	Polars DataFrame containing the result data.

Raises:

Type	Description
`ValueError`	If no data available.

ArrowResult ¶

Bases: StatementResult

Result class for SQL operations that return Apache Arrow data.

Used when database drivers support returning results in Apache Arrow format for data interchange. Suitable for analytics workloads and data science applications.

Attributes:

Name	Type	Description
`schema`		Arrow schema information for the result data.

DMLResult ¶

Bases: SQLResult

Optimized result for simple DML operations (INSERT/UPDATE/DELETE).

Used by the ultra-fast execution path to bypass full SQLResult construction and pooling for non-SELECT operations.

StackResult ¶

Wrapper for per-operation stack results that surfaces driver results directly.

Pagination Envelopes¶

Pagination ¶

Pagination = CursorPagination[T] | OffsetPagination[T]

OffsetPagination ¶

Bases: Generic[T]

Container for data returned using limit/offset pagination.

Parameters:

Name	Type	Description	Default
`items`	`Sequence[T]`	List of data being sent as part of the response.	required
`limit`	`int`	Maximal number of items to send.	required
`offset`	`int`	Offset from the beginning of the query. Identical to an index.	required
`total`	`int`	Total number of items.	required

CursorPagination ¶

Bases: Generic[T]

Container for data returned using cursor (keyset) pagination.

Parameters:

Name	Type	Description	Default
`items`	`Sequence[T]`	List of data being sent as part of the response.	required
`limit`	`int`	Maximal number of items to send.	required
`next_cursor`	`str \| None`	Token for the next page, or `None` on the last page.	required
`previous_cursor`	`str \| None`	Token for the previous page, or `None` on the first page.	required
`has_next`	`bool`	Whether a page exists after this one.	required
`has_previous`	`bool`	Whether a page exists before this one.	required