Protocols

Protocol definitions and runtime-checkable interfaces used across SQLSpec's core, drivers, builder, and data dictionary.

Statement and Query Protocols

class sqlspec.protocols.StatementProtocol

Bases: Protocol

Protocol for statement attribute access.

__init__(*args, **kwargs)

class sqlspec.protocols.SQLBuilderProtocol

Bases: Protocol

Protocol for SQL query builders.

property parameters: dict[str, Any]

Public access to query parameters.

get_expression()

Return the current SQLGlot expression.

Return type:

Expr | None

add_parameter(value, name=None)

Add a parameter to the builder.

Return type:

tuple[Any, str]

create_placeholder(value, base_name)

Create placeholder expression with bound parameter (public).

Return type:

tuple[Placeholder, str]

build()

Build and return the final expression.

Return type:

Union[Expr, typing.Any]

set_expression(expression)

Replace the underlying SQLGlot expression.

Return type:

None

generate_unique_parameter_name(base_name)

Generate a unique parameter name exposed via public API.

Return type:

str

build_static_expression(expression=None, parameters=None, *, cache_key=None, expression_factory=None, copy=True, optimize_expression=None, dialect=None)

Compile a pre-built expression with optional caching and parameters.

Return type:

Any

__init__(*args, **kwargs)

class sqlspec.protocols.QueryResultProtocol

Bases: Protocol

Protocol for query execution results.

__init__(*args, **kwargs)

class sqlspec.protocols.PipelineCapableProtocol

Bases: Protocol

Protocol for connections supporting pipeline execution.

__init__(*args, **kwargs)

class sqlspec.protocols.SupportsArrowResults

Bases: Protocol

Protocol for adapters that support Arrow result format.

Adapters implementing this protocol can return query results in Apache Arrow format via the select_to_arrow() method, enabling zero-copy data transfer and efficient integration with data science tools.

select_to_arrow(statement, /, *parameters, statement_config=None, return_format='table', native_only=False, batch_size=None, arrow_schema=None, **kwargs)

Execute query and return results as Apache Arrow Table or RecordBatch.

Parameters:

• statement (Any) -- SQL statement to execute.

• *parameters (Any) -- Query parameters and filters.

• statement_config (Any | None) -- Optional statement configuration override.

• return_format (str) -- Output format - "table", "reader", or "batches".

• native_only (bool) -- If True, raise error when native Arrow path unavailable.

• batch_size (int | None) -- Chunk size for streaming modes.

• arrow_schema (Any | None) -- Optional target Arrow schema for type casting.

• **kwargs (Any) -- Additional keyword arguments.

Return type:

Table | RecordBatch

Returns:

ArrowResult containing Arrow data.

__init__(*args, **kwargs)

Data Dictionary Protocols

class sqlspec.protocols.AsyncDataDictionaryProtocol

Bases: Protocol

Protocol for async data dictionary implementations.

__init__(*args, **kwargs)

class sqlspec.protocols.SyncDataDictionaryProtocol

Bases: Protocol

Protocol for sync data dictionary implementations.

__init__(*args, **kwargs)

Storage and Driver Protocols

class sqlspec.protocols.ObjectStoreProtocol

Bases: Protocol

Protocol for object storage operations.

All synchronous methods use the *_sync suffix for consistency with async methods.

__init__(uri, **kwargs)

resolve_uri(path)

Resolve a backend-relative path to its unsigned address.

Return type:

str

read_bytes_sync(path, **kwargs)

Read bytes from an object synchronously.

Return type:

bytes

write_bytes_sync(path, data, **kwargs)

Write bytes to an object synchronously.

Return type:

None

read_text_sync(path, encoding='utf-8', **kwargs)

Read text from an object synchronously.

Return type:

str

write_text_sync(path, data, encoding='utf-8', **kwargs)

Write text to an object synchronously.

Return type:

None

exists_sync(path, **kwargs)

Check if an object exists synchronously.

Return type:

bool

delete_sync(path, **kwargs)

Delete an object synchronously.

Return type:

None

copy_sync(source, destination, **kwargs)

Copy an object synchronously.

Return type:

None

move_sync(source, destination, **kwargs)

Move an object synchronously.

Return type:

None

list_objects_sync(prefix='', recursive=True, **kwargs)

List objects with optional prefix synchronously.

Return type:

list[str]

glob_sync(pattern, **kwargs)

Find objects matching a glob pattern synchronously.

Return type:

list[str]

is_object_sync(path)

Check if path points to an object synchronously.

Return type:

bool

is_path_sync(path)

Check if path points to a prefix (directory-like) synchronously.

Return type:

bool

get_metadata_sync(path, **kwargs)

Get object metadata synchronously.

Return type:

dict[str, object]

read_arrow_sync(path, **kwargs)

Read an Arrow table from storage synchronously.

Return type:

Table

write_arrow_sync(path, table, **kwargs)

Write an Arrow table to storage synchronously.

Return type:

None

stream_arrow_sync(pattern, *, file_format='parquet', batch_size=65536, **kwargs)

Stream Arrow record batches from matching objects synchronously.

Return type:

Iterator[RecordBatch]

stream_read_sync(path, chunk_size=None, **kwargs)

Stream bytes from an object synchronously.

Return type:

Iterator[bytes]

async read_bytes_async(path, **kwargs)

Async read bytes from an object.

Return type:

bytes

async write_bytes_async(path, data, **kwargs)

Async write bytes to an object.

Return type:

None

async read_text_async(path, encoding='utf-8', **kwargs)

Async read text from an object.

Return type:

str

async write_text_async(path, data, encoding='utf-8', **kwargs)

Async write text to an object.

Return type:

None

async stream_read_async(path, chunk_size=None, **kwargs)

Stream bytes from an object asynchronously.

Return type:

AsyncIterator[bytes]

async exists_async(path, **kwargs)

Async check if an object exists.

Return type:

bool

async delete_async(path, **kwargs)

Async delete an object.

Return type:

None

async list_objects_async(prefix='', recursive=True, **kwargs)

Async list objects with optional prefix.

Return type:

list[str]

async copy_async(source, destination, **kwargs)

Async copy an object.

Return type:

None

async move_async(source, destination, **kwargs)

Async move an object.

Return type:

None

async get_metadata_async(path, **kwargs)

Async get object metadata.

Return type:

dict[str, object]

async read_arrow_async(path, **kwargs)

Async read an Arrow table from storage.

Return type:

Table

async write_arrow_async(path, table, **kwargs)

Async write an Arrow table to storage.

Return type:

None

stream_arrow_async(pattern, *, file_format='parquet', batch_size=65536, **kwargs)

Stream Arrow record batches from matching objects.

Return type:

AsyncIterator[RecordBatch]

property supports_signing: bool

Whether this backend supports URL signing.

Returns:

True if the backend supports generating signed URLs, False otherwise. Only S3, GCS, and Azure backends via obstore support signing.

sign_sync(paths, expires_in=3600, for_upload=False)

Generate signed URL(s) for object(s).

Overloads:

• self, paths (str), expires_in (int), for_upload (bool) → str

• self, paths (list[str]), expires_in (int), for_upload (bool) → list[str]

Parameters:

• paths (str | list[str]) -- Single object path or list of paths to sign.

• expires_in (int) -- URL expiration time in seconds (default: 3600, max: 604800 = 7 days).

• for_upload (bool) -- Whether the URL is for upload (PUT) vs download (GET).

Returns:

Single signed URL string if paths is a string, or list of signed URLs if paths is a list. Preserves input type for convenience.

Raises:

NotImplementedError -- If the backend does not support URL signing.

async sign_async(paths, expires_in=3600, for_upload=False)

Generate signed URL(s) asynchronously.

Overloads:

• self, paths (str), expires_in (int), for_upload (bool) → str

• self, paths (list[str]), expires_in (int), for_upload (bool) → list[str]

Parameters:

• paths (str | list[str]) -- Single object path or list of paths to sign.

• expires_in (int) -- URL expiration time in seconds (default: 3600, max: 604800 = 7 days).

• for_upload (bool) -- Whether the URL is for upload (PUT) vs download (GET).

Returns:

Single signed URL string if paths is a string, or list of signed URLs if paths is a list. Preserves input type for convenience.

Raises:

NotImplementedError -- If the backend does not support URL signing.

class sqlspec.protocols.SupportsCloseProtocol

Bases: Protocol

Protocol for objects exposing close().

__init__(*args, **kwargs)

class sqlspec.protocols.NotificationProtocol

Bases: Protocol

Protocol for database event notifications.

__init__(*args, **kwargs)

class sqlspec.protocols.MappingLikeProtocol

Bases: Protocol

Protocol for objects that can be converted to dict via dict() constructor.

This matches database row types like sqlite3.Row, asyncpg.Record, psycopg.Row that support dictionary-like access with keys() method.

keys()

Return an iterator over the keys.

Return type:

Iterator[str]

__getitem__(key)

Get item by key.

Return type:

Any

__init__(*args, **kwargs)