`adbc_driver_manager`#

Low-Level API#

Low-level ADBC bindings for Python.

The root module provides a fairly direct, 1:1 mapping to the C API definitions in Python. For a higher-level interface, use adbc_driver_manager.dbapi. (This requires PyArrow.)

Constants & Enums#

class adbc_driver_manager.AdbcStatusCode(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: IntEnum

A status code indicating the type of error.

Attributes:

denominator: the denominator of a rational number in lowest terms
imag: the imaginary part of a complex number
numerator: the numerator of a rational number in lowest terms
real: the real part of a complex number

Methods

`as_integer_ratio`(/)	Return integer ratio.
`bit_count`(/)	Number of ones in the binary representation of the absolute value of self.
`bit_length`(/)	Number of bits necessary to represent self in binary.
`conjugate`	Returns self, the complex conjugate of any int.
`from_bytes`(/, bytes[, byteorder, signed])	Return the integer represented by the given array of bytes.
`to_bytes`(/[, length, byteorder, signed])	Return an array of bytes representing an integer.

class adbc_driver_manager.GetObjectsDepth(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: IntEnum

Attributes:

denominator: the denominator of a rational number in lowest terms
imag: the imaginary part of a complex number
numerator: the numerator of a rational number in lowest terms
real: the real part of a complex number

Methods

`as_integer_ratio`(/)	Return integer ratio.
`bit_count`(/)	Number of ones in the binary representation of the absolute value of self.
`bit_length`(/)	Number of bits necessary to represent self in binary.
`conjugate`	Returns self, the complex conjugate of any int.
`from_bytes`(/, bytes[, byteorder, signed])	Return the integer represented by the given array of bytes.
`to_bytes`(/[, length, byteorder, signed])	Return an array of bytes representing an integer.

adbc_driver_manager.INGEST_OPTION_MODE#: Whether to append to or create a new table for bulk ingestion.

adbc_driver_manager.INGEST_OPTION_MODE_APPEND#: Append to the table for bulk ingestion.

adbc_driver_manager.INGEST_OPTION_MODE_CREATE#: Create a new table for bulk ingestion.

adbc_driver_manager.INGEST_OPTION_TARGET_TABLE#: The table to create/append to for bulk ingestion.

Classes#

class adbc_driver_manager.AdbcConnection#

Bases: _AdbcHandle

An active database connection.

Connections are not thread-safe and clients should take care to serialize accesses to a connection.

Parameters:

databaseAdbcDatabase: The database to connect to.
kwargsdict: String key-value options to pass to the underlying database.

Methods

`close`	Release the handle to the connection.
`commit`	Commit the current transaction.
`get_info`	Get metadata about the database/driver.
`get_objects`	Get a hierarchical view of database objects.
`get_table_schema`	Get the Arrow schema of a table.
`get_table_types`	Get the list of supported table types.
`read_partition`	Fetch a single partition from execute_partitions.
`rollback`	Rollback the current transaction.
`set_autocommit`	Toggle whether autocommit is enabled.

close()#: Release the handle to the connection.

commit()#: Commit the current transaction.

get_info()#: Get metadata about the database/driver.

get_objects()#: Get a hierarchical view of database objects.

get_table_schema()#

Get the Arrow schema of a table.

Returns:

ArrowSchemaHandle: A C Data Interface ArrowSchema struct containing the schema.

get_table_types()#: Get the list of supported table types.

read_partition()#: Fetch a single partition from execute_partitions.

rollback()#: Rollback the current transaction.

set_autocommit()#: Toggle whether autocommit is enabled.

class adbc_driver_manager.AdbcDatabase#

Bases: _AdbcHandle

An instance of a database.

Parameters:

kwargsdict: String key-value options to pass to the underlying database. Must include at least “driver” to identify the underlying database driver to load.

Methods

close

Release the handle to the database.

close()#: Release the handle to the database.

class adbc_driver_manager.AdbcStatement#

Bases: _AdbcHandle

A database statement.

Statements are not thread-safe and clients should take care to serialize accesses to a connection.

Parameters:

connectionAdbcConnection: The connection to create the statement for.

Methods

`bind`	Bind an ArrowArray to this statement.
`bind_stream`	Bind an ArrowArrayStream to this statement.
`execute_partitions`	Execute the query and get the partitions of the result set.
`execute_query`	Execute the query and get the result set.
`execute_update`	Execute the query without a result set.
`prepare`	Turn this statement into a prepared statement.
`set_options`	Set arbitrary key-value options.
`set_sql_query`	Set a SQL query to be executed.
`set_substrait_plan`	Set a Substrait plan to be executed.

close

bind()#

Bind an ArrowArray to this statement.

Parameters:

dataint or ArrowArrayHandle
schemaint or ArrowSchemaHandle

bind_stream()#

Bind an ArrowArrayStream to this statement.

Parameters:

streamint or ArrowArrayStreamHandle

execute_partitions()#

Execute the query and get the partitions of the result set.

Not all drivers will support this.

Returns:

list of byte: The partitions of the distributed result set.
ArrowSchemaHandle: The schema of the result set.
int: The number of rows if known, else -1.

execute_query()#

Execute the query and get the result set.

Returns:

ArrowArrayStreamHandle: The result set.
int: The number of rows if known, else -1.

execute_update()#

Execute the query without a result set.

Returns:

int: The number of affected rows if known, else -1.

prepare()#: Turn this statement into a prepared statement.

set_options()#: Set arbitrary key-value options.

set_sql_query()#: Set a SQL query to be executed.

set_substrait_plan()#: Set a Substrait plan to be executed.

class adbc_driver_manager.ArrowArrayHandle#

Bases: object

A wrapper for an allocated ArrowArray.

Attributes:

address: The address of the ArrowArray.

address#: The address of the ArrowArray.

class adbc_driver_manager.ArrowArrayStreamHandle#

Bases: object

A wrapper for an allocated ArrowArrayStream.

Attributes:

address: The address of the ArrowArrayStream.

address#: The address of the ArrowArrayStream.

class adbc_driver_manager.ArrowSchemaHandle#

Bases: object

A wrapper for an allocated ArrowSchema.

Attributes:

address: The address of the ArrowSchema.

address#: The address of the ArrowSchema.

DBAPI 2.0 API#

PEP 249 (DB-API 2.0) API wrapper for the ADBC Driver Manager.

Constants & Enums#

adbc_driver_manager.dbapi.apilevel = '2.0'#: The DB-API API level (2.0).

adbc_driver_manager.dbapi.paramstyle = 'qmark'#: The parameter style (qmark). This is hardcoded, but actually depends on the driver.

adbc_driver_manager.dbapi.threadsafety = 1#: The thread safety level (connections may not be shared).

adbc_driver_manager.dbapi.Date = <class 'datetime.date'>#: The type for date values.

adbc_driver_manager.dbapi.Time = <class 'datetime.time'>#: The type for time values.

adbc_driver_manager.dbapi.Timestamp(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]) = <class 'datetime.datetime'>#: The type for timestamp values.

adbc_driver_manager.dbapi.BINARY = frozenset({14, 35})#: The type of binary columns.

adbc_driver_manager.dbapi.DATETIME = frozenset({16, 17, 18, 19, 20})#: The type of datetime columns.

adbc_driver_manager.dbapi.NUMBER = frozenset({2, 3, 4, 5, 6, 7, 8, 9, 11, 12})#: The type of numeric columns.

adbc_driver_manager.dbapi.ROWID = frozenset({9})#: The type of “row ID” columns.

adbc_driver_manager.dbapi.STRING = frozenset({13, 34})#: The type of string columns.

Functions#

adbc_driver_manager.dbapi.connect(*, driver: str, entrypoint: str = None, db_kwargs: Optional[Dict[str, str]] = None, conn_kwargs: Optional[Dict[str, str]] = None) → Connection#

Connect to a database via ADBC.

Parameters:

driver: The driver name. For example, “adbc_driver_sqlite” will attempt to load libadbc_driver_sqlite.so on Linux systems, libadbc_driver_sqlite.dylib on MacOS, and adbc_driver_sqlite.dll on Windows. This may also be a path to the library to load.
entrypoint: The driver-specific entrypoint, if different than the default.
db_kwargs: Key-value parameters to pass to the driver to initialize the database.
conn_kwargs: Key-value parameters to pass to the driver to initialize the connection.

adbc_driver_manager.dbapi.DateFromTicks(ticks: int) → date#: Construct a date value from a count of seconds.

adbc_driver_manager.dbapi.TimeFromTicks(ticks: int) → date#: Construct a time value from a count of seconds.

adbc_driver_manager.dbapi.TimestampFromTicks(ticks: int) → date#: Construct a timestamp value from a count of seconds.

Classes#

class adbc_driver_manager.dbapi.Connection(db: Union[AdbcDatabase, _SharedDatabase], conn: AdbcConnection, conn_kwargs: Optional[Dict[str, str]] = None)#

Bases: _Closeable

A DB-API 2.0 (PEP 249) connection.

Do not create this object directly; use connect().

Attributes:

adbc_connection: Get the underlying ADBC connection.
adbc_database: Get the underlying ADBC database.

Methods

`adbc_clone`()	Create a new Connection sharing the same underlying database.
`adbc_get_info`()	Get metadata about the database and driver.
`adbc_get_objects`(*[, depth, catalog_filter, ...])	List catalogs, schemas, tables, etc.
`adbc_get_table_schema`(table_name, *[, ...])	Get the Arrow schema of a table by name.
`adbc_get_table_types`()	List the types of tables that the server knows about.
`close`()	Close the connection.
`commit`()	Explicitly commit.
`cursor`()	Create a new cursor for querying the database.
`rollback`()	Explicitly rollback.

adbc_clone() → Connection#

Create a new Connection sharing the same underlying database.

Notes

This is an extension and not part of the DBAPI standard.

property adbc_connection: AdbcConnection#

Get the underlying ADBC connection.

Notes

This is an extension and not part of the DBAPI standard.

property adbc_database: AdbcDatabase#

Get the underlying ADBC database.

Notes

This is an extension and not part of the DBAPI standard.

adbc_get_info() → Dict[Union[str, int], Any]#

Get metadata about the database and driver.

Notes

This is an extension and not part of the DBAPI standard.

adbc_get_objects(*, depth: Literal['all', 'catalogs', 'db_schemas', 'tables', 'columns'] = 'all', catalog_filter: Optional[str] = None, db_schema_filter: Optional[str] = None, table_name_filter: Optional[str] = None, table_types_filter: Optional[List[str]] = None, column_name_filter: Optional[str] = None) → RecordBatchReader#

List catalogs, schemas, tables, etc. in the database.

Parameters:

depth: What objects to return info on.
catalog_filter: An optional filter on the catalog names returned.
db_schema_filter: An optional filter on the database schema names returned.
table_name_filter: An optional filter on the table names returned.
table_types_filter: An optional list of types of tables returned.
column_name_filter: An optional filter on the column names returned.

Notes

This is an extension and not part of the DBAPI standard.

adbc_get_table_schema(table_name: str, *, catalog_filter: Optional[str] = None, db_schema_filter: Optional[str] = None) → Schema#

Get the Arrow schema of a table by name.

Parameters:

table_name: The table to get the schema of.
catalog_filter: An optional filter on the catalog name of the table.
db_schema_filter: An optional filter on the database schema name of the table.

Notes

This is an extension and not part of the DBAPI standard.

adbc_get_table_types() → List[str]#

List the types of tables that the server knows about.

Notes

This is an extension and not part of the DBAPI standard.

close() → None#: Close the connection.

Warning

Failure to close a connection may leak memory or database connections.

commit() → None#: Explicitly commit.

cursor() → Cursor#: Create a new cursor for querying the database.

rollback() → None#: Explicitly rollback.

class adbc_driver_manager.dbapi.Cursor(conn: Connection)#

Bases: _Closeable

A DB-API 2.0 (PEP 249) cursor.

Do not create this object directly; use Connection.cursor().

Attributes:

adbc_statement: Get the underlying ADBC statement.
arraysize: The number of rows to fetch at a time with fetchmany().
connection: Get the connection associated with this cursor.
description: The schema of the result set.
rowcount: Get the row count of the result set, or -1 if not known.
rownumber: Get the current row number, or None if not applicable.

Methods

`adbc_execute_partitions`(operation[, parameters])	Execute a query and get the partitions of a distributed result set.
`adbc_ingest`(table_name, data[, mode])	Ingest Arrow data into a database table.
`adbc_read_partition`(partition)	Read a partition of a distributed result set.
`callproc`(procname, parameters)	Call a stored procedure (not supported).
`close`()	Close the cursor and free resources.
`execute`(operation[, parameters])	Execute a query.
`executemany`(operation, seq_of_parameters)	Execute a query with multiple parameter sets.
`fetch_arrow_table`()	Fetch all rows of the result as a PyArrow Table.
`fetch_df`()	Fetch all rows of the result as a Pandas DataFrame.
`fetchall`()	Fetch all rows of the result.
`fetchallarrow`()	Fetch all rows of the result as a PyArrow Table.
`fetchmany`([size])	Fetch some rows of the result.
`fetchone`()	Fetch one row of the result.
`next`()	Fetch the next row, or raise StopIteration.
`nextset`()	Move to the next available result set (not supported).
`setinputsizes`(sizes)	Preallocate memory for the parameters (no-op).
`setoutputsize`(size[, column])	Preallocate memory for the result set (no-op).

adbc_execute_partitions(operation, parameters=None) → Tuple[List[bytes], Schema]#

Execute a query and get the partitions of a distributed result set.

Parameters:

partitionslist of byte: A list of partition descriptors, which can be read with read_partition.
schemapyarrow.Schema: The schema of the result set.

Notes

This is an extension and not part of the DBAPI standard.

adbc_ingest(table_name: str, data: Union[RecordBatch, Table, RecordBatchReader], mode: Literal['append', 'create'] = 'create') → int#

Ingest Arrow data into a database table.

Depending on the driver, this can avoid per-row overhead that would result from a typical prepare-bind-insert loop.

Parameters:

table_name: The table to insert into.
data: The Arrow data to insert.
mode: Whether to append data to an existing table, or create a new table.

Returns:

int: The number of rows inserted, or -1 if the driver cannot provide this information.

Notes

This is an extension and not part of the DBAPI standard.

adbc_read_partition(partition: bytes) → None#

Read a partition of a distributed result set.

Notes

This is an extension and not part of the DBAPI standard.

property adbc_statement: AdbcStatement#

Get the underlying ADBC statement.

Notes

This is an extension and not part of the DBAPI standard.

property arraysize: int#: The number of rows to fetch at a time with fetchmany().

callproc(procname, parameters)#: Call a stored procedure (not supported).

close()#: Close the cursor and free resources.

property connection: Connection#

Get the connection associated with this cursor.

This is an optional DB-API extension.

property description: Optional[List[tuple]]#: The schema of the result set.

execute(operation: Union[bytes, str], parameters=None) → None#

Execute a query.

Parameters:

operationbytes or str: The query to execute. Pass SQL queries as strings, (serialized) Substrait plans as bytes.
parameters: Parameters to bind. Can be a Python sequence (to provide a single set of parameters), or an Arrow record batch, table, or record batch reader (to provide multiple parameters, which will each be bound in turn).

executemany(operation: Union[bytes, str], seq_of_parameters) → None#

Execute a query with multiple parameter sets.

This method does not generate a result set.

Parameters:

operationbytes or str: The query to execute. Pass SQL queries as strings, (serialized) Substrait plans as bytes.
parameters: Parameters to bind. Can be a list of Python sequences, or an Arrow record batch, table, or record batch reader. If None, then the query will be executed once, else it will be executed once per row.

fetch_arrow_table() → Table#

Fetch all rows of the result as a PyArrow Table.

This implements a similar API as DuckDB.

Notes

This is an extension and not part of the DBAPI standard.

fetch_df() → pandas.DataFrame#

Fetch all rows of the result as a Pandas DataFrame.

This implements a similar API as DuckDB.

Notes

This is an extension and not part of the DBAPI standard.

fetchall() → List[tuple]#: Fetch all rows of the result.

fetchallarrow() → Table#

Fetch all rows of the result as a PyArrow Table.

This implements a similar API as turbodbc.

Notes

This is an extension and not part of the DBAPI standard.

fetchmany(size: Optional[int] = None) → List[tuple]#: Fetch some rows of the result.

fetchone() → tuple#: Fetch one row of the result.

next()#: Fetch the next row, or raise StopIteration.

nextset()#: Move to the next available result set (not supported).

property rowcount: int#: Get the row count of the result set, or -1 if not known.

property rownumber: Optional[int]#: Get the current row number, or None if not applicable.

setinputsizes(sizes)#: Preallocate memory for the parameters (no-op).

setoutputsize(size, column=None)#: Preallocate memory for the result set (no-op).

Exceptions#

exception adbc_driver_manager.DatabaseError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: Error

Errors related to the database.

exception adbc_driver_manager.DataError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

Errors related to processed data.

exception adbc_driver_manager.Error(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: Exception

PEP 249-compliant base exception class.

Attributes:

status_codeAdbcStatusCode: The original ADBC status code.
vendor_codeint, optional: A vendor-specific status code if present.
sqlstatestr, optional: The SQLSTATE code if present.

exception adbc_driver_manager.IntegrityError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

Errors related to relational integrity.

exception adbc_driver_manager.InterfaceError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: Error

Errors related to the database interface.

exception adbc_driver_manager.InternalError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

Errors related to database-internal errors.

exception adbc_driver_manager.NotSupportedError(message, *, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

An operation or some functionality is not supported.

exception adbc_driver_manager.OperationalError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

Errors related to database operation, not under user control.

exception adbc_driver_manager.ProgrammingError(message, *, status_code, vendor_code=None, sqlstate=None)#

Bases: DatabaseError

Errors related to user errors.

exception adbc_driver_manager.Warning#

Bases: UserWarning

PEP 249-compliant base warning class.

adbc_driver_manager#

Low-Level API#

Constants & Enums#

Classes#

DBAPI 2.0 API#

Constants & Enums#

Functions#

Classes#

Exceptions#

`adbc_driver_manager`#