此页面包含使用 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 变量名（如同它是一个表）来自动查询某些 Python 变量。这些类型包括：Pandas DataFrame、Polars DataFrame、Polars LazyFrame、NumPy 数组、关系和 Arrow 对象。

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

SET python_enable_replacements = false;

DuckDB 支持查询多种 Apache Arrow 对象类型，包括表、数据集、RecordBatchReaders 和扫描器。有关更多示例，请参阅 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。如果在分析步骤中选择的类型不正确，这将导致“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 表和视图
• 替换扫描