快速入门

在此我们将简要介绍 ADBC 与 SQLite 驱动的基本功能。

安装

pip install adbc_driver_manager adbc_driver_sqlite pyarrow

DBAPI (PEP 249) 风格的 API

如果安装了 PyArrow 或 Polars，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