Python DB API – DuckDB - DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 客户端API / Python

Python DB API

标准的 DuckDB Python API 提供了一个符合 PEP 249 中描述的 DB-API 2.0 规范的 SQL 接口，与 SQLite Python API 类似。

连接

要使用该模块，首先必须创建一个表示数据库连接的 DuckDBPyConnection 对象。这可以通过 duckdb.connect 方法完成。

'config' 关键字参数可用于提供一个 dict，其中包含引用 DuckDB 可识别的设置的键值对。

内存中连接 (In-Memory Connection)

特殊值 :memory: 可用于创建内存数据库。请注意，内存数据库的数据不会持久化到磁盘（即：当你退出 Python 进程时，所有数据都会丢失）。

命名内存连接

特殊值 :memory: 也可以加上后缀作为名称，例如：:memory:conn3。当提供了名称时，后续的 duckdb.connect 调用将创建到同一个数据库的新连接，并共享目录（视图、表、宏等）。

不带名称使用 :memory: 将始终创建一个新的、独立的数据库实例。

默认连接

默认情况下，我们在 duckdb 模块内部创建一个（未命名的）内存数据库。DuckDBPyConnection 的所有方法在 duckdb 模块上也可用，这些方法使用的就是此连接。

特殊值 :default: 可用于获取此默认连接。

基于文件的连接

如果 database 是一个文件路径，则会建立到持久化数据库的连接。如果该文件不存在，则会创建该文件（文件扩展名无关紧要，可以是 .db、.duckdb 或任何其他扩展名）。

`read_only` 连接

如果你想以只读模式连接，可以将 read_only 标志设置为 True。如果文件不存在，则在以只读模式连接时不会创建该文件。如果多个 Python 进程想要同时访问同一个数据库文件，则必须使用只读模式。

import duckdb

duckdb.execute("CREATE TABLE tbl AS SELECT 42 a")
con = duckdb.connect(":default:")
con.sql("SELECT * FROM tbl")
# or
duckdb.default_connection().sql("SELECT * FROM tbl")

┌───────┐
│   a   │
│ int32 │
├───────┤
│    42 │
└───────┘

import duckdb

# to start an in-memory database
con = duckdb.connect(database = ":memory:")
# to use a database file (not shared between processes)
con = duckdb.connect(database = "my-db.duckdb", read_only = False)
# to use a database file (shared between processes)
con = duckdb.connect(database = "my-db.duckdb", read_only = True)
# to explicitly get the default connection
con = duckdb.connect(database = ":default:")

如果你想创建到现有数据库的第二个连接，可以使用 cursor() 方法。这在允许并行线程独立运行查询时很有用。单个连接是线程安全的，但在查询期间会被锁定，在这种情况下有效地序列化了数据库访问。

当连接超出作用域或使用 close() 显式关闭时，连接会被隐式关闭。一旦到某个数据库实例的最后一个连接被关闭，该数据库实例也会随之关闭。

可以使用连接的 execute() 方法将 SQL 查询发送到 DuckDB。一旦查询执行完毕，可以使用连接上的 fetchone 和 fetchall 方法检索结果。fetchall 将检索所有结果并完成事务。fetchone 在每次调用时都会检索一行结果，直到没有更多结果可用为止。事务只有在调用 fetchone 且没有剩余结果时才会关闭（返回值为 None）。例如，如果查询只返回一行，则应调用一次 fetchone 来检索结果，并调用第二次来关闭事务。下面是一些简短的示例。

# create a table
con.execute("CREATE TABLE items (item VARCHAR, value DECIMAL(10, 2), count INTEGER)")
# insert two items into the table
con.execute("INSERT INTO items VALUES ('jeans', 20.0, 1), ('hammer', 42.2, 2)")

# retrieve the items again
con.execute("SELECT * FROM items")
print(con.fetchall())
# [('jeans', Decimal('20.00'), 1), ('hammer', Decimal('42.20'), 2)]

# retrieve the items one at a time
con.execute("SELECT * FROM items")
print(con.fetchone())
# ('jeans', Decimal('20.00'), 1)
print(con.fetchone())
# ('hammer', Decimal('42.20'), 2)
print(con.fetchone()) # This closes the transaction. Any subsequent calls to .fetchone will return None
# None

连接对象的 description 属性包含按标准定义的列名。

预处理语句

DuckDB 还在 API 中通过 execute 和 executemany 方法支持预处理语句。可以在包含 ? 或 $1（美元符号加数字）占位符的查询之后，将值作为额外参数传递。使用 ? 符号会按 Python 参数中传递的顺序添加值。使用 $ 符号则允许根据 Python 参数中找到的值的数字和索引，在 SQL 语句中重用值。值的转换遵循转换规则。

以下是一些示例。首先，使用预处理语句插入一行数据

con.execute("INSERT INTO items VALUES (?, ?, ?)", ["laptop", 2000, 1])

其次，使用预处理语句插入多行数据

con.executemany("INSERT INTO items VALUES (?, ?, ?)", [["chainsaw", 500, 10], ["iphone", 300, 2]] )

使用预处理语句查询数据库

con.execute("SELECT item FROM items WHERE value > ?", [400])
print(con.fetchall())

[('laptop',), ('chainsaw',)]

使用 $ 符号的预处理语句进行查询并重用值

con.execute("SELECT $1, $1, $2", ["duck", "goose"])
print(con.fetchall())

[('duck', 'duck', 'goose')]

警告：请不要使用 executemany 向 DuckDB 插入大量数据。请参阅数据摄入页面以获取更好的方案。

命名参数

除了像 $1, $2 等标准未命名参数外，也可以提供像 $my_parameter 这样的命名参数。使用命名参数时，必须在 parameters 参数中提供一个从 str 到值的字典映射。以下是一个示例用法：

import duckdb

res = duckdb.execute("""
    SELECT
        $my_param,
        $other_param,
        $also_param
    """,
    {
        "my_param": 5,
        "other_param": "DuckDB",
        "also_param": [42]
    }
).fetchall()
print(res)

[(5, 'DuckDB', [42])]

关于此页面

行为准则商标使用指南

关于此页面

本文中