Session

A session gives loaded tables names that SQL queries can use. Start with register_table(), then call sql() to get a PyArrow reader for the result.

The SQL quickstart shows both steps. This reference covers accepted table names, query restrictions, scan settings, and errors.

Session

Session()

Query Delta tables with SQL and read the results as PyArrow batches.

Register tables you have already opened, then call sql(). The package includes the Rust DataFusion engine; you do not need to install the separate datafusion Python package.

Examples:

from delta_arrow_reader import DeltaTable, Session

table = DeltaTable("path/to/table")
session = Session()
session.register_table("events", table)
with session.sql("SELECT COUNT(*) AS rows FROM events") as reader:
    print(reader.read_all().to_pydict())

Register more tables to query them together with a JOIN. Only read-only SQL is supported. Joins, sorts and aggregations can use substantial memory even when you read their output in batches.

register_table

register_table(
    name: str,
    table: DeltaTable,
    *,
    execution_options: ScanExecutionOptions | None = None,
) -> None

Give an opened table a name to use in SQL queries.

Registration reuses the table's prepared file information and connection measurements. It does not read Parquet data or repeat initialization.

Examples:

session.register_table("latest_events", table.refresh())

Parameters:

Name	Type	Description	Default
`name`	`str`	A simple identifier, such as `events` or `order_items`. Start with an ASCII letter or underscore, then use ASCII letters, digits or underscores. SQL keywords and duplicate names are rejected.	required
`table`	`DeltaTable`	The loaded `DeltaTable` snapshot to query. Refreshing the original variable later does not change this registration. Register the refreshed table under a new name or in a new session.	required
`execution_options`	`ScanExecutionOptions \| None`	Read settings for this registration. `None` uses the DataFusion adapter defaults, independently of custom settings passed to `DeltaTable`. Pass a `ScanExecutionOptions` explicitly to override them.	`None`

Raises:

Type	Description
`TypeError`	An argument has the wrong type.
`DeltaReaderError`	Registration fails, including an invalid or duplicate name. The error has phase `datafusion` and code `sql_registration`. A duplicate does not replace the existing table.

sql

sql(query: str) -> pyarrow.RecordBatchReader

Run a read-only SQL query over registered tables.

This call plans the query. Result execution starts when you request the first batch. Use a with block to release resources if you stop early.

Examples:

For a registered events table with a region column:

with session.sql(
    "SELECT region, COUNT(*) AS rows FROM events GROUP BY region"
) as reader:
    for batch in reader:
        print(batch.to_pydict())

Parameters:

Name	Type	Description	Default
`query`	`str`	One read-only SQL statement. Table creation, writes, COPY and session-changing statements are rejected before execution.	required

Returns:

Type	Description
`RecordBatchReader`	An independent PyArrow reader. It retains the session and table snapshots even if those Python variables are deleted.

Raises:

Type	Description
`TypeError`	The query is not a string.
`DeltaReaderError`	The query is invalid, unsupported or cannot be planned, or its schema cannot be exported. Planning failures have phase `datafusion` and code `sql_planning`.

Execution errors are raised by PyArrow while consuming results, with code=sql_execution in the message. A failed reader remains failed. SQL error messages omit query text, literal values and table paths.