Jupyter Notebooks

Клиент Python для DuckDB может использоваться непосредственно в Jupyter notebooks без дополнительной конфигурации, если это необходимо. Однако, для упрощения разработки запросов SQL можно использовать дополнительные библиотеки. Это руководство опишет, как использовать эти дополнительные библиотеки. Обратитесь к другим руководствам в разделе Python, чтобы узнать, как использовать DuckDB и Python вместе.

В этом примере мы используем пакет JupySQL.

Этот примерный рабочий процесс также доступен в виде Google Colab notebook.

Установка библиотек

Четыре дополнительные библиотеки улучшают работу с DuckDB в Jupyter notebooks.

1. jupysql: Преобразует ячейку кода Jupyter в ячейку SQL
2. Pandas: Очистка визуализации таблиц и совместимость с другими анализами
3. matplotlib: Визуализация с помощью Python
4. duckdb-engine (DuckDB SQLAlchemy driver): Используется SQLAlchemy для подключения к DuckDB (необязательно)

Выполните эти pip install команды из командной строки, если Jupyter Notebook еще не установлен. В противном случае, см. ссылку на Google Colab выше для примера в среде ноутбука:

pip install duckdb

Установка Jupyter Notebook

pip install notebook

Или JupyterLab:

pip install jupyterlab

Установка поддерживающих библиотек:

pip install jupysql pandas matplotlib duckdb-engine

Импорт и настройка библиотек

Откройте Jupyter Notebook и импортируйте необходимые библиотеки.

Подключение к DuckDB напрямую

Для подключения к DuckDB выполните:

import duckdb
import pandas as pd

%load_ext sql
conn = duckdb.connect()
%sql conn --alias duckdb

Подключение к DuckDB через SQLAlchemy с использованием duckdb_engine

В качестве альтернативы, можно подключиться к DuckDB через SQLAlchemy с использованием duckdb_engine. См. различия в производительности и функциях.

import duckdb
import pandas as pd
# No need to import duckdb_engine
#  jupysql will auto-detect the driver needed based on the connection string!

# Import jupysql Jupyter extension to create SQL cells
%load_ext sql

Установите конфигурации в jupysql, чтобы напрямую выводить данные в Pandas и упростить вывод, отображаемый в ноутбуке.

%config SqlMagic.autopandas = True
%config SqlMagic.feedback = False
%config SqlMagic.displaycon = False

Подключите jupysql к DuckDB с использованием строки подключения в стиле SQLAlchemy. Подключитесь к новой памяти DuckDB, стандартному подключению или базе данных на основе файла:

%sql duckdb:///:memory:

%sql duckdb:///:default:

%sql duckdb:///path/to/file.db

Команда %sql и duckdb.sql используют одно стандартное подключение, если вы укажете duckdb:///:default: в качестве строки подключения SQLAlchemy.

Запросы к DuckDB

Запросы SQL из одной строки можно выполнить, используя %sql в начале строки. Результаты запроса будут отображены как таблица Pandas.

%sql SELECT 'Off and flying!' AS a_duckdb_column;

Целую ячейку Jupyter можно использовать как ячейку SQL, поместив %%sql в начале ячейки. Результаты запроса будут отображены как таблица Pandas.

%%sql
SELECT
    schema_name,
    function_name
FROM duckdb_functions()
ORDER BY ALL DESC
LIMIT 5;

Для сохранения результатов запроса в переменной Python используйте << как оператор присваивания. Это можно использовать как с магическими командами %sql, так и %%sql Jupyter.

%sql res << SELECT 'Off and flying!' AS a_duckdb_column;

Если опция %config SqlMagic.autopandas = True установлена, переменная представляет собой таблицу Pandas, в противном случае это объект ResultSet, который можно преобразовать в Pandas с помощью функции DataFrame().

Запросы к таблицам Pandas

DuckDB может находить и выполнять запросы к любой таблице, хранящейся как переменная в Jupyter notebook.

input_df = pd.DataFrame.from_dict({"i": [1, 2, 3],
                                   "j": ["one", "two", "three"]})

Таблица, к которой выполняется запрос, может быть указана так же, как и любая другая таблица в FROM.

%sql output_df << SELECT sum(i) AS total_i FROM input_df;

Визуализация данных DuckDB

Наиболее распространённый способ построения графиков набора данных в Python — загрузить их с помощью Pandas, а затем использовать matplotlib или seaborn для построения графиков. Этот подход требует загрузки всех данных в память, что очень неэффективно. Модуль построения графиков в JupySQL выполняет вычисления в SQL-движке. Это делегирует управление памятью движку и гарантирует, что промежуточные вычисления не будут постоянно потреблять память, эффективно строя графики огромных наборов данных.

Установка и загрузка расширения DuckDB httpfs

Расширение httpfs DuckDB позволяет выполнять запросы к файлам Parquet и CSV удалённо по протоколу http. В этих примерах выполняется запрос к файлу Parquet, содержащему исторические данные о такси из Нью-Йорка. Использование формата Parquet позволяет DuckDB извлекать в память только необходимые строки и столбцы, а не загружать весь файл. DuckDB также может обрабатывать локальные Parquet файлы, что может быть желательно, если требуется запрос ко всему файлу Parquet или выполнение нескольких запросов, требующих больших подмножеств файла.

%%sql
INSTALL httpfs;
LOAD httpfs;

Диаграмма размаха и гистограмма

Чтобы создать диаграмму размаха, вызовите %sqlplot boxplot, передав имя таблицы и столбец для построения графика. В данном случае, имя таблицы — это URL удалённо хранящегося файла Parquet.

%sqlplot boxplot --table https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2021-01.parquet --column trip_distance

Теперь создайте запрос, фильтрующий по 90-му процентилю. Обратите внимание на использование функций --save и --no-execute. Это сообщает JupySQL сохранить запрос, но пропустить его выполнение. Он будет использован в следующем вызове построения графика.

%%sql --save short_trips --no-execute
SELECT *
FROM 'https://d37ci6vzurychx.cloudfront.net/trip-data/yellow_tripdata_2021-01.parquet'
WHERE trip_distance < 6.3

Чтобы создать гистограмму, вызовите %sqlplot histogram и передайте имя таблицы, столбец для построения графика и количество интервалов. Используется --with short-trips, поэтому JupySQL использует ранее определённый запрос и, следовательно, строит график только для подмножества данных.

%sqlplot histogram --table short_trips --column trip_distance --bins 10 --with short_trips

Заключение

Теперь вы можете свободно переключаться между SQL и Pandas простым и высокопроизводительным способом! Вы можете строить графики огромных наборов данных непосредственно через движок (избегая как загрузки всего файла, так и загрузки всего его в память Pandas). Таблицы Pandas можно читать как таблицы в SQL, а результаты SQL можно выводить в таблицы Pandas. Удачных анализов!