本页面包含使用 DuckDB 将数据摄入 Python 的示例。首先，导入 DuckDB 包

import duckdb

然后，继续执行以下任一部分。

CSV 文件

CSV 文件可以使用 read_csv 函数读取，该函数既可以在 Python 内部调用，也可以直接在 SQL 内部调用。默认情况下，read_csv 函数会通过对提供的文件进行采样来尝试自动检测 CSV 设置。

使用完全自动检测的设置从文件读取

duckdb.read_csv("example.csv")

从文件夹读取多个 CSV 文件

duckdb.read_csv("folder/*.csv")

指定 CSV 内部格式的选项

duckdb.read_csv("example.csv", header = False, sep = ",")

覆盖前两列的类型

duckdb.read_csv("example.csv", dtype = ["int", "varchar"])

在 SQL 内部直接读取 CSV 文件

duckdb.sql("SELECT * FROM 'example.csv'")

在 SQL 内部调用 read_csv

duckdb.sql("SELECT * FROM read_csv('example.csv')")

更多信息，请参阅 CSV 导入页面。

Parquet 文件

Parquet 文件可以使用 read_parquet 函数读取，该函数既可以在 Python 内部调用，也可以直接在 SQL 内部调用。

从单个 Parquet 文件读取

duckdb.read_parquet("example.parquet")

从文件夹读取多个 Parquet 文件

duckdb.read_parquet("folder/*.parquet")

通过 https 读取 Parquet 文件

duckdb.read_parquet("https://some.url/some_file.parquet")

读取 Parquet 文件列表

duckdb.read_parquet(["file1.parquet", "file2.parquet", "file3.parquet"])

在 SQL 内部直接读取 Parquet 文件

duckdb.sql("SELECT * FROM 'example.parquet'")

在 SQL 内部调用 read_parquet

duckdb.sql("SELECT * FROM read_parquet('example.parquet')")

更多信息，请参阅 Parquet 加载页面。

JSON 文件

JSON 文件可以使用 read_json 函数读取，该函数既可以在 Python 内部调用，也可以直接在 SQL 内部调用。默认情况下，read_json 函数会自动检测文件是否包含换行符分隔的 JSON 或普通 JSON，并会检测 JSON 文件中存储对象的模式。

从单个 JSON 文件读取

duckdb.read_json("example.json")

从文件夹读取多个 JSON 文件

duckdb.read_json("folder/*.json")

在 SQL 内部直接读取 JSON 文件

duckdb.sql("SELECT * FROM 'example.json'")

在 SQL 内部调用 read_json

duckdb.sql("SELECT * FROM read_json_auto('example.json')")

直接访问 DataFrame 和 Arrow 对象

DuckDB 能够通过引用变量名称（就像引用表一样）自动查询某些 Python 变量。这些类型包括：Pandas DataFrame、Polars DataFrame、Polars LazyFrame、NumPy 数组、关系 (relations) 和 Arrow 对象。

只有在 sql() 或 execute() 调用位置对 Python 代码可见的变量才能以这种方式使用。访问这些变量是通过替换扫描 (replacement scans) 实现的。要完全禁用替换扫描，请使用

SET python_enable_replacements = false;

DuckDB 支持查询多种类型的 Apache Arrow 对象，包括 表 (tables)、数据集 (datasets)、RecordBatchReaders 和 扫描器 (scanners)。更多示例请参阅 Python 指南。

import duckdb
import pandas as pd

test_df = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
print(duckdb.sql("SELECT * FROM test_df").fetchall())

[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]

DuckDB 还支持将 DataFrame 或 Arrow 对象“注册”为虚拟表，这类似于 SQL VIEW。当查询以其他方式存储（如类变量或字典中的值）的 DataFrame/Arrow 对象时，这非常有用。以下是 Pandas 的示例

如果您的 Pandas DataFrame 存储在其他位置，这里有一个手动注册它的示例

import duckdb
import pandas as pd

my_dictionary = {}
my_dictionary["test_df"] = pd.DataFrame.from_dict({"i": [1, 2, 3, 4], "j": ["one", "two", "three", "four"]})
duckdb.register("test_df_view", my_dictionary["test_df"])
print(duckdb.sql("SELECT * FROM test_df_view").fetchall())

[(1, 'one'), (2, 'two'), (3, 'three'), (4, 'four')]

您还可以从 DataFrame（或视图）的内容在 DuckDB 中创建持久表

# create a new table from the contents of a DataFrame
con.execute("CREATE TABLE test_df_table AS SELECT * FROM test_df")
# insert into an existing table from the contents of a DataFrame
con.execute("INSERT INTO test_df_table SELECT * FROM test_df")

Pandas DataFrames – object 列

pandas.DataFrame 的 object dtype 列需要特别小心，因为它们存储的是任意类型的值。为了将这些列转换为 DuckDB，我们先进行分析阶段，然后再转换这些值。在这个分析阶段，会对列中所有行的样本进行分析以确定目标类型。此样本大小默认为 1000。如果在分析步骤中选取的类型不正确，将会导致 Invalid Input Error: Failed to cast value，在这种情况下，您需要增加样本大小。可以通过设置 pandas_analyze_sample 配置选项来更改样本大小。

# example setting the sample size to 100k
duckdb.execute("SET GLOBAL pandas_analyze_sample = 100_000")

注册对象

您可以使用 DuckDBPyConnection.register() 函数将 Python 对象注册为 DuckDB 表。

同名对象的优先级如下

• 通过 DuckDBPyConnection.register() 显式注册的对象
• DuckDB 原生表和视图
• 替换扫描