adbc_driver_manager

底层 API

面向 Python 的底层 ADBC 绑定。

根模块在 Python 中提供了与 C API 定义相当直接的 1:1 映射。若需要更高级的接口，请使用 adbc_driver_manager.dbapi。（这需要 PyArrow。）

常量与枚举

class adbc_driver_manager.AdbcStatusCode(*values)

基类: IntEnum

指示错误类型的状态码。

ALREADY_EXISTS = 4
CANCELLED = 11
INTEGRITY = 8
INTERNAL = 9
INVALID_ARGUMENT = 5
INVALID_DATA = 7
INVALID_STATE = 6
IO = 10
NOT_FOUND = 3
NOT_IMPLEMENTED = 2
OK = 0
TIMEOUT = 12
UNAUTHENTICATED = 13
UNAUTHORIZED = 14
UNKNOWN = 1
class adbc_driver_manager.GetObjectsDepth(*values)

基类: IntEnum

adbc_get_objects 需要获取多少数据。

ALL = 0
CATALOGS = 1
COLUMNS = 0
DB_SCHEMAS = 2
TABLES = 3
class adbc_driver_manager.ConnectionOptions(*values)

Bases: Enum

在驱动程序之间标准化的连接选项。

并非所有驱动程序都支持所有选项。

CURRENT_CATALOG = 'adbc.connection.catalog'

获取/设置当前目录（Catalog）。

CURRENT_DB_SCHEMA = 'adbc.connection.db_schema'

获取/设置当前架构（Schema）。

ISOLATION_LEVEL = 'adbc.connection.transaction.isolation_level'

设置事务隔离级别。

class adbc_driver_manager.DatabaseOptions(*values)

Bases: Enum

在驱动程序之间标准化的数据库选项。

并非所有驱动程序都支持所有选项。

PASSWORD = 'password'

设置用于用户名-密码认证的密码。

URI = 'uri'

要连接的 URI。

USERNAME = 'username'

设置用于用户名-密码认证的用户名。

class adbc_driver_manager.StatementOptions(*values)

Bases: Enum

在驱动程序之间标准化的语句选项。

并非所有驱动程序都支持所有选项。

BIND_BY_NAME = 'adbc.statement.bind_by_name'

按名称而不是按位置绑定参数。

INCREMENTAL = 'adbc.statement.exec.incremental'

在 ExecutePartitions 上启用增量执行。

INGEST_MODE = 'adbc.ingest.mode'

对于批量导入，决定是创建还是追加到表。

INGEST_TARGET_CATALOG = 'adbc.ingest.target_catalog'

对于批量导入，指定创建/定位表所在的目录。此 API 为实验性功能。

INGEST_TARGET_DB_SCHEMA = 'adbc.ingest.target_db_schema'

对于批量导入，指定创建/定位表所在的架构。此 API 为实验性功能。

INGEST_TARGET_TABLE = 'adbc.ingest.target_table'

对于批量导入，指定要导入的目标表。

INGEST_TEMPORARY = 'adbc.ingest.temporary'

对于批量导入，使用临时表。此 API 为实验性功能。

PROGRESS = 'adbc.statement.exec.progress'

获取查询进度。

adbc_driver_manager.INGEST_OPTION_MODE

批量导入时，是追加到现有表还是创建新表。

adbc_driver_manager.INGEST_OPTION_MODE_APPEND

批量导入时追加到表。

adbc_driver_manager.INGEST_OPTION_MODE_CREATE

批量导入时创建新表。

adbc_driver_manager.INGEST_OPTION_TARGET_TABLE

批量导入时要创建/追加的目标表。

类

class adbc_driver_manager.AdbcConnection

基类: _AdbcHandle

一个活动的数据库连接。

连接不是线程安全的，客户端应注意序列化对连接的访问。

参数:
databaseAdbcDatabase

要连接到的数据库。

kwargsdict

传递给底层数据库的字符串键值选项。

方法

cancel()

尝试取消连接上正在进行的操作。

close()

释放连接句柄。

commit()

提交当前事务。

get_info([info_codes])

获取关于数据库/驱动程序的元数据。

get_objects(depth[, catalog, db_schema, ...])

获取数据库对象的层次结构视图。

get_option(key, *[, encoding, errors])

获取字符串选项的值。

get_option_bytes(key)

获取二进制选项的值。

get_option_float(key)

获取浮点数选项的值。

get_option_int(key)

获取整数选项的值。

get_statistic_names()

获取此驱动程序定义的自定义统计名称。

get_statistics([catalog, db_schema, ...])

获取关于表数据分布的统计信息。

get_table_schema(catalog, db_schema, table_name)

获取表的 Arrow 架构。

get_table_types()

获取支持的表类型列表。

read_partition(partition)

从 execute_partitions 中获取单个分区。

rollback()

回滚当前事务。

set_autocommit(enabled)

切换是否启用自动提交。

set_options(**kwargs)

设置任意键值选项。
cancel() → None

尝试取消连接上正在进行的操作。

close() → None

释放连接句柄。

commit() → None

提交当前事务。

get_info(info_codes=None) → ArrowArrayStreamHandle

获取关于数据库/驱动程序的元数据。

get_objects(depth, catalog=None, db_schema=None, table_name=None, table_types=None, column_name=None) → ArrowArrayStreamHandle

获取数据库对象的层次结构视图。

get_option(key: str | bytes, *, encoding='utf-8', errors='strict') → str

获取字符串选项的值。

参数:
keystr 或 bytes

要获取的选项。

encodingstr

选项值的编码。几乎总是应为 UTF-8。

errorsstr

解码选项值时出现错误的处理方式（参见 bytes.decode）。

get_option_bytes(key: str) → bytes

获取二进制选项的值。

get_option_float(key: str) → float

获取浮点数选项的值。

get_option_int(key: str) → int

获取整数选项的值。

get_statistic_names() → ArrowArrayStreamHandle

获取此驱动程序定义的自定义统计名称。

返回：
ArrowArrayStreamHandle

一个包含以下列的流：statistic_name (utf8), statistic_key (int16)。

备注

自 ADBC API 版本 1.1.0 起可用。返回驱动程序特定的统计名称及其键。标准的 ADBC 统计（键 0-1023）不包含在内 - 仅包含驱动程序特定的统计。

get_statistics(catalog=None, db_schema=None, table_name=None, approximate=True) → ArrowArrayStreamHandle

获取关于表数据分布的统计信息。

参数:
catalogstr, 可选

要过滤的目录。可以是搜索模式或 None。

db_schemastr, 可选

要过滤的数据库架构。可以是搜索模式或 None。

table_namestr, 可选

要过滤的表名。可以是搜索模式或 None。

approximatebool, 默认 True

如果为 True，允许使用近似或缓存的统计信息。如果为 False，则请求精确的统计信息（可能开销较大或不支持）。

返回：
ArrowArrayStreamHandle

一个具有嵌套结构的统计数据流。

备注

自 ADBC API 版本 1.1.0 起可用。即便请求精确值，驱动程序也可能返回近似值，如结果的 statistic_is_approximate 列所示。

get_table_schema(catalog, db_schema, table_name) → ArrowSchemaHandle

获取表的 Arrow 架构。

返回：
ArrowSchemaHandle

包含该架构的 C 数据接口 ArrowSchema 结构体。

get_table_types() → ArrowArrayStreamHandle

获取支持的表类型列表。

read_partition(partition) → ArrowArrayStreamHandle

从 execute_partitions 中获取单个分区。

rollback() → None

回滚当前事务。

set_autocommit(enabled) → None

切换是否启用自动提交。

set_options(**kwargs) → None

设置任意键值选项。

以 kwargs 形式传递选项： set_options(**{"some.option": "value"})。

注意，并非所有驱动程序都支持在创建后设置选项。

另请参阅

adbc_driver_manager.ConnectionOptions

标准选项名称。

class adbc_driver_manager.AdbcDatabase

基类: _AdbcHandle

数据库的一个实例。

参数:
kwargsdict

传递给底层数据库的字符串键值选项。必须至少包含“driver”以标识要加载的底层数据库驱动程序。

方法

close()

释放数据库句柄。

get_option(key, *[, encoding, errors])

获取字符串选项的值。

get_option_bytes(key)

获取二进制选项的值。

get_option_float(key)

获取浮点数选项的值。

get_option_int(key)

获取整数选项的值。

set_options(**kwargs)

设置任意键值选项。
close() → None

释放数据库句柄。

get_option(key: str | bytes, *, encoding='utf-8', errors='strict') → str

获取字符串选项的值。

参数:
keystr 或 bytes

要获取的选项。

encodingstr

选项值的编码。几乎总是应为 UTF-8。

errorsstr

解码选项值时出现错误的处理方式（参见 bytes.decode）。

get_option_bytes(key: str) → bytes

获取二进制选项的值。

get_option_float(key: str) → float

获取浮点数选项的值。

get_option_int(key: str) → int

获取整数选项的值。

set_options(**kwargs) → None

设置任意键值选项。

以 kwargs 形式传递选项： set_options(**{"some.option": "value"})。

注意，并非所有驱动程序都支持在创建后设置选项。

另请参阅

adbc_driver_manager.DatabaseOptions

标准选项名称。

class adbc_driver_manager.AdbcStatement

基类: _AdbcHandle

一条数据库语句。

语句不是线程安全的，客户端应注意序列化对连接的访问。

参数:
connectionAdbcConnection

创建该语句的连接。

方法

bind(data[, schema])

将 ArrowArray 绑定到此语句。

bind_stream(stream)

将 ArrowArrayStream 绑定到此语句。

cancel()

尝试取消连接上正在进行的操作。

close()

释放语句句柄。

execute_partitions()

执行查询并获取结果集的分区。

execute_query()

执行查询并获取结果集。

execute_schema()

在不执行查询的情况下获取结果集的架构。

execute_update()

执行不返回结果集的查询。

get_option(key, *[, encoding, errors])

获取字符串选项的值。

get_option_bytes(key)

获取二进制选项的值。

get_option_float(key)

获取浮点数选项的值。

get_option_int(key)

获取整数选项的值。

get_parameter_schema()

获取绑定参数的 Arrow 架构。

prepare()

将此语句转换为预处理语句（prepared statement）。

set_options(**kwargs)

仅为此语句设置任意键值选项。

set_sql_query(query)

设置要执行的 SQL 查询。

set_substrait_plan(plan)

设置要执行的 Substrait 计划。
bind(data, schema=None) → None

将 ArrowArray 绑定到此语句。

参数:
dataPyCapsule 或 int 或 ArrowArrayHandle
schemaPyCapsule 或 int 或 ArrowSchemaHandle
bind_stream(stream) → None

将 ArrowArrayStream 绑定到此语句。

参数:
streamPyCapsule 或 int 或 ArrowArrayStreamHandle
cancel() → None

尝试取消连接上正在进行的操作。

close() → None

释放语句句柄。

execute_partitions() → Tuple[List[bytes], ArrowSchemaHandle | None, int]

执行查询并获取结果集的分区。

并非所有驱动程序都支持此功能。

返回：
字节列表

分布式结果集的分区。

ArrowSchemaHandle 或 None

结果集的架构。如果启用了增量执行且服务器未返回架构，则可能为 None。

int

行数（如果已知，否则为 -1）。

execute_query() → Tuple[ArrowArrayStreamHandle, int]

执行查询并获取结果集。

返回：
ArrowArrayStreamHandle

结果集。

int

行数（如果已知，否则为 -1）。

execute_schema() → ArrowSchemaHandle

在不执行查询的情况下获取结果集的架构。

返回：
ArrowSchemaHandle

结果集的架构。

execute_update() → int

执行不返回结果集的查询。

返回：
int

受影响的行数（如果已知，否则为 -1）。

get_option(key: str | bytes, *, encoding='utf-8', errors='strict') → str

获取字符串选项的值。

参数:
keystr 或 bytes

要获取的选项。

encodingstr

选项值的编码。几乎总是应为 UTF-8。

errorsstr

解码选项值时出现错误的处理方式（参见 bytes.decode）。

get_option_bytes(key: str) → bytes

获取二进制选项的值。

get_option_float(key: str) → float

获取浮点数选项的值。

get_option_int(key: str) → int

获取整数选项的值。

get_parameter_schema() → ArrowSchemaHandle

获取绑定参数的 Arrow 架构。

这会检索一个 Arrow 架构，描述参数化语句中参数的数量、名称和类型。架构的字段应按参数的序号位置排列；命名参数应仅出现一次。

如果参数没有名称，或无法确定名称，则架构中相应字段的名称将为空字符串。如果无法确定类型，则相应字段的类型将为 NA (NullType)。

此方法应在 prepare() 之后调用。

引发:
NotSupportedError

如果无法确定架构。

prepare() → None

将此语句转换为预处理语句（prepared statement）。

set_options(**kwargs) → None

仅为此语句设置任意键值选项。

以 kwargs 形式传递选项： set_options(**{"some.option": "value"})。

注意，并非所有驱动程序都支持在创建后设置选项。

另请参阅

adbc_driver_manager.StatementOptions

标准选项名称。

set_sql_query(query) → None

设置要执行的 SQL 查询。

set_substrait_plan(plan) → None

设置要执行的 Substrait 计划。

class adbc_driver_manager.ArrowArrayHandle

基类： object

已分配 ArrowArray 的包装器。

此对象实现了 Arrow PyCapsule 接口。

属性:
address

ArrowArray 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

方法

release()

在不导入的情况下释放此数组。
address

ArrowArray 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

release()

在不导入的情况下释放此数组。

如果已释放（若 not self.is_valid），则不执行任何操作。

后置条件： not self.is_valid。

class adbc_driver_manager.ArrowArrayStreamHandle

基类： object

已分配 ArrowArrayStream 的包装器。

此对象实现了 Arrow PyCapsule 接口。

属性:
address

ArrowArrayStream 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

方法

release()

在不导入的情况下释放此流。
address

ArrowArrayStream 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

release()

在不导入的情况下释放此流。

如果已释放（若 not self.is_valid），则不执行任何操作。

后置条件： not self.is_valid。

class adbc_driver_manager.ArrowSchemaHandle

基类： object

已分配 ArrowSchema 的包装器。

此对象实现了 Arrow PyCapsule 接口。

属性:
address

ArrowSchema 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

方法

release()

在不导入的情况下释放此架构。
address

ArrowSchema 的地址。

is_valid

检查有效性（对象具有非 NULL 的释放指针）。

release()

在不导入的情况下释放此架构。

如果已释放（若 not self.is_valid），则不执行任何操作。

后置条件： not self.is_valid。

DBAPI 2.0 API

用于 ADBC 驱动程序管理器的 PEP 249 (DB-API 2.0) API 包装器。

PyArrow 要求

此模块需要 PyArrow 才能实现全部功能。如果未安装 PyArrow，所有实际读写数据的功能将缺失。您仍然可以执行查询并将结果获取为 PyCapsule，但许多其他方法将引发异常。此外，DB-API 类型定义（BINARY, DATETIME 等）将会存在，但无效。

资源管理

您必须对 Connection 和 Cursor 对象调用 close()，否则驱动程序资源可能会泄漏。作为后备方案实现了 __del__，但 Python 不保证何时调用它。在开发过程中，在 pytest 下运行，或将环境变量 _ADBC_DRIVER_MANAGER_WARN_UNCLOSED_RESOURCE 设置为 1 时，__del__ 将引发 ResourceWarning。

常量与枚举

adbc_driver_manager.dbapi.apilevel = '2.0'

DB-API API 级别 (2.0)。

adbc_driver_manager.dbapi.paramstyle = 'qmark'

参数样式 (qmark)。这是硬编码的，但实际上取决于驱动程序。

adbc_driver_manager.dbapi.threadsafety = 1

线程安全级别（连接不能共享）。

adbc_driver_manager.dbapi.Date = <class 'datetime.date'>

日期值的类型。

adbc_driver_manager.dbapi.Time = <class 'datetime.time'>

时间值的类型。

adbc_driver_manager.dbapi.Timestamp(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]]) = <class 'datetime.datetime'>

时间戳值的类型。

adbc_driver_manager.dbapi.BINARY = frozenset({14, 35})

二进制列的类型。

adbc_driver_manager.dbapi.DATETIME = frozenset({16, 17, 18, 19, 20})

日期时间列的类型。

adbc_driver_manager.dbapi.NUMBER = frozenset({2, 3, 4, 5, 6, 7, 8, 9, 11, 12})

数字列的类型。

adbc_driver_manager.dbapi.ROWID = frozenset({9})

“行 ID”列的类型。

adbc_driver_manager.dbapi.STRING = frozenset({13, 34})

字符串列的类型。

函数

adbc_driver_manager.dbapi.connect(driver: str | Path | None = None, uri: str | None = None, *, profile: str | None = None, entrypoint: str | None = None, db_kwargs: Mapping[str, str | Path] | None = None, conn_kwargs: Mapping[str, str] | None = None, autocommit=False) → Connection

通过 ADBC 连接到数据库。

参数:
driver

要使用的驱动程序。这可以是多种值之一

  • 驱动程序名称或清单名称。

    例如，“adbc_driver_sqlite”将首先尝试从各种搜索路径中加载 adbc_driver_sqlite.toml。然后，它将在 Linux 上尝试加载 libadbc_driver_sqlite.so，在 macOS 上加载 libadbc_driver_sqlite.dylib，或在 Windows 上加载 adbc_driver_sqlite.dll。请参阅 ADBC 驱动程序管理器和清单。

  • 要加载的共享库的相对或绝对路径。

  • 仅提供 URI，在这种情况下，URI 方案将被视为驱动程序名称，并按上述方式加载。当在驱动程序名称中检测到“://”时会发生这种情况。（并不假定该 URI 实际上是一个有效的 URI。）驱动程序管理器将原样传递该 URI，因此仅当驱动程序支持其方案恰好与驱动程序名称相同的 URI 时，此方法才有用（例如，PostgreSQL 可以工作，但 SQLite 不行，因为 SQLite 使用 file: URI）。

  • 如果 URI 以 profile:// 开头，则会加载连接配置文件。请参阅 ADBC 驱动程序管理器和连接配置文件。

uri

数据库的“uri”参数（如果适用）。这等同于在 db_kwargs 中传递它，但稍微简洁一些。如果提供了此参数，则优先于 db_kwargs 中的任何值。

profile

要加载的连接配置文件。加载 profile="profile-name" 与加载 URI profile://profile-name 相同。请参阅 ADBC 驱动程序管理器和连接配置文件。

入口点

驱动程序特定的入口点（如果与默认值不同）。

db_kwargs

传递给驱动程序以初始化数据库的键值参数。

conn_kwargs

传递给驱动程序以初始化连接的键值参数。

autocommit

是否启用自动提交。为了符合 DB-API 标准，此项默认禁用。如果无法禁用，将发出警告。

adbc_driver_manager.dbapi.DateFromTicks(ticks: int) → date

从秒数构造一个日期值。

adbc_driver_manager.dbapi.TimeFromTicks(ticks: int) → time

从秒数构造一个时间值。

adbc_driver_manager.dbapi.TimestampFromTicks(ticks: int) → datetime

从秒数构造一个时间戳值。

类

class adbc_driver_manager.dbapi.Connection(db: AdbcDatabase | _SharedDatabase, conn: AdbcConnection, conn_kwargs: Mapping[str, str] | None = None, *, autocommit=False, backend: DbapiBackend | None = None)

基类: _Closeable

DB-API 2.0 (PEP 249) 连接。

请勿直接创建此对象；请使用 connect()。

属性:
adbc_connection

获取底层的 ADBC 连接。

adbc_current_catalog

当前目录名称。

adbc_current_db_schema

当前模式名称。

adbc_database

获取底层的 ADBC 数据库。

方法

adbc_cancel()

取消此连接上任何正在进行的操作。

adbc_clone()

创建共享相同底层数据库的新连接。

adbc_get_info()

获取有关数据库和驱动程序的元数据。

adbc_get_objects(*[, depth, catalog_filter, ...])

列出目录、模式、表等。

adbc_get_statistic_names()

获取此驱动程序定义的自定义统计信息名称列表。

adbc_get_statistics(*[, catalog_filter, ...])

获取有关表数据分布的统计信息。

adbc_get_table_schema(table_name, *[, ...])

按名称获取表的 Arrow 模式。

adbc_get_table_types()

列出服务器已知的表类型。

close()

关闭连接。

commit()

显式提交。

cursor(*[, adbc_stmt_kwargs])

创建用于查询数据库的新游标。

execute(operation[, parameters, ...])

在新的游标上执行查询。

rollback()

显式回滚。
adbc_cancel() → None

取消此连接上任何正在进行的操作。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_clone() → Connection

创建共享相同底层数据库的新连接。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property adbc_connection: AdbcConnection

获取底层的 ADBC 连接。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property adbc_current_catalog: str

当前目录名称。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property adbc_current_db_schema: str

当前模式名称。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property adbc_database: AdbcDatabase

获取底层的 ADBC 数据库。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_get_info() → Dict[str | int, Any]

获取有关数据库和驱动程序的元数据。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

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

列出数据库中的目录、模式、表等。

参数:
depth

返回哪些对象的信息。

catalog_filter

对返回的目录名称的可选过滤器。

db_schema_filter

对返回的数据库模式名称的可选过滤器。

table_name_filter

对返回的表名称的可选过滤器。

table_types_filter

返回的表类型的可选列表。

column_name_filter

对返回的列名称的可选过滤器。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_get_statistic_names() → RecordBatchReader

获取此驱动程序定义的自定义统计信息名称列表。

结果包含两列：- statistic_name (utf8): 统计信息的人类可读名称 - statistic_key (int16): 用于 get_statistics 结果的数字键

返回：
pyarrow.RecordBatchReader

统计信息名称的读取器。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

自 ADBC API 版本 1.1.0 起可用。标准 ADBC 统计信息（键 0-1023）不包含在此结果中 - 仅包含特定于驱动程序的统计信息。

adbc_get_statistics(*, catalog_filter: str | None = None, db_schema_filter: str | None = None, table_name_filter: str | None = None, approximate: bool = True) → RecordBatchReader

获取有关表数据分布的统计信息。

结果是一个具有嵌套结构的 Arrow 数据集，包含表统计信息。模式包括：

  • catalog_name (utf8)

  • catalog_db_schemas (结构体列表)

    • db_schema_name (utf8)

    • db_schema_statistics (结构体列表)

      • table_name (utf8)

      • column_name (utf8, 可为空) - 如果适用于整个表，则为空

      • statistic_key (int16) - 字典编码的统计信息名称

      • statistic_value (密集联合体) - int64、uint64、float64 或二进制

      • statistic_is_approximate (bool)

参数:
catalog_filter

对目录名称的可选过滤器。可以是搜索模式。

db_schema_filter

对数据库模式名称的可选过滤器。可以是搜索模式。

table_name_filter

对表名称的可选过滤器。可以是搜索模式。

approximate

如果为 True（默认值），则允许近似或缓存的统计信息。如果为 False，则请求精确的统计信息，这可能会很昂贵或不受支持。请注意，驱动程序可能仍然会返回近似值，具体由 statistic_is_approximate 列指示。

返回：
pyarrow.RecordBatchReader

统计数据的读取器。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

自 ADBC API 版本 1.1.0 起可用。并非所有驱动程序都支持此方法。如果不支持，将引发 NotSupportedError。

adbc_get_table_schema(table_name: str, *, catalog_filter: str | None = None, db_schema_filter: str | None = None) → Schema

按名称获取表的 Arrow 模式。

参数:
table_name

要获取模式的表。

catalog_filter

对表的目录名称的可选过滤器。

db_schema_filter

对表的数据库模式名称的可选过滤器。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_get_table_types() → List[str]

列出服务器已知的表类型。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

close() → None

关闭连接。

警告

未能关闭连接可能会导致内存泄漏或数据库连接耗尽。

备注

这也将关闭与此连接关联的任何打开的游标。

commit() → None

显式提交。

cursor(*, adbc_stmt_kwargs: Mapping[str, Any] | None = None) → Cursor

创建用于查询数据库的新游标。

参数:
adbc_stmt_kwargsdict, 可选

传递给底层 ADBC 语句的 ADBC 特定选项。

execute(operation: bytes | str, parameters=None, *, adbc_stmt_kwargs: Mapping[str, Any] | None = None) → Cursor

在新的游标上执行查询。

这是创建新游标并执行查询的一种便捷方法。

rollback() → None

显式回滚。

class adbc_driver_manager.dbapi.Cursor(conn: Connection, adbc_stmt_kwargs: Mapping[str, Any] | None = None, *, dbapi_backend: DbapiBackend | None = None)

基类: _Closeable

DB-API 2.0 (PEP 249) 游标。

请勿直接创建此对象；请使用 Connection.cursor()。

属性:
adbc_statement

获取底层 ADBC 语句。

arraysize

使用 fetchmany() 每次提取的行数。

connection

获取与此游标关联的连接。

description

结果集的架构。

rowcount

获取结果集的行数，如果未知则为 -1。

rownumber

获取当前行号，如果不可用则为 None。

方法

adbc_cancel()

取消此语句上任何正在进行的操作。

adbc_execute_partitions(operation[, parameters])

执行查询并获取分布式结果集的分区。

adbc_execute_schema(operation[, parameters])

获取查询结果集的模式，而不执行查询。

adbc_ingest(table_name, data[, mode, ...])

将 Arrow 数据摄取到数据库表中。

adbc_prepare(operation)

准备查询而不执行它。

adbc_read_partition(partition)

读取分布式结果集的分区。

callproc(procname, parameters)

调用存储过程（不支持）。

close()

关闭游标并释放资源。

execute(operation[, parameters])

执行查询。

executemany(operation, seq_of_parameters)

使用多个参数集执行查询。

executescript(operation)

执行多个语句。

fetch_arrow()

以实现 Arrow PyCapsule 接口的对象形式提取结果。

fetch_arrow_table()

以 PyArrow Table 的形式提取结果的所有行。

fetch_df()

以 Pandas DataFrame 的形式提取结果的所有行。

fetch_polars()

以 Polars DataFrame 的形式提取结果的所有行。

fetch_record_batch()

以 PyArrow RecordBatchReader 的形式提取结果。

fetchall()

提取结果的所有行。

fetchallarrow()

以 PyArrow Table 的形式提取结果的所有行。

fetchmany([size])

提取结果的部分行。

fetchone()

提取结果的一行。

下一页()

提取下一行，或引发 StopIteration。

nextset()

移动到下一个可用的结果集（不支持）。

setinputsizes(sizes)

为参数预分配内存（空操作）。

setoutputsize(size[, column])

为结果集预分配内存（空操作）。
adbc_cancel() → None

取消此语句上任何正在进行的操作。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

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

执行查询并获取分布式结果集的分区。

返回：
partitions字节列表

分区描述符列表，可以使用 read_partition 读取。

schemapyarrow.Schema 或 None

结果集的模式。如果启用了增量查询执行且服务器尚未返回模式，则可能为 None。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_execute_schema(operation, parameters=None) → Schema

获取查询结果集的模式，而不执行查询。

返回：
pyarrow.Schema

结果集的架构。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_ingest(table_name: str, data: pyarrow.RecordBatch | pyarrow.Table | pyarrow.RecordBatchReader | CapsuleType, mode: Literal['append', 'create', 'replace', 'create_append'] = 'create', *, catalog_name: str | None = None, db_schema_name: str | None = None, temporary: bool = False) → int

将 Arrow 数据摄取到数据库表中。

根据驱动程序的不同，这可以避免典型的 prepare-bind-insert 循环导致的每行开销。

参数:
table_name

要插入的表。

数据

要插入的 Arrow 数据。这可以是 pyarrow RecordBatch、Table 或 RecordBatchReader，或者任何实现 Arrow PyCapsule 协议的兼容数据（即具有 __arrow_c_array__ 或 __arrow_c_stream__ 方法）。

模式

如何处理现有数据

  • ‘append’：追加到表（如果表不存在则报错）

  • ‘create’：创建表并插入（如果表已存在则报错）

  • ‘create_append’：创建表（如果不存在）并插入

  • ‘replace’：删除现有表（如有），然后与‘create’相同

catalog_name

如果提供，则为在其中创建/查找表的目录。此 API 为实验性。

db_schema_name

如果提供，则为在其中创建/查找表的模式。此 API 为实验性。

temporary

是否摄取到临时表。大多数驱动程序不支持在设置 catalog_name 和/或 db_schema_name 的同时设置此项。此 API 为实验性。

返回：
int

插入的行数，如果驱动程序无法提供此信息，则为 -1。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_prepare(operation: bytes | str) → Schema | None

准备查询而不执行它。

要在之后执行查询，请使用相同的查询调用 execute() 或 executemany()。这不会第二次准备该查询。

返回：
pyarrow.Schema 或 None

绑定参数的模式，如果无法确定模式，则为 None。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

adbc_read_partition(partition: bytes) → None

读取分布式结果集的分区。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property adbc_statement: AdbcStatement

获取底层 ADBC 语句。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

property arraysize: int

使用 fetchmany() 每次提取的行数。

callproc(procname, parameters) → NoReturn

调用存储过程（不支持）。

close() → None

关闭游标并释放资源。

property connection: Connection

获取与此游标关联的连接。

这是一个可选的 DB-API 扩展。

property description: List[tuple] | None

结果集的架构。

execute(operation: bytes | str, parameters=None) → Self

执行查询。

参数:
operationbytes 或 str

要执行的查询。SQL 查询以字符串形式传递，（序列化的）Substrait 计划以字节形式传递。

parameters

要绑定的参数。可以是 Python 序列（用于绑定单个参数集）、Python 字典（用于按名称而不是按位置绑定单个参数集），或者 Arrow 记录批次、表或记录批次读取器（用于提供多个参数，每个参数将依次绑定）。

在提供 Arrow 数据时按名称绑定，请显式切换语句选项“adbc.statement.bind_by_name”。

请注意，不支持提供元组列表（此用法在 DBAPI-2.0 中已弃用；请改用 executemany()）。

返回：
Self

此游标（用于启用链式调用）。

executemany(operation: bytes | str, seq_of_parameters) → None

使用多个参数集执行查询。

此方法不生成结果集。

参数:
operationbytes 或 str

要执行的查询。SQL 查询以字符串形式传递，（序列化的）Substrait 计划以字节形式传递。

seq_of_parameters

要绑定的参数。可以是 Python 序列列表，或 Arrow 记录批次、表或记录批次读取器。如果为 None，则查询将执行一次，否则将为每行执行一次。（这意味着空序列等同于根本不执行查询。）

备注

允许参数为 None 超出了 DB-API 规范。

此方法不返回 self，因为没有结果集。

executescript(operation: str) → None

执行多个语句。

如果有挂起的事务，则先提交。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetch_arrow() → ArrowArrayStreamHandle

以实现 Arrow PyCapsule 接口的对象形式提取结果。

此方法只能调用一次。必须在任何其他消耗数据的方法（例如 fetchone、fetch_arrow_table 等；允许使用 description）之前调用。一旦调用此方法，可能无法再调用其他检查数据的方法。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetch_arrow_table() → Table

以 PyArrow Table 的形式提取结果的所有行。

这实现了与 DuckDB 类似的 API。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetch_df() → pandas.DataFrame

以 Pandas DataFrame 的形式提取结果的所有行。

这实现了与 DuckDB 类似的 API。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetch_polars() → polars.DataFrame

以 Polars DataFrame 的形式提取结果的所有行。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetch_record_batch() → RecordBatchReader

以 PyArrow RecordBatchReader 的形式提取结果。

这实现了与 DuckDB 类似的 API：https://duckdb.org.cn/docs/guides/python/export_arrow.html#export-as-a-recordbatchreader

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetchall() → List[tuple]

提取结果的所有行。

fetchallarrow() → Table

以 PyArrow Table 的形式提取结果的所有行。

这实现了与 turbodbc 类似的 API。

备注

这是一个扩展，不属于 DBAPI 标准的一部分。

fetchmany(size: int | None = None) → List[tuple]

提取结果的部分行。

fetchone() → tuple | None

提取结果的一行。

next() → tuple

提取下一行，或引发 StopIteration。

nextset() → NoReturn

移动到下一个可用的结果集（不支持）。

property rowcount: int

获取结果集的行数，如果未知则为 -1。

property rownumber: int | None

获取当前行号，如果不可用则为 None。

setinputsizes(sizes) → None

为参数预分配内存（空操作）。

setoutputsize(size, column=None) → None

为结果集预分配内存（空操作）。

内部组件

请勿直接使用这些。

class adbc_driver_manager._lib._AdbcHandle

基类： object

ADBC 句柄的基类，它们是上下文管理器。

class adbc_driver_manager.dbapi._Closeable

基类: ABC

提供上下文管理器接口的基类。

class adbc_driver_manager.dbapi._SharedDatabase(db: AdbcDatabase)

基类: _Closeable

共享 AdbcDatabase 的持有者。

异常

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

基类：Error

与数据库相关的错误。

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

基类：DatabaseError

与处理数据相关的错误。

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

基类：Exception

符合 PEP 249 的基础异常类。

属性:
status_codeAdbcStatusCode

原始的 ADBC 状态码。

vendor_codeint, optional

供应商特定的状态码（如果存在）。

sqlstatestr, optional

SQLSTATE 代码（如果存在）。

detailslist[tuple[str, bytes]], optional

附加的错误详情（如果存在）。

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

基类：DatabaseError

与关系完整性相关的错误。

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

基类：Error

与数据库接口相关的错误。

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

基类：DatabaseError

与数据库内部错误相关的错误。

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

基类：DatabaseError

不支持某项操作或功能。

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

基类：DatabaseError

与非用户控制的数据库操作相关的错误。

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

基类：DatabaseError

与用户错误相关的错误。

exception adbc_driver_manager.Warning

基类：UserWarning

符合 PEP 249 的基础警告类。