本页面包含使用DuckDB将数据导入Python的示例。首先，导入DuckDB页面：
import duckdb
然后，继续以下任何部分。
CSV Files
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 Files
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 Files
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')")
直接访问DataFrames和Arrow对象
DuckDB 能够通过引用变量名称自动查询某些 Python 变量（就像它是一个表一样）。 这些类型包括以下内容：Pandas DataFrame、Polars DataFrame、Polars LazyFrame、NumPy 数组、relations 和 Arrow 对象。
只有在sql()或execute()调用位置对Python代码可见的变量才能以这种方式使用。
通过替换扫描可以访问这些变量。要完全禁用替换扫描，请使用：
SET python_enable_replacements = false;
DuckDB 支持查询多种类型的 Apache Arrow 对象，包括 tables、datasets、RecordBatchReaders 和 scanners。更多示例请参阅 Python guides。
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 数据框 – object 列
pandas.DataFrame 的 object 类型的列需要特别注意，因为这种类型存储的是任意类型的值。
要将这些列转换为 DuckDB，我们首先在转换值之前进行一个分析阶段。
在这个分析阶段中，会对列的所有行进行采样分析，以确定目标类型。
默认情况下，这个采样大小设置为 1000。
如果在分析步骤中选择的类型不正确，将会导致“无法转换值：”错误，在这种情况下，您需要增加采样大小。
可以通过设置 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表和视图
- 替换扫描