DuckDB можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. DuckDB запускается внутри Python-процесса и умеет читать CSV напрямую, поэтому для первого аналитического запроса не нужен сервер базы данных. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.
Начинающий аналитик часто тратит больше времени на импорт файла и настройку СУБД, чем на сам вопрос к данным. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте скрипт, который читает продажи из CSV, группирует их по категории и возвращает аккуратную таблицу. Проверка: запрос считает одинаковую сумму при повторном запуске, пропускает пустые значения по заданному правилу и показывает три строки результата.
создать sales.csv с заголовками category, price и quantity. Не расширяйте проект до первого успешного запуска.
фильтр оставляет только строки с положительным количеством. Проверяйте значение, а не отсутствие ошибки.
После успеха добавьте категорию с двумя продажами и заранее посчитайте ожидаемую сумму. Так копирование станет практикой.
Как устроен учебный проект DuckDB
CSV остаётся исходным файлом, DuckDB выполняет SQL локально, а Python отвечает за запуск запроса и дальнейшую обработку результата. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.
| Этап | Действие | Проверяемый результат |
|---|---|---|
| Файл | создать sales.csv с заголовками category, price и quantity | CSV читается как таблица с понятными типами |
| Запрос | проверить данные через SELECT и WHERE | фильтр оставляет только строки с положительным количеством |
| Агрегация | сгруппировать категории и посчитать price * quantity | SQL возвращает сумму и число заказов по категории |
| Результат | получить DataFrame и отсортировать значения | в консоли видна итоговая таблица без запуска сервера |
Контрольные точки: файл, запрос, агрегация и результат. Следующий шаг начинается после совпадения с ожидаемым результатом.
От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.
SELECT * FROM read_csv_auto('sales.csv') LIMIT 3 и проверьте имена и типы колонок до агрегации. Сохраните команду запуска и ожидаемый вывод.Собираем рабочий пример шаг за шагом
Пример сверялся с актуальной документацией официальной документации DuckDB Python API на 19 октября 2026 года. Создайте окружение командой uv init, затем добавьте зависимости: uv add duckdb pandas. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.
import duckdb
query = """
SELECT
category,
COUNT(*) AS orders,
ROUND(SUM(price * quantity), 2) AS revenue
FROM read_csv_auto('sales.csv')
WHERE quantity > 0 AND price IS NOT NULL
GROUP BY category
ORDER BY revenue DESC
"""
result = duckdb.sql(query).df()
print(result)
print("total:", round(result["revenue"].sum(), 2))- Таблица содержит колонки
category,ordersиrevenue. - Категории отсортированы от большей выручки к меньшей, а итог совпадает с суммой строк.
- Повторный запуск даёт тот же предсказуемый результат.
- Пустой ввод получает понятное сообщение вместо падения.
SQL описывает преобразование данных, DuckDB выполняет его, а метод .df() передаёт небольшой итог в pandas. Найдите в примере вход, проверку и место формирования результата.
Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.
Что происходит внутри и почему это работает
read_csv_auto создаёт табличное представление файла и пытается определить типы колонок. Фильтр выполняется до группировки, поэтому некорректные строки не попадают в сумму. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Для больших файлов выгоднее сначала выбрать нужные колонки и агрегировать их в DuckDB, а не загружать весь CSV в pandas.
| Часть | За что отвечает | Что проверить |
|---|---|---|
| Источник | read_csv_auto читает CSV и определяет схему | названия, разделитель и типы совпадают с ожиданием |
| SQL | WHERE очищает поток, GROUP BY собирает категории | ручная сумма двух строк совпадает с запросом |
| Python | запускает запрос и получает небольшой итоговый DataFrame | повторный запуск не зависит от старого состояния |
Автоматическое определение типов удобно для старта, но не является обещанием качества данных. Если в колонке price встречается слово, тип может измениться или чтение завершится ошибкой. Для устойчивого проекта задавайте типы явно и храните проверку схемы рядом с запросом. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.
Проверяем проект и добавляем свою функцию
Добавьте колонку date и второй запрос, который считает выручку по месяцам. Не меняйте исходный CSV во время выполнения программы. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.
- Сохраните ожидаемый результат: запрос считает одинаковую сумму при повторном запуске, пропускает пустые значения по заданному правилу и показывает три строки результата.
- Измените правило: добавьте категорию с двумя продажами и заранее посчитайте ожидаемую сумму. Сначала предскажите итог.
- Передайте граничное значение и убедитесь, что приложение не падает.
- Верните корректные данные и объясните роли трёх основных частей.
- CSV читается как таблица с понятными типами
- фильтр оставляет только строки с положительным количеством
- SQL возвращает сумму и число заказов по категории
- в консоли видна итоговая таблица без запуска сервера
DuckDB особенно полезен, когда SQL должен обработать много строк, а в Python нужен только компактный итог. Полезная правка проходит от нового ввода до видимого результата.
Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.
Что запомнить и куда двигаться дальше
Следующий шаг - сохранить запрос в отдельный файл, указать типы CSV и добавить проверку контрольной суммы. Сервер понадобится только когда данные и доступ должны разделять разные процессы и пользователи. Для закрепления откройте в разборе CSV через pandas, в статье про COUNT и в статье про ORDER BY.
Как изучить тему в Кодике
Сначала закрепите SELECT, WHERE, GROUP BY и ORDER BY на пяти строках, затем переносите запрос на большой CSV. Сначала восстановите главную функцию и проверьте её на трёх значениях.
| Шаг | Что разобрать | Мини-проверка |
|---|---|---|
| 1. Основа | Таблицы, типы, NULL и арифметику в SQL | Объясните вход и выход функции. |
| 2. Инструмент | read_csv_auto, DESCRIBE и получение DataFrame | Повторите команду по памяти. |
| 3. Проект | Агрегацию продаж с фильтром и сортировкой | Проверьте два сценария. |
| 4. Рефакторинг | Явную схему CSV и тест контрольной суммы | Разделите ввод, логику и вывод. |
Если итог неверен, проверяйте не pandas, а количество строк после каждого SQL-этапа. Базовый синтаксис закрепите через курс SQL.
DuckDB не находит sales.csv. Печатайте абсолютный путь или запускайте скрипт из корня проекта.
Цена прочитана как VARCHAR из-за грязной строки. Проверьте DESCRIBE и задайте тип.
Любая арифметика с NULL даёт NULL. Определите правило: исключить строку или подставить значение.
Передача всех строк в pandas тратит память. Сначала фильтруйте и агрегируйте в SQL.
Что получится в итоге
Так выглядит законченный учебный проект: есть понятный вход, видимый результат, защита от неверных данных и место для следующего улучшения.
Нужен ли отдельный сервер для DuckDB в этом примере?
Нет. База работает внутри Python-процесса и читает локальный файл напрямую.
Почему фильтр стоит до GROUP BY?
Он исключает некорректные строки до подсчёта количества и суммы.
Что проверять первым, если DuckDB не запускается?
Версию среды, текущую папку, команду запуска и первую строку ошибки.
Как понять, что проект DuckDB работает?
Проверьте основной сценарий, неверный ввод, повторный запуск и один граничный случай.
Можно ли начать с готового кода?
Да. Добейтесь результата, измените одно правило и восстановите ключевую функцию без копирования.
Выберите одно улучшение и проведите его от ввода до результата.
Если не хватает основы, перейдите курс SQL, затем восстановите ключевую функцию без подсказки.