Python API

Установка

API DuckDB для Python можно установить с помощью pip: pip install duckdb. Подробную информацию см. на странице установки. Также возможно установить DuckDB с помощью conda: conda install python-duckdb -c conda-forge.

Версия Python: DuckDB требует Python версии 3.7 или выше.

Базовое использование API

Самый простой способ выполнения SQL-запросов с помощью DuckDB — использование команды duckdb.sql.

import duckdb

duckdb.sql("SELECT 42").show()

Это выполнит запросы с использованием базы данных в памяти, которая хранится глобально внутри модуля Python. Результат запроса возвращается как Relation. Relation — это символическое представление запроса. Запрос не выполняется до тех пор, пока результат не будет извлечен или не будет запрошено его отображение на экране.

На отношения можно ссылаться в последующих запросах, сохраняя их в переменных и используя их в качестве таблиц. Таким образом, запросы можно создавать поэтапно.

import duckdb

r1 = duckdb.sql("SELECT 42 AS i")
duckdb.sql("SELECT i * 2 AS k FROM r1").show()

Ввод данных

DuckDB может обрабатывать данные из различных форматов — как хранящиеся на диске, так и в памяти. Дополнительную информацию см. на странице обработки данных.

import duckdb

duckdb.read_csv("example.csv")                # read a CSV file into a Relation
duckdb.read_parquet("example.parquet")        # read a Parquet file into a Relation
duckdb.read_json("example.json")              # read a JSON file into a Relation

duckdb.sql("SELECT * FROM 'example.csv'")     # directly query a CSV file
duckdb.sql("SELECT * FROM 'example.parquet'") # directly query a Parquet file
duckdb.sql("SELECT * FROM 'example.json'")    # directly query a JSON file

DataFrames

DuckDB может напрямую выполнять запросы к Pandas DataFrame, Polars DataFrame и Arrow таблицам. Обратите внимание, что эти объекты доступны только для чтения, т.е. редактирование этих таблиц с помощью INSERT или UPDATE невозможно.

Pandas

Для непосредственного запроса Pandas DataFrame выполните:

import duckdb
import pandas as pd

pandas_df = pd.DataFrame({"a": [42]})
duckdb.sql("SELECT * FROM pandas_df")

┌───────┐
│   a   │
│ int64 │
├───────┤
│    42 │
└───────┘

Polars

Для непосредственного запроса Polars DataFrame выполните:

import duckdb
import polars as pl

polars_df = pl.DataFrame({"a": [42]})
duckdb.sql("SELECT * FROM polars_df")

┌───────┐
│   a   │
│ int64 │
├───────┤
│    42 │
└───────┘

PyArrow

Для непосредственного запроса PyArrow таблицы выполните:

import duckdb
import pyarrow as pa

arrow_table = pa.Table.from_pydict({"a": [42]})
duckdb.sql("SELECT * FROM arrow_table")

┌───────┐
│   a   │
│ int64 │
├───────┤
│    42 │
└───────┘

Преобразование результатов

DuckDB поддерживает эффективное преобразование результатов запросов в различные форматы. Дополнительную информацию см. на странице преобразования результатов.

import duckdb

duckdb.sql("SELECT 42").fetchall()   # Python objects
duckdb.sql("SELECT 42").df()         # Pandas DataFrame
duckdb.sql("SELECT 42").pl()         # Polars DataFrame
duckdb.sql("SELECT 42").arrow()      # Arrow Table
duckdb.sql("SELECT 42").fetchnumpy() # NumPy Arrays

Запись данных на диск

DuckDB поддерживает запись объектов Relation непосредственно на диск в различных форматах. Для записи данных на диск с помощью SQL можно использовать COPY команду.

import duckdb

duckdb.sql("SELECT 42").write_parquet("out.parquet") # Write to a Parquet file
duckdb.sql("SELECT 42").write_csv("out.csv")         # Write to a CSV file
duckdb.sql("COPY (SELECT 42) TO 'out.parquet'")      # Copy to a Parquet file

Параметры подключения

Приложения могут открыть новое подключение к DuckDB с помощью метода duckdb.connect().

Использование базы данных в памяти

При использовании DuckDB через duckdb.sql(), он работает с базой данных в памяти, то есть таблицы не сохраняются на диске. Вызов метода duckdb.connect() без аргументов возвращает подключение, которое также использует базу данных в памяти:

import duckdb

con = duckdb.connect()
con.sql("SELECT 42 AS x").show()

Постоянное хранилище

Метод duckdb.connect(dbname) создает подключение к постоянной базе данных. Любые данные, записанные в это подключение, будут сохранены и могут быть загружены повторно, подключившись к тому же файлу, как из Python, так и из других клиентов DuckDB.

import duckdb

# create a connection to a file called 'file.db'
con = duckdb.connect("file.db")
# create a table and load data into it
con.sql("CREATE TABLE test (i INTEGER)")
con.sql("INSERT INTO test VALUES (42)")
# query the table
con.table("test").show()
# explicitly close the connection
con.close()
# Note: connections also closed implicitly when they go out of scope

Также можно использовать менеджер контекста для обеспечения закрытия подключения:

import duckdb

with duckdb.connect("file.db") as con:
    con.sql("CREATE TABLE test (i INTEGER)")
    con.sql("INSERT INTO test VALUES (42)")
    con.table("test").show()
    # the context manager closes the connection automatically

Настройка

Метод duckdb.connect() принимает словарь config, где можно указать параметры конфигурации. Например:

import duckdb

con = duckdb.connect(config = {'threads': 1})

Объект подключения и модуль

Объект подключения и модуль duckdb могут использоваться взаимозаменяемо — они поддерживают одинаковые методы. Единственное различие заключается в том, что при использовании модуля duckdb используется глобальная база данных в памяти.

Если вы разрабатываете пакет, предназначенный для использования другими, и используете DuckDB в пакете, рекомендуется создавать объекты подключения, а не использовать методы модуля duckdb. Это связано с тем, что модуль duckdb использует общую глобальную базу данных, что может привести к трудноотлаживаемым проблемам, если он используется из нескольких разных пакетов.

Использование подключений в параллельных программах Python

Объект DuckDBPyConnection не потокобезопасен. Если вы хотите записывать в ту же базу данных из нескольких потоков, создайте курсор для каждого потока с помощью метода DuckDBPyConnection.cursor().

Загрузка и установка расширений

API Python DuckDB предоставляет функции для установки и загрузки расширений, которые выполняют эквивалентные операции для выполнения SQL-команд INSTALL и LOAD соответственно. Пример установки и загрузки spatial расширения выглядит следующим образом:

import duckdb

con = duckdb.connect()
con.install_extension("spatial")
con.load_extension("spatial")

Расширения сообщества

Для загрузки расширений сообщества используйте аргумент repository="community" метода install_extension.

Например, установите и загрузите h3 расширение сообщества следующим образом:

import duckdb

con = duckdb.connect()
con.install_extension("h3", repository="community")
con.load_extension("h3")

Неподписанные расширения

Для загрузки неподписанных расширений используйте аргумент config = {"allow_unsigned_extensions": "true"} метода duckdb.connect().