本页面记录了将 Python 对象转换为 DuckDB 以及将 DuckDB 结果转换为 Python 对象的规则。
对象转换：Python 对象到 DuckDB
这是 Python 对象类型到 DuckDB 逻辑类型 的映射
None→NULLbool→BOOLEANdatetime.timedelta→INTERVALstr→VARCHARbytearray→BLOBmemoryview→BLOBdecimal.Decimal→DECIMAL/DOUBLEuuid.UUID→UUID
其余转换规则如下。
int
由于 Python 中的整数可以是任意大小，因此无法实现一对一的转换。相反，我们按顺序执行这些强制转换，直到成功为止。
BIGINTINTEGERUBIGINTUINTEGERDOUBLE
使用 DuckDB Value 类时，可以设置目标类型，这将影响转换过程。
float
这些转换尝试按顺序进行，直到其中一个成功。
DOUBLEFLOAT
datetime.datetime
对于 datetime，如果可用，我们将检查 pandas.isnull，如果返回 true，则返回 NULL。我们将对比 datetime.datetime.min 和 datetime.datetime.max，分别将其转换为 -inf 和 +inf。
如果 datetime 包含 tzinfo（时区信息），我们将使用 TIMESTAMPTZ，否则它将成为 TIMESTAMP。
datetime.time
如果 time 包含 tzinfo，我们将使用 TIMETZ，否则它将成为 TIME。
datetime.date
date 转换为 DATE 类型。我们将对比 datetime.date.min 和 datetime.date.max，分别将其转换为 -inf 和 +inf。
bytes
bytes 默认转换为 BLOB；当用于构建 BITSTRING 类型的 Value 对象时，它会映射为 BITSTRING。
list
list 变为其子项中“最宽松”类型的 LIST 类型，例如：
my_list_value = [
12345,
"test"
]
将变为 VARCHAR[]，因为 12345 可以转换为 VARCHAR，但 test 无法转换为 INTEGER。
[12345, test]
dict
dict 对象可以根据其结构转换为 STRUCT(...) 或 MAP(..., ...)。如果字典的结构类似于：
import duckdb
my_map_dict = {
"key": [
1, 2, 3
],
"value": [
"one", "two", "three"
]
}
duckdb.values(my_map_dict)
那么我们将把它转换为两个列表压缩在一起的键值对的 MAP。上面的示例变为 MAP(INTEGER, VARCHAR)。
┌─────────────────────────┐
│ {1=one, 2=two, 3=three} │
│ map(integer, varchar) │
├─────────────────────────┤
│ {1=one, 2=two, 3=three} │
└─────────────────────────┘
如果字典由函数返回，该函数将返回一个 MAP，因此必须指定函数的 return_type。提供一个无法转换为 MAP 的返回类型将引发错误。
import duckdb
duckdb_conn = duckdb.connect()
def get_map() -> dict[str,list[str]|list[int]]:
return {
"key": [
1, 2, 3
],
"value": [
"one", "two", "three"
]
}
duckdb_conn.create_function("get_map", get_map, return_type=dict[int, str])
duckdb_conn.sql("select get_map()").show()
duckdb_conn.create_function("get_map_error", get_map)
duckdb_conn.sql("select get_map_error()").show()
┌─────────────────────────┐
│ get_map() │
│ map(bigint, varchar) │
├─────────────────────────┤
│ {1=one, 2=two, 3=three} │
└─────────────────────────┘
ConversionException: Conversion Error: Type VARCHAR can't be cast as UNION(u1 VARCHAR[], u2 BIGINT[]). VARCHAR can't be implicitly cast to any of the union member types: VARCHAR[], BIGINT[]
字段名称很重要，且两个列表必须具有相同的大小。
否则，我们将尝试将其转换为 STRUCT。
import duckdb
my_struct_dict = {
1: "one",
"2": 2,
"three": [1, 2, 3],
False: True
}
duckdb.values(my_struct_dict)
变为：
┌────────────────────────────────────────────────────────────────────┐
│ {'1': 'one', '2': 2, 'three': [1, 2, 3], 'False': true} │
│ struct("1" varchar, "2" integer, three integer[], "false" boolean) │
├────────────────────────────────────────────────────────────────────┤
│ {'1': one, '2': 2, 'three': [1, 2, 3], 'False': true} │
└────────────────────────────────────────────────────────────────────┘
如果字典由函数返回，由于自动转换，该函数将返回一个 MAP。要返回 STRUCT，必须提供 return_type。
import duckdb
from duckdb.sqltypes import BOOLEAN, INTEGER, VARCHAR
from duckdb import list_type, struct_type
duckdb_conn = duckdb.connect()
my_struct_dict = {
1: "one",
"2": 2,
"three": [1, 2, 3],
False: True
}
def get_struct() -> dict[str|int|bool,str|int|list[int]|bool]:
return my_struct_dict
duckdb_conn.create_function("get_struct_as_map", get_struct)
duckdb_conn.sql("select get_struct_as_map()").show()
duckdb_conn.create_function("get_struct", get_struct, return_type=struct_type({
1: VARCHAR,
"2": INTEGER,
"three": list_type(INTEGER),
False: BOOLEAN
}))
duckdb_conn.sql("select get_struct()").show()
┌──────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ get_struct_as_map() │
│ map(union(u1 varchar, u2 bigint, u3 boolean), union(u1 varchar, u2 bigint, u3 bigint[], u4 boolean)) │
├──────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ {1=one, 2=2, three=[1, 2, 3], false=true} │
└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────────┐
│ get_struct() │
│ struct("1" varchar, "2" integer, three integer[], "false" boolean) │
├────────────────────────────────────────────────────────────────────┤
│ {'1': one, '2': 2, 'three': [1, 2, 3], 'False': true} │
└────────────────────────────────────────────────────────────────────┘
字典的每个
key都会被转换为字符串。
tuple
tuple 默认转换为 LIST；当用于构建 STRUCT 类型的 Value 对象时，它会转换为 STRUCT。
numpy.ndarray 和 numpy.datetime64
ndarray 和 datetime64 通过调用 tolist() 并转换其结果来完成转换。
结果转换：DuckDB 结果到 Python
DuckDB 的 Python 客户端提供了多种额外的方法，可用于高效地检索数据。
NumPy
fetchnumpy()以 NumPy 数组字典的形式获取数据。
Pandas
df()以 Pandas DataFrame 的形式获取数据。fetchdf()是df()的别名。fetch_df()是df()的别名。fetch_df_chunk(vector_multiple)将部分结果提取到 DataFrame 中。每个块中返回的行数是向量大小（默认为 2048）* vector_multiple（默认为 1）。
Apache Arrow
fetch_arrow_table()以 Arrow 表的形式获取数据。to_arrow_table()是fetch_arrow_table()的别名。arrow()返回一个 Arrow 记录批次读取器。fetch_record_batch(chunk_size)返回一个具有每批次chunk_size行的 Arrow 记录批次读取器。
Polars
pl()以 Polars DataFrame 的形式获取数据。
示例
以下是一些使用此功能的示例。请参阅 Python 指南以获取更多示例。
以 Pandas DataFrame 获取
df = con.execute("SELECT * FROM items").fetchdf()
print(df)
item value count
0 jeans 20.0 1
1 hammer 42.2 2
2 laptop 2000.0 1
3 chainsaw 500.0 10
4 iphone 300.0 2
以 NumPy 数组字典获取
arr = con.execute("SELECT * FROM items").fetchnumpy()
print(arr)
{'item': masked_array(data=['jeans', 'hammer', 'laptop', 'chainsaw', 'iphone'],
mask=[False, False, False, False, False],
fill_value='?',
dtype=object), 'value': masked_array(data=[20.0, 42.2, 2000.0, 500.0, 300.0],
mask=[False, False, False, False, False],
fill_value=1e+20), 'count': masked_array(data=[1, 2, 1, 10, 2],
mask=[False, False, False, False, False],
fill_value=999999,
dtype=int32)}
以 Arrow 表获取。随后转换为 Pandas 仅用于美观打印。
tbl = con.execute("SELECT * FROM items").fetch_arrow_table()
print(tbl.to_pandas())
item value count
0 jeans 20.00 1
1 hammer 42.20 2
2 laptop 2000.00 1
3 chainsaw 500.00 10
4 iphone 300.00 2