跳到主要内容

数据导入

本页包含使用 Goose 在 Python 中进行数据导入的示例。首先，导入 Goose 包：

import goose

然后可以继续阅读以下任一部分。

CSV 文件​

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

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

goose.read_csv("example.csv")

读取文件夹中的多个 CSV 文件：

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

指定 CSV 内部格式选项：

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

覆盖前两列的类型：

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

直接在 SQL 中读取 CSV 文件：

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

在 SQL 中调用 read_csv：

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

更多信息请参见 CSV Import 页面。

Parquet 文件​

Parquet 文件可通过 read_parquet 函数读取，既可在 Python 中调用，也可直接在 SQL 中调用。

读取单个 Parquet 文件：

goose.read_parquet("example.parquet")

读取文件夹中的多个 Parquet 文件：

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

通过 https 读取 Parquet 文件：

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

读取 Parquet 文件列表：

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

直接在 SQL 中读取 Parquet 文件：

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

在 SQL 中调用 read_parquet：

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

更多信息请参见 Parquet Loading 页面。

JSON 文件​

JSON 文件可通过 read_json 函数读取，既可在 Python 中调用，也可直接在 SQL 中调用。默认情况下，read_json 会自动检测文件是换行分隔 JSON 还是普通 JSON，并检测 JSON 文件中对象的 schema。

读取单个 JSON 文件：

goose.read_json("example.json")

读取文件夹中的多个 JSON 文件：

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

直接在 SQL 中读取 JSON 文件：

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

在 SQL 中调用 read_json：

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

直接访问 DataFrame 和 Arrow 对象​

Goose 可以通过变量名（就像表名一样）自动查询某些 Python 变量。 这些类型包括：Pandas DataFrame、Polars DataFrame、Polars LazyFrame、NumPy arrays、relations 以及 Arrow 对象。

只有在调用 sql() 或 execute() 位置对 Python 代码可见的变量，才能以这种方式使用。 访问这些变量依赖于 replacement scans。若要完全禁用 replacement scans，请使用：

SET python_enable_replacements = false;

Goose 支持查询多种 Apache Arrow 对象，包括 tables、datasets、RecordBatchReaders 和 scanners。更多示例请参见 Python guides。

import goose
import pandas as pd

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

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

如果 Pandas DataFrame 存储在其他位置，下面是手动注册示例：

import goose
import pandas as pd

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

你也可以根据 DataFrame（或视图）的内容在 Goose 中创建持久化表：

# 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")

同名对象的优先级如下：

  • Objects explicitly registered via register()
  • Goose 原生表和视图
  • Replacement scans

Pandas DataFrames - object 列​

pandas.DataFrame 中 object dtype 的列需要特别注意，因为它可存储任意类型的值。 将这些列转换到 Goose 时，会先进行 analyze 阶段，再执行值转换。 在 analyze 阶段，会对该列所有行进行采样分析，以确定目标类型。 默认采样大小为 1000。 如果 analyze 阶段选择的类型不正确，会出现 Invalid Input Error: Failed to cast value，此时需要增大采样大小。 可通过设置 pandas_analyze_sample 配置项来调整采样大小。

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