Core¶

The core module provides SQL statement handling, parameter conversion, result helpers, and caching utilities used by every driver.

Example¶

core SQL usage¶

from sqlspec import SQLSpec
from sqlspec.adapters.sqlite import SqliteConfig
from sqlspec.core import SQL

db_path = tmp_path / "core_api.db"
spec = SQLSpec()
config = spec.add_config(SqliteConfig(connection_config={"database": str(db_path)}))

with spec.provide_session(config) as session:
    session.execute("create table if not exists notes (id integer primary key, body text)")
    session.execute("insert into notes (body) values ('Note')")
    query = SQL("select id, body from notes where id = :note_id or id = :note_id").select_only("body")
    result = session.execute(query, {"note_id": 1})
    print(result.one_or_none())

SQL Statement¶

class sqlspec.core.statement.SQL[source]¶

Bases: object

SQL statement with parameter and filter support.

Represents a SQL statement that can be compiled with parameters and filters. Supports both positional and named parameters, statement filtering, and various execution modes including batch operations.

__init__(statement, *parameters, statement_config=None, is_many=None, **kwargs)[source]¶

Initialize SQL statement.

Parameters:

statement¶ – SQL string, expression, or existing SQL object
*parameters¶ – Parameters and filters
statement_config¶ – Configuration
is_many¶ – Mark as execute_many operation
**kwargs¶ – Additional parameters

reset()[source]¶

Reset SQL object for reuse in pooling scenarios.

Return type:: None

property sql: str¶: Get the raw SQL string.

property raw_sql: str¶

Get raw SQL string (public API).

Returns:: The raw SQL string

property parameters: Any¶: Get the original parameters.

property positional_parameters: list[TypeAliasForwardRef('typing.Any')]¶: Get positional parameters (public API).

property named_parameters: dict[str, TypeAliasForwardRef('typing.Any')]¶: Get named parameters (public API).

property original_parameters: Any¶: Get original parameters (public API).

property operation_type: Literal['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'COPY', 'COPY_FROM', 'COPY_TO', 'EXECUTE', 'SCRIPT', 'DDL', 'PRAGMA', 'MERGE', 'COMMAND', 'UNKNOWN']¶: SQL operation type.

property statement_config: StatementConfig¶: Statement configuration.

property expression: Expression | None¶: SQLGlot expression.

property raw_expression: Expression | None¶: Original expression supplied at construction, if available.

property filters: list[StatementFilter]¶: Applied filters.

get_filters_view()[source]¶

Get zero-copy filters view (public API).

Return type:: FiltersView
Returns:: Read-only view of filters without copying

property is_processed: bool¶: Check if SQL has been processed (public API).

get_processed_state()[source]¶

Get processed state (public API).

Return type:: Any

property dialect: str | None¶: SQL dialect.

property statement_expression: Expression | None¶

Get parsed statement expression (public API).

Returns:: Parsed SQLGlot expression or None if not parsed

property is_many: bool¶: Check if this is execute_many.

property is_script: bool¶: Check if this is script execution.

property validation_errors: list[str]¶: Validation errors.

property has_errors: bool¶: Check if there are validation errors.

returns_rows()[source]¶

Check if statement returns rows.

Return type:: bool
Returns:: True if the SQL statement returns result rows

is_modifying_operation()[source]¶

Check if the SQL statement is a modifying operation.

Return type:: bool
Returns:: True if the operation modifies data (INSERT/UPDATE/DELETE)

compile()[source]¶

Compile SQL statement with parameters.

Return type:: tuple[str, typing.Any]
Returns:: Tuple of compiled SQL string and execution parameters

as_script()[source]¶

Create copy marked for script execution.

Return type:: SQL
Returns:: New SQL instance configured for script execution

copy(statement=None, parameters=None, **kwargs)[source]¶

Create copy with modifications.

Parameters:

statement¶ (str | Expression | None) – New SQL statement to use
parameters¶ (Any | None) – New parameters to use
**kwargs¶ (Any) – Additional modifications

Return type:

SQL

Returns:

New SQL instance with modifications applied

add_named_parameter(name, value)[source]¶

Add a named parameter and return a new SQL instance.

Parameters:

name¶ (str) – Parameter name
value¶ (Any) – Parameter value

Return type:

SQL

Returns:

New SQL instance with the added parameter

where(condition)[source]¶

Add WHERE condition to the SQL statement.

Parameters:: condition¶ (str | Expression) – WHERE condition as string or SQLGlot expression
Return type:: SQL
Returns:: New SQL instance with the WHERE condition applied

where_eq(column, value)[source]¶

Add WHERE column = value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_neq(column, value)[source]¶

Add WHERE column != value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_lt(column, value)[source]¶

Add WHERE column < value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_lte(column, value)[source]¶

Add WHERE column <= value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_gt(column, value)[source]¶

Add WHERE column > value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_gte(column, value)[source]¶

Add WHERE column >= value condition.

Parameters:

column¶ (str | Column) – Column name or expression
value¶ (Any) – Value to compare against

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_like(column, pattern)[source]¶

Add WHERE column LIKE pattern condition.

Parameters:

column¶ (str | Column) – Column name or expression
pattern¶ (str) – LIKE pattern (e.g., ‘%search%’)

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_ilike(column, pattern)[source]¶

Add WHERE column ILIKE pattern condition (case-insensitive).

Parameters:

column¶ (str | Column) – Column name or expression
pattern¶ (str) – ILIKE pattern (e.g., ‘%search%’)

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_is_null(column)[source]¶

Add WHERE column IS NULL condition.

Parameters:: column¶ (str | Column) – Column name or expression
Return type:: SQL
Returns:: New SQL instance with WHERE condition applied

where_is_not_null(column)[source]¶

Add WHERE column IS NOT NULL condition.

Parameters:: column¶ (str | Column) – Column name or expression
Return type:: SQL
Returns:: New SQL instance with WHERE condition applied

where_in(column, values)[source]¶

Add WHERE column IN (values) condition.

Parameters:

column¶ (str | Column) – Column name or expression
values¶ (Sequence[typing.Any]) – Sequence of values for IN clause

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_not_in(column, values)[source]¶

Add WHERE column NOT IN (values) condition.

Parameters:

column¶ (str | Column) – Column name or expression
values¶ (Sequence[typing.Any]) – Sequence of values for NOT IN clause

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

where_between(column, low, high)[source]¶

Add WHERE column BETWEEN low AND high condition.

Parameters:

column¶ (str | Column) – Column name or expression
low¶ (Any) – Lower bound value
high¶ (Any) – Upper bound value

Return type:

SQL

Returns:

New SQL instance with WHERE condition applied

order_by(*items, desc=False)[source]¶

Add ORDER BY clause to the SQL statement.

Parameters:

*items¶ (str | Expression) – ORDER BY expressions as strings or SQLGlot expressions
desc¶ (bool) – Apply descending order to each item

Return type:

SQL

Returns:

New SQL instance with ORDER BY applied

limit(value)[source]¶

Add LIMIT clause to the SQL statement.

Parameters:: value¶ (int) – Maximum number of rows to return
Return type:: SQL
Returns:: New SQL instance with LIMIT applied
Raises:: SQLSpecError – If statement is not a SELECT

offset(value)[source]¶

Add OFFSET clause to the SQL statement.

Parameters:: value¶ (int) – Number of rows to skip
Return type:: SQL
Returns:: New SQL instance with OFFSET applied
Raises:: SQLSpecError – If statement is not a SELECT

paginate(page, page_size)[source]¶

Add LIMIT and OFFSET for pagination.

Parameters:

page¶ (int) – Page number (1-indexed)
page_size¶ (int) – Number of items per page

Return type:

SQL

Returns:

New SQL instance with LIMIT and OFFSET applied

Example

# Get page 3 with 20 items per page stmt = SQL(“SELECT * FROM users”).paginate(3, 20) # Results in: SELECT * FROM users LIMIT 20 OFFSET 40

select_only(*columns, prune_columns=None)[source]¶

Replace SELECT columns with only the specified columns.

This is useful for narrowing down the columns returned by a query without modifying the FROM clause or WHERE conditions.

Parameters:

*columns¶ (str | Expression) – Column names or expressions to select
prune_columns¶ (bool | None) – Remove unused columns from subqueries. When True, applies SQLGlot’s qualify and pushdown_projections optimizations. Defaults to the config’s enable_column_pruning setting.

Return type:

SQL

Returns:

New SQL instance with only the specified columns

Example

stmt = SQL(“SELECT * FROM users WHERE active = 1”) narrow = stmt.select_only(“id”, “name”, “email”) # Results in: SELECT id, name, email FROM users WHERE active = 1

# With column pruning on a subquery: stmt = SQL(“SELECT * FROM (SELECT id, name, email, created_at FROM users) AS u”) narrow = stmt.select_only(“id”, “name”, prune_columns=True) # Results in: SELECT id, name FROM (SELECT id, name FROM users) AS u

explain(analyze=False, verbose=False, format=None)[source]¶

Create an EXPLAIN statement for this SQL.

Wraps the current SQL statement in an EXPLAIN clause with dialect-aware syntax generation.

Parameters:

analyze¶ (bool) – Execute the statement and show actual runtime statistics
verbose¶ (bool) – Show additional information
format¶ (str | None) – Output format (TEXT, JSON, XML, YAML, TREE, TRADITIONAL)

Return type:

SQL

Returns:

New SQL instance containing the EXPLAIN statement

Examples

Basic EXPLAIN:: stmt = SQL(“SELECT * FROM users”) explain_stmt = stmt.explain()
With options:: explain_stmt = stmt.explain(analyze=True, format=”json”)

builder(dialect=None)[source]¶

Create a query builder seeded from this SQL statement.

Parameters:: dialect¶ (Union[str, Dialect, Type[Dialect], None]) – Optional SQL dialect override for parsing and rendering.
Return type:: QueryBuilder
Returns:: QueryBuilder instance initialized with the parsed statement.
Raises:: SQLBuilderError – If the statement cannot be parsed.

Notes

Statements outside the DML set return an ExpressionBuilder without DML-specific helper methods.

__hash__()[source]¶

Hash value computation.

Return type:: int

__eq__(other)[source]¶

Equality comparison.

Return type:: bool

__repr__()[source]¶

String representation.

Return type:: str

class sqlspec.core.statement.StatementConfig[source]¶

Bases: object

Configuration for SQL statement processing.

Controls SQL parsing, validation, transformations, parameter handling, and other processing options for SQL statements.

__init__(parameter_config=None, enable_parsing=True, enable_validation=True, enable_transformations=True, enable_analysis=False, enable_expression_simplification=False, enable_column_pruning=False, enable_parameter_type_wrapping=True, enable_caching=True, parameter_converter=None, parameter_validator=None, dialect=None, execution_mode=None, execution_args=None, output_transformer=None, statement_transformers=None)[source]¶

Initialize StatementConfig.

Parameters:

parameter_config¶ – Parameter style configuration
enable_parsing¶ – Enable SQL parsing
enable_validation¶ – Run SQL validators
enable_transformations¶ – Apply SQL transformers
enable_analysis¶ – Run SQL analyzers
enable_expression_simplification¶ – Apply expression simplification
enable_column_pruning¶ – Remove unused columns from subqueries during select_only
enable_parameter_type_wrapping¶ – Wrap parameters with type information
enable_caching¶ – Cache processed SQL statements
parameter_converter¶ – Handles parameter style conversions
parameter_validator¶ – Validates parameter usage and styles
dialect¶ – SQL dialect
execution_mode¶ – Special execution mode
execution_args¶ – Arguments for special execution modes
output_transformer¶ – Optional output transformation function
statement_transformers¶ – Optional AST transformers executed during compilation

enable_parsing¶

enable_validation¶

enable_transformations¶

enable_analysis¶

enable_expression_simplification¶

enable_column_pruning¶

enable_parameter_type_wrapping¶

enable_caching¶

parameter_converter¶

parameter_validator¶

parameter_config¶

dialect¶

execution_mode¶

execution_args¶

output_transformer¶

statement_transformers¶

freeze()[source]¶

Mark the configuration as immutable to enable caching.

Return type:: None

replace(**kwargs)[source]¶

Immutable update pattern.

Parameters:: **kwargs¶ (Any) – Attributes to update
Return type:: StatementConfig
Returns:: New StatementConfig instance with updated attributes

__hash__()[source]¶

Hash based on configuration settings.

Return type:: int

__repr__()[source]¶

String representation of the StatementConfig instance.

Return type:: str

__eq__(other)[source]¶

Equality comparison.

Return type:: bool

Parameter Handling¶

class sqlspec.core.parameters.ParameterProcessor[source]¶

Bases: object

Parameter processing engine coordinating conversion phases.

DEFAULT_CACHE_SIZE = 1000¶

__init__(*, converter=None, validator=None, cache_max_size=None, validator_cache_max_size=None)[source]¶

clear_cache()[source]¶

Clear cached processing results and reset stats.

Return type:: None

cache_stats()[source]¶

Return cache statistics for parameter processing.

Return type:: dict[str, int]

process(sql, parameters, config, dialect=None, is_many=False, wrap_types=True, param_fingerprint=None)[source]¶

Return type:: ParameterProcessingResult

process_for_execution(sql, parameters, config, dialect=None, is_many=False, wrap_types=True, parsed_expression=None, param_fingerprint=None)[source]¶

Process parameters for execution without parse normalization.

Parameters:

sql¶ (str) – SQL string to process.
parameters¶ (sqlspec.core.parameters.ParameterPayload) – Parameter payload.
config¶ (ParameterStyleConfig) – Parameter style configuration.
dialect¶ (str | None) – Optional SQL dialect.
is_many¶ (bool) – Whether this is execute_many.
wrap_types¶ (bool) – Whether to wrap parameters with type metadata.
parsed_expression¶ (Any) – Pre-parsed SQLGlot expression to preserve through pipeline.
param_fingerprint¶ (Any | None) – Pre-computed parameter fingerprint for cache key.

Return type:

ParameterProcessingResult

Returns:

ParameterProcessingResult with execution SQL and parameters.

class sqlspec.core.parameters.ParameterConverter[source]¶

Bases: object

Parameter style conversion helper.

__init__(validator=None)[source]¶

validator¶

convert_placeholder_style(sql, parameters, target_style, is_many=False, *, strict_named_parameters=True)[source]¶

Return type:: tuple[str, dict[str, typing.Any] | list[typing.Any] | tuple[typing.Any, ...] | None]

class sqlspec.core.parameters.ParameterValidator[source]¶

Bases: object

Extracts placeholder metadata and dialect compatibility information.

__init__(cache_max_size=5000)[source]¶

set_cache_max_size(cache_max_size)[source]¶

Update the maximum cache size for parameter metadata.

Return type:: None

clear_cache()[source]¶

Clear cached parameter metadata and reset stats.

Return type:: None

cache_stats()[source]¶

Return cache statistics.

Return type:: dict[str, int]

extract_parameters(sql)[source]¶

Extract ordered parameter metadata from SQL text.

Return type:: list[ParameterInfo]

class sqlspec.core.parameters.ParameterStyleConfig[source]¶

Bases: object

Configuration describing parameter behaviour for a statement.

__init__(default_parameter_style, supported_parameter_styles=None, supported_execution_parameter_styles=None, default_execution_parameter_style=None, type_coercion_map=None, has_native_list_expansion=False, needs_static_script_compilation=False, allow_mixed_parameter_styles=False, preserve_parameter_format=True, preserve_original_params_for_many=False, output_transformer=None, ast_transformer=None, json_serializer=None, json_deserializer=None, strict_named_parameters=True)[source]¶

default_parameter_style¶

supported_parameter_styles¶

supported_execution_parameter_styles¶

default_execution_parameter_style¶

type_coercion_map¶

has_native_list_expansion¶

output_transformer¶

ast_transformer¶

needs_static_script_compilation¶

allow_mixed_parameter_styles¶

preserve_parameter_format¶

preserve_original_params_for_many¶

strict_named_parameters¶

json_serializer¶

json_deserializer¶

hash()[source]¶

Return the hash value for caching compatibility.

Return type:: int
Returns:: Hash value matching hash() output for this config.

replace(**overrides)[source]¶

Return type:: ParameterStyleConfig

with_json_serializers(serializer, *, tuple_strategy='list', deserializer=None)[source]¶: Return a copy configured with JSON serializers for complex parameters.

class sqlspec.core.parameters.ParameterStyle[source]¶

Bases: str, Enum

Enumeration of supported SQL parameter placeholder styles.

NONE = 'none'¶

STATIC = 'static'¶

QMARK = 'qmark'¶

NUMERIC = 'numeric'¶

NAMED_COLON = 'named_colon'¶

POSITIONAL_COLON = 'positional_colon'¶

NAMED_AT = 'named_at'¶

NAMED_DOLLAR = 'named_dollar'¶

NAMED_PYFORMAT = 'pyformat_named'¶

POSITIONAL_PYFORMAT = 'pyformat_positional'¶

__new__(value)¶

Result Processing¶

class sqlspec.core.result.SQLResult[source]¶

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.

__init__(statement, data=None, rows_affected=0, last_inserted_id=None, execution_time=None, metadata=None, error=None, operation_type='SELECT', operation_index=None, parameters=None, column_names=None, total_count=None, has_more=False, inserted_ids=None, statement_results=None, errors=None, total_statements=0, successful_statements=0, row_format='dict')[source]¶

Initialize SQL result.

Parameters:

statement¶ (SQL) – The original SQL statement that was executed.
data¶ (list[typing.Any] | None) – The result data from the operation (raw driver-native format).
rows_affected¶ (int) – Number of rows affected by the operation.
last_inserted_id¶ (int | str | None) – Last inserted ID from the operation.
execution_time¶ (float | None) – Time taken to execute the statement in seconds.
metadata¶ (dict[str, typing.Any] | None) – Additional metadata about the operation.
error¶ (Exception | None) – Exception that occurred during execution.
operation_type¶ (Literal['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'COPY', 'COPY_FROM', 'COPY_TO', 'EXECUTE', 'SCRIPT', 'DDL', 'PRAGMA', 'MERGE', 'COMMAND', 'UNKNOWN']) – Type of SQL operation performed.
operation_index¶ (int | None) – Index of operation in a script.
parameters¶ (Any | None) – Parameters used for the query.
column_names¶ (list[str] | None) – Names of columns in the result set.
total_count¶ (int | None) – Total number of rows in the complete result set.
has_more¶ (bool) – Whether there are additional result pages available.
inserted_ids¶ (list[int | str] | None) – List of IDs from INSERT operations.
statement_results¶ (list[SQLResult] | None) – Results from individual statements in a script.
errors¶ (list[str] | None) – List of error messages for script execution.
total_statements¶ (int) – Total number of statements in a script.
successful_statements¶ (int) – Count of successful statements in a script.
row_format¶ (str) – Format of raw rows - “tuple”, “dict”, or “record”.

error¶

operation_index¶

parameters¶

has_more¶

inserted_ids¶

statement_results¶

errors¶

total_statements¶

successful_statements¶

column_names¶

total_count¶

property operation_type: Literal['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'COPY', 'COPY_FROM', 'COPY_TO', 'EXECUTE', 'SCRIPT', 'DDL', 'PRAGMA', 'MERGE', 'COMMAND', 'UNKNOWN']¶

Get operation type for this result.

Returns:: The type of SQL operation that produced this result.

property raw_data: tuple[list[TypeAliasForwardRef('typing.Any')], list[str]]¶

Zero-copy access to raw driver-native rows and column names.

Returns:: Tuple of (raw_rows, column_names).

get_metadata(key, default=None)[source]¶

Get metadata value by key.

Parameters:

key¶ (str) – The metadata key to retrieve.
default¶ (Any) – Default value if key is not found.

Return type:

Any

Returns:

The metadata value or default.

set_metadata(key, value)[source]¶

Set metadata value by key.

Parameters:

key¶ (str) – The metadata key to set.
value¶ (Any) – The value to set.

Return type:

None

is_success()[source]¶

Check if the operation was successful.

Return type:: bool
Returns:: True if operation was successful, False otherwise.

get_data(*, schema_type=None)[source]¶

Get the data from the result.

For regular operations, returns the list of rows. For script operations, returns a summary dictionary containing execution statistics and results.

Parameters:: schema_type¶ (type[TypeVar(SchemaT)] | None) – Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
Return type:: list[TypeVar(SchemaT)] | list[dict[str, typing.Any]]
Returns:: List of result rows (optionally transformed to schema_type) or script summary.

add_statement_result(result)[source]¶

Add a statement result to the script execution results.

Parameters:: result¶ (SQLResult) – Statement result to add.
Return type:: None

get_total_rows_affected()[source]¶

Get the total number of rows affected across all statements.

Return type:: int
Returns:: Total rows affected.

property num_rows: int¶

Get the number of rows affected (alias for get_total_rows_affected).

Returns:: Total rows affected.

property num_columns: int¶

Get the number of columns in the result data.

Returns:: Number of columns.

get_first(*, schema_type=None)[source]¶

Get the first row from the result, if any.

Parameters:: schema_type¶ (type[TypeVar(SchemaT)] | None) – Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
Return type:: Union[TypeVar(SchemaT), dict[str, typing.Any], None]
Returns:: First row (optionally transformed to schema_type) or None if no data.

get_count()[source]¶

Get the number of rows in the current result set (e.g., a page of data).

Return type:: int
Returns:: Number of rows in current result set.

is_empty()[source]¶

Check if the result set (self.data) is empty.

Return type:: bool
Returns:: True if result set is empty.

get_affected_count()[source]¶

Get the number of rows affected by a DML operation.

Return type:: int
Returns:: Number of affected rows.

was_inserted()[source]¶

Check if this was an INSERT operation.

Return type:: bool
Returns:: True if INSERT operation.

was_updated()[source]¶

Check if this was an UPDATE operation.

Return type:: bool
Returns:: True if UPDATE operation.

was_deleted()[source]¶

Check if this was a DELETE operation.

Return type:: bool
Returns:: True if DELETE operation.

__len__()[source]¶

Get the number of rows in the result set.

Return type:: int
Returns:: Number of rows in the data.

__getitem__(index)[source]¶

Get a row by index.

Parameters:: index¶ (int) – Row index
Return type:: dict[str, typing.Any]
Returns:: The row at the specified index

__iter__()[source]¶

Iterate over the rows in the result.

Return type:: Iterator[dict[str, typing.Any]]
Returns:: Iterator that yields each row as a dictionary

all(*, schema_type=None)[source]¶

Return all rows as a list.

Parameters:: schema_type¶ (type[TypeVar(SchemaT)] | None) – Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
Return type:: list[TypeVar(SchemaT)] | list[dict[str, typing.Any]]
Returns:: List of all rows (optionally transformed to schema_type)

one(*, schema_type=None)[source]¶

Return exactly one row.

Parameters:: schema_type¶ (type[TypeVar(SchemaT)] | None) – Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
Return type:: Union[TypeVar(SchemaT), dict[str, typing.Any]]
Returns:: The single row (optionally transformed to schema_type)
Raises:: ValueError – If no results or more than one result

one_or_none(*, schema_type=None)[source]¶

Return at most one row.

Parameters:: schema_type¶ (type[TypeVar(SchemaT)] | None) – Optional schema type to transform the data into. Supports Pydantic models, dataclasses, msgspec structs, attrs classes, and TypedDict.
Return type:: Union[TypeVar(SchemaT), dict[str, typing.Any], None]
Returns:: The single row (optionally transformed to schema_type) or None if no results
Raises:: ValueError – If more than one result

scalar()[source]¶

Return the first column of the first row.

Return type:: Any
Returns:: The scalar value from first column of first row

scalar_or_none()[source]¶

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

Return type:: Any
Returns:: The scalar value from first column of first row, or None

to_arrow()[source]¶

Convert result data to Apache Arrow Table.

Return type:: Table
Returns:: Arrow Table containing the result data.
Raises:: ValueError – If no data available.

Examples

>>> result = session.select("SELECT * FROM users")
>>> table = result.to_arrow()
>>> print(table.num_rows)
3

to_pandas()[source]¶

Convert result data to pandas DataFrame.

Return type:: DataFrame
Returns:: pandas DataFrame containing the result data.
Raises:: ValueError – If no data available.

Examples

>>> result = session.select("SELECT * FROM users")
>>> df = result.to_pandas()
>>> print(df.head())

to_polars()[source]¶

Convert result data to Polars DataFrame.

Return type:: DataFrame
Returns:: Polars DataFrame containing the result data.
Raises:: ValueError – If no data available.

Examples

>>> result = session.select("SELECT * FROM users")
>>> df = result.to_polars()
>>> print(df.head())

write_to_storage_sync(destination, *, format_hint=None, storage_options=None, pipeline=None)[source]¶

Return type:: StorageTelemetry

async write_to_storage_async(destination, *, format_hint=None, storage_options=None, pipeline=None)[source]¶

Return type:: StorageTelemetry

SQLSpec results expose helper methods like all(), one(), one_or_none(), scalar(), to_pandas(), and to_arrow() for structured access.