快速入门

这里我们将简要介绍使用 SQLite 驱动程序的 ADBC 基本功能。

安装

pip install adbc_driver_manager adbc_driver_sqlite pyarrow

DBAPI (PEP 249) 风格 API

如果安装了 PyArrow，ADBC 会提供一个类似于 DBAPI 标准的高级 API。

创建连接

>>> import adbc_driver_sqlite.dbapi
>>> conn = adbc_driver_sqlite.dbapi.connect()

在应用程序代码中，连接必须在使用后关闭，否则可能会导致内存泄漏。连接可以用作上下文管理器来完成此操作。

创建游标

>>> cursor = conn.cursor()

在应用程序代码中，游标必须在使用后关闭，否则可能会导致内存泄漏。游标可以用作上下文管理器来完成此操作。

执行查询

我们可以执行一个查询，并通过常规的、面向行的 DBAPI 接口获取结果

>>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
>>> cursor.fetchone()
(1, 2.0, 'Hello, world!')
>>> cursor.fetchone()

我们还可以通过非标准方法将结果作为 Arrow 数据获取

>>> cursor.execute("SELECT 1, 2.0, 'Hello, world!'")
>>> cursor.fetch_arrow_table()
pyarrow.Table
1: int64
2.0: double
'Hello, world!': string
----
1: [[1]]
2.0: [[2]]
'Hello, world!': [["Hello, world!"]]

参数化查询

我们可以将参数绑定到查询中

>>> cursor.execute("SELECT ? + 1 AS the_answer", parameters=(41,))
>>> cursor.fetch_arrow_table()
pyarrow.Table
the_answer: int64
----
the_answer: [[42]]

导入批量数据

到目前为止，我们主要演示了常见的 DBAPI 接口。ADBC API 还提供了其他方法。例如，我们可以将 Arrow 数据表插入到新的数据库表中

>>> import pyarrow
>>> table = pyarrow.table([[1, 2], ["a", None]], names=["ints", "strs"])
>>> cursor.adbc_ingest("sample", table)
2
>>> cursor.execute("SELECT COUNT(DISTINCT ints) FROM sample")
>>> cursor.fetchall()
[(2,)]

我们还可以追加到现有表

>>> table = pyarrow.table([[2, 3], [None, "c"]], names=["ints", "strs"])
>>> cursor.adbc_ingest("sample", table, mode="append")
2
>>> cursor.execute("SELECT COUNT(DISTINCT ints) FROM sample")
>>> cursor.fetchall()
[(3,)]

获取数据库/驱动程序元数据

我们可以使用另一个扩展方法来获取有关驱动程序和数据库的信息，这次是在连接本身进行操作

>>> conn.adbc_get_info()["vendor_name"]
'SQLite'
>>> conn.adbc_get_info()["driver_name"]
'ADBC SQLite Driver'

我们还可以查询数据库中的表和列。这将给出描述所有目录、模式、表和列的嵌套结构

>>> info = conn.adbc_get_objects().read_all().to_pylist()
>>> main_catalog = info[0]
>>> schema = main_catalog["catalog_db_schemas"][0]
>>> tables = schema["db_schema_tables"]
>>> tables[0]["table_name"]
'sample'
>>> [column["column_name"] for column in tables[0]["table_columns"]]
['ints', 'strs']

我们可以获取表的 Arrow 模式

>>> conn.adbc_get_table_schema("sample")
ints: int64
strs: string