semolina.cursor

DBAPI 2.0 cursor wrapper with Row convenience methods.

SemolinaCursor delegates to any DBAPI 2.0-compatible cursor and adds fetchall_rows(), fetchmany_rows(), and fetchone_row() that convert raw tuples into Row objects using cursor.description column names.

Classes

SemolinaCursor

DBAPI 2.0 cursor wrapper with Row convenience methods.

Module Contents

class semolina.cursor.SemolinaCursor(cursor: Any, conn: Any, pool: Any)

DBAPI 2.0 cursor wrapper with Row convenience methods.

Wraps any DBAPI 2.0-compatible cursor via delegation. Adds fetchall_rows(), fetchmany_rows(), and fetchone_row() methods that convert DBAPI tuples to Row objects.

Context manager support releases cursor and connection on exit.

fetchall_rows() → list[semolina.results.Row]

Fetch all remaining rows as Row objects.

Returns:

List of Row objects with attribute and dict access.

fetchone_row() → semolina.results.Row | None

Fetch next row as a Row, or None if exhausted.

Returns:

Row object, or None if no rows remain.

fetchmany_rows(size: int = 1) → list[semolina.results.Row]

Fetch up to size rows as Row objects.

Parameters:

size – Maximum number of rows to fetch. Defaults to 1.

Returns:

List of Row objects (may be shorter than size).

fetchall() → list[tuple[Any, Ellipsis]]

Fetch all remaining rows as raw tuples (DBAPI passthrough).

Returns:

List of tuple rows.

fetchone() → tuple[Any, Ellipsis] | None

Fetch next row as raw tuple (DBAPI passthrough).

Returns:

Tuple row, or None if exhausted.

fetchmany(size: int = 1) → list[tuple[Any, Ellipsis]]

Fetch up to size rows as raw tuples (DBAPI passthrough).

Parameters:

size – Maximum number of rows to fetch.

Returns:

List of tuple rows.

fetch_arrow_table() → pyarrow.Table

Fetch all remaining rows as a PyArrow Table (ADBC passthrough).

Delegates to the underlying ADBC cursor’s fetch_arrow_table() method for zero-copy Arrow data transfer.

Requires an ADBC-capable cursor (Snowflake, Databricks, or DuckDB pool connections). Not supported by non-ADBC cursors.

Returns:

pyarrow.Table with the query results.

Raises:

AttributeError – If the underlying cursor does not support fetch_arrow_table() (e.g. a non-ADBC cursor).

Example

cursor = Sales.query().metrics(Sales.revenue).execute()
table = cursor.fetch_arrow_table()
df = table.to_pandas()

fetch_record_batch() → pyarrow.RecordBatchReader

Fetch the result as a PyArrow RecordBatchReader (ADBC passthrough).

Delegates to the underlying ADBC cursor’s fetch_record_batch() method for lazy, memory-bounded streaming consumption of Arrow data.

Requires an ADBC-capable cursor (Snowflake, Databricks, or DuckDB pool connections). Not supported by non-ADBC cursors.

The returned reader shares state with this cursor’s other fetch methods — consume the reader before calling fetchone(), fetch_arrow_table(), or iterating the cursor.

The cursor must outlive the reader: consume the reader inside the context manager (or before .close()). See arrow-adbc issue #1893.

Returns:

pyarrow.RecordBatchReader over the query result.

Raises:

AttributeError – If the underlying cursor does not support fetch_record_batch() (e.g. a non-ADBC cursor).

Example

with Sales.query().metrics(Sales.revenue).execute() as cursor:
    reader = cursor.fetch_record_batch()
    for batch in reader:
        process(batch)

property description: list[tuple[Any, Ellipsis]] | None

Cursor description passthrough.

Returns:

List of 7-element tuples describing columns, or None before execute.

property rowcount: int

Row count passthrough.

Returns:

Number of rows affected by the last operation.

close() → None

Close cursor and release connection.