Ввод данных

Эта страница содержит примеры ввода данных в Python с использованием DuckDB. Сначала импортируйте страницу 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"])

Непосредственное чтение файла CSV из SQL:

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

Вызов read_csv из SQL:

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

Чтение файла Parquet по протоколу https:

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

Чтение списка файлов Parquet:

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

Непосредственное чтение файла Parquet из SQL:

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

Вызов read_parquet из SQL:

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

Непосредственное чтение файла JSON из SQL:

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

Вызов read_json из SQL:

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

Непосредственный доступ к DataFrame и объектам Arrow

DuckDB может автоматически обращаться к определенным переменным Python, ссылаясь на их имя (как если бы это была таблица). К этим типам относятся: Pandas DataFrame, Polars DataFrame, Polars LazyFrame, NumPy массивы, отношения и объекты Arrow. Доступ к ним обеспечивается замещающими сканированиями.

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')]

Вы также можете создать постоянную таблицу в DuckDB на основе содержимого DataFrame (или представления):

# 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 DataFrame – столбцы 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")

Регистрация объектов

Вы можете зарегистрировать объекты Python в качестве таблиц DuckDB с помощью функции DuckDBPyConnection.register().

Порядок приоритетов объектов с одинаковыми именами следующий:

• Объекты, явно зарегистрированные с помощью DuckDBPyConnection.register()
• Оригинальные таблицы и представления DuckDB
• Замещающие сканирования