Аналитики по магазину на СУБД ClickHouse и FastAPI

Реализация различиных аналитик по данным магазина (pet-пример) на Python 3.13, FastAPI и ClickHouse.

Содержание

• SQL запросы (задание 2.1 и 2.2): sql/queries.sql
• View для отчета (задание 2.3.1): sql/views.sql
• Оптимизации (задание 2.3.2): docs/optimizations.md
• Тестовые данные: sql/seed.sql
• Даталогическая схема и пояснения: docs/schema.md

Стек технологий

• Python 3.13
• FastAPI (async)
• SQLAlchemy 2.x
• ClickHouse + clickhouse-sqlalchemy (asynch)
• uv (менеджер зависимостей)
• ruff (линтинг/форматирование)
• ty (type checker)
• Docker / Docker Compose

Структура проекта

app/
  api/            # HTTP слой
  core/           # конфиги, ошибки, логирование
  db/             # engine + init_db + ORM base/session
  models/         # ORM модели по таблицам
  schemas/        # pydantic схемы
  services/       # бизнес-логика
  utils/          # утилиты и декораторы
sql/
  queries.sql
  views.sql
  seed.sql
docs/
  schema.md
  optimizations.md

Пререквизиты

• Python
• uv
• Docker и Docker Compose

Запуск

1. Установить зависимости:

uv sync --no-dev

2. Поднять всё приложение:

docker-compose up --build

3. Применить view:

docker compose exec -T clickhouse clickhouse-client --multiquery < sql/views.sql

4. Загрузить тестовые данные:

docker compose exec -T clickhouse clickhouse-client --multiquery < sql/seed.sql

REST API

После запуска сервиса можно обратиться к API и добавить товар в заказ:

POST http://localhost:8000/orders/{order_id}/items с JSON‑телом:

{
  "item_id": <item-id>,
  "qty": <qty>
}

Пример для заказа 7003 (из сид-данных):

POST http://localhost:8000/orders/7003/items
{
  "item_id": 1002,
  "qty": 3
}

Ответ:

{
  "order_id": 7003,
  "item_id": 1002,
  "qty": 5,
  "price": 27990.00,
  "total": 139950.00
}

Ошибки:

• 404 — заказ или товар не найдены
• 409 — недостаточно товара на складе

Сброс БД (полная переинициализация)

Если нужно пересоздать БД с нуля (очистить все данные):

docker compose down -v
docker compose up --build
docker compose exec -T clickhouse clickhouse-client --multiquery < sql/seed.sql
docker compose exec -T clickhouse clickhouse-client --multiquery < sql/views.sql

SQL-Запросы (через clickhouse-client в контейнере)

SQL‑запросы, выполняющие простую аналитику, лежат в sql/queries.sql и sql/views.sql. Их можно запускать через контейнер ClickHouse:

docker compose exec -T clickhouse clickhouse-client --multiquery < sql/views.sql
docker compose exec -T clickhouse clickhouse-client --query "SELECT * FROM top5_items_last_month FORMAT PrettyCompact"

sql/queries.sql уже содержит разделители и FORMAT PrettyCompact, чтобы вывод был аккуратнее в терминале.

docker compose exec -T clickhouse clickhouse-client --multiquery < sql/queries.sql

Допущения

• Для async‑драйвера ClickHouse (asynch < 0.3.0) в SQLAlchemy 2.x использовал костыльный "патч" (см. app/db/compat.py).