Statements & Stack¶

from sqlspec.core import (
    SQL,
    ExplainFormat,
    ExplainOptions,
    ProcessedState,
    StackExecutionMetrics,
    StackOperation,
    Statement,
    StatementConfig,
    StatementStack,
    get_default_config,
    get_default_parameter_config,
)

SQL statement encapsulation, dialect configuration, batched StatementStack pipelines, and EXPLAIN options. See Querying and Transactions for usage examples.

Statement & Configuration¶

SQL ¶

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.

sql ¶

sql

Get the raw SQL string (alias of :attr:raw_sql).

raw_sql ¶

raw_sql

Get raw SQL string (public API).

Returns:

Type	Description
`str`	The raw SQL string

parameters ¶

parameters

Get the values that will be bound to the statement.

dialect ¶

dialect

SQL dialect.

compile ¶

compile()

Compile SQL statement with parameters.

Returns:

Type	Description
`tuple[str, Any]`	Tuple of compiled SQL string and execution parameters

paginate ¶

paginate(page, page_size)

Add LIMIT and OFFSET for pagination.

Parameters:

Name	Type	Description	Default
`page`	`int`	Page number (1-indexed)	required
`page_size`	`int`	Number of items per page	required

Returns:

Type	Description
`SQL`	New SQL instance with LIMIT and OFFSET applied

Statement ¶

Statement = str | exp.Expr | SQL

StatementConfig ¶

Configuration for SQL statement processing.

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

ProcessedState ¶

Processing results for SQL statements.

Contains the compiled SQL, execution parameters, parsed expression, operation type, and validation errors for a processed SQL statement.

get_default_config ¶

get_default_config()

Get default statement configuration.

Returns:

Type	Description
`StatementConfig`	Cached StatementConfig singleton with default settings.

get_default_parameter_config ¶

get_default_parameter_config()

Get default parameter configuration.

Returns:

Type	Description
`ParameterStyleConfig`	ParameterStyleConfig with QMARK style as default

Statement Stacks¶

StatementStack ¶

Immutable builder that preserves ordered SQL operations.

push_execute ¶

push_execute(statement, /, *parameters, statement_config=None, **kwargs)

push_execute_many ¶

push_execute_many(
    statement, parameter_sets, /, *filters, statement_config=None, **kwargs
)

push_execute_script ¶

push_execute_script(statement, /, *parameters, statement_config=None, **kwargs)

extend ¶

extend(*stacks)

StackOperation ¶

Single SQL operation captured inside a statement stack.

StackExecutionMetrics ¶

Capture telemetry facts about a stack execution.

Explain Options¶

ExplainOptions ¶

Configuration options for EXPLAIN statements.

Encapsulates all possible EXPLAIN options across different database dialects. Not all options are supported by all databases - the builder will select appropriate options based on the target dialect.

PostgreSQL Options

analyze: Execute the statement and show actual runtime statistics verbose: Show additional information (schema-qualified names, etc.) costs: Include estimated costs (default True in PostgreSQL) buffers: Include buffer usage information (requires ANALYZE) timing: Include actual timing information (requires ANALYZE) summary: Include summary information after the query plan memory: Include memory usage information (PostgreSQL 17+) settings: Include configuration parameter information (PostgreSQL 12+) wal: Include WAL usage information (requires ANALYZE, PostgreSQL 13+) generic_plan: Generate a generic plan ignoring parameter values (PostgreSQL 16+) format: Output format (TEXT, JSON, XML, YAML)

MySQL Options

analyze: Execute and show actual statistics (always uses TREE format) format: Output format (TRADITIONAL, JSON, TREE)

SQLite

Only supports EXPLAIN QUERY PLAN (no additional options)

DuckDB

analyze: Execute and show actual statistics format: Output format (TEXT, JSON)

Oracle

Uses EXPLAIN PLAN FOR + DBMS_XPLAN.DISPLAY (special handling)

BigQuery

analyze: Execute and show actual statistics (incurs costs!)

ExplainFormat ¶

Bases: StrEnum

Output formats for EXPLAIN statements.

Different databases support different output formats

TEXT: All databases (default)
JSON: PostgreSQL, MySQL (8.0+), DuckDB
XML: PostgreSQL
YAML: PostgreSQL
TREE: MySQL (8.0+), DuckDB
TRADITIONAL: MySQL (tabular output)