Данные, SQL и аналитика

Работа аналитика — это постоянный контекст-свитчинг между SQL-клиентом, Jupyter-ноутбуком и документацией по схеме. Спросить «что за колонка product_id?» означает открыть DBeaver, найти таблицу, прочитать комментарий (если он есть), вернуться к ноутбуку и не забыть, что хотел написать. Claude Code сворачивает этот процесс: агент сам смотрит схему, генерирует SQL, верифицирует его и редактирует ноутбук — всё в одном контексте.

Быстрое повторение

Какая главная проблема в классическом workflow аналитика, которую решает Claude Code?

Подключение базы данных через MCP

Для большинства реляционных СУБД есть готовые MCP-серверы. Официальный для PostgreSQL — @modelcontextprotocol/server-postgres:

claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres \
  "postgresql://localhost/analytics"

После подключения агент получает инструменты: просмотр списка таблиц, чтение схемы конкретной таблицы и выполнение SQL-запросов. Всё это стандартные MCP-примитивы типа tool — подробнее о механизме в Model Context Protocol: архитектура и основы.

Чтобы зафиксировать конфигурацию для всей команды, добавьте сервер в .mcp.json в корне репозитория:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Секрет передаётся через переменную окружения, а не хранится в файле — обязательная практика для командных конфигов. О скоупах MCP-серверов (local, project, user) подробнее в Подключение MCP-серверов в Claude Code.

sequenceDiagram participant А as Аналитик participant CC as Claude Code participant MCP as Postgres MCP participant DB as PostgreSQL А->>CC: «Покажи выручку по категориям за Q1» CC->>MCP: describe_table(orders) MCP->>DB: INFORMATION_SCHEMA запрос DB-->>MCP: структура таблиц MCP-->>CC: схема orders, products, order_items CC->>MCP: execute_query(SELECT category, SUM(...)) MCP->>DB: выполняет запрос DB-->>MCP: агрегированные данные (20 строк) MCP-->>CC: результат CC-->>А: сводка + интерпретация

sequenceDiagram
    participant А as Аналитик
    participant CC as Claude Code
    participant MCP as Postgres MCP
    participant DB as PostgreSQL

    А->>CC: «Покажи выручку по категориям за Q1»
    CC->>MCP: describe_table(orders)
    MCP->>DB: INFORMATION_SCHEMA запрос
    DB-->>MCP: структура таблиц
    MCP-->>CC: схема orders, products, order_items
    CC->>MCP: execute_query(SELECT category, SUM(...))
    MCP->>DB: выполняет запрос
    DB-->>MCP: агрегированные данные (20 строк)
    MCP-->>CC: результат
    CC-->>А: сводка + интерпретация

Агентный цикл при работе с базой данных через Postgres MCP-сервер

Паттерны работы с SQL

«Схема первая» — фундамент хороших запросов

Первое правило: прежде чем просить SQL, дайте агенту схему. Когда Claude Code подключён к базе через MCP, он получает её автоматически при первом обращении. Без MCP — подложите явно:

Вот схема нашей аналитической БД:
@schema/analytics.sql

Напиши запрос, который считает выручку по категориям товаров
за последние 30 дней, с разбивкой по неделям.
Таблицы: orders, order_items, products.

Символ @ подгружает файл в контекст без лишних шагов — подробнее в CLAUDE.md и система памяти.

Итерация SQL в диалоге

SQL редко получается правильным с первого раза — особенно когда логика бизнес-метрик сложная. Работайте итерационно: первый запрос — как черновик, каждая следующая реплика — точечная правка:

[первый ответ — запрос сгенерирован]

Хорошо, но нужно исключить тестовые заказы (status = 'test')
и включить только завершённые (status IN ('shipped', 'delivered')).
Обнови запрос.

Диалог сохраняет контекст схемы и предыдущей логики, так что каждая поправка минимальная и точная.

Верификация через EXPLAIN и dry-run

Перед запуском тяжёлого аналитического запроса на продакшн-базе — запрашивайте план:

Перед выполнением сделай EXPLAIN ANALYZE и покажи план.
Если есть seq scan на таблице >10M строк —
предложи индекс или перепиши запрос.

Агент сам увидит, что join идёт по неиндексированной колонке, и предупредит до того, как запрос положил бы реплику. После EXPLAIN — отдельным сообщением: «теперь выполни».

Проверь себя

Зачем перед тяжёлым аналитическим запросом запускать EXPLAIN ANALYZE, а не сразу сам запрос? Когда это особенно важно?

Jupyter-ноутбуки: два пути

Claude Code поддерживает .ipynb-файлы через два разных механизма, существенно отличающихся по возможностям.

Встроенный NotebookEdit

Специальный инструмент, работающий «из коробки» без настройки. Он правильно парсит структуру .ipynb-файла: добавляет, заменяет и удаляет ячейки, очищает старые выводы при изменении кода.

Ограничения существенные: нет доступа к ядру — агент не может выполнить ячейку и посмотреть вывод. Кроме того, содержимое ячейки записывается как одна JSON-строка с \n, а не как массив строк, как это делает стандартный Jupyter, — это создаёт шум в git-диффе и может ломаться при ручном редактировании в JupyterLab.

NotebookEdit подходит для быстрых правок структуры: переименовать переменную по всему ноутбуку, добавить markdown-заголовок, переставить ячейки.

Jupyter MCP Server (рекомендуется для анализа)

Сторонний MCP-сервер с открытым кодом, который даёт агенту полный доступ к запущенному Jupyter-ядру: выполнять ячейки, читать вывод (текст, таблицы, графики), перехватывать ошибки и исправлять их в следующей ячейке. Это настоящий агентный цикл внутри ноутбука.

Настройка занимает около 10 минут:

# 1. Установить сервер
pip install jupyter-mcp-server

# 2. Запустить Jupyter
jupyter lab

# 3. Добавить в Claude Code
claude mcp add jupyter -- python -m jupyter_mcp_server

После этого Claude Code работает автономно: написал ячейку → выполнил → прочитал трейсбэк → исправил → запустил снова. Именно такой цикл нужен для EDA.

Проверь себя

Вам нужно написать код для EDA, запустить его и по выводу решить, что делать дальше. NotebookEdit или Jupyter MCP Server? Почему?

Паттерны разведочного анализа (EDA)

Типичная EDA-сессия с Jupyter MCP Server строится пошагово — один вопрос за раз.

Шаг 1 — обзор датасета:

Загрузи data/transactions_2024.csv в pandas,
покажи форму, типы колонок, долю пропусков
и базовую статистику по числовым полям.

Шаг 2 — целевой вопрос:

Топ-10 категорий по сумме транзакций за Q4.
Построй bar chart с seaborn, отсортируй по убыванию.

Шаг 3 — аномалии:

Есть ли выбросы в колонке amount? Используй IQR-метод.
Если есть — покажи на boxplot и выведи долю от общего числа строк.

Ключевое: «Проанализируй всё» — плохой промпт для EDA. Агент начинает строить случайные графики без понимания цели. Задавайте конкретный вопрос, смотрите результат, формулируйте следующий.

Для дата-инженеров: dbt и ETL

Claude Code хорошо ложится в инженерный стек.

dbt-проекты. Агент читает модели, схему sources и понимает контекст трансформаций. Типичный промпт:

Посмотри на @models/staging/stg_orders.sql
и соответствующий @schema.yml.

Напиши intermediate-модель int_orders_enriched, которая добавляет:
- полное имя клиента из dim_customers
- категорию товара из dim_products

Включи описания колонок в schema.yml.

Агент генерирует модель, grain-комментарии и тесты — в стиле существующих файлов рядом.

Дебаг ETL-пайплайнов. Если упал Airflow-DAG, дайте агенту лог и путь к файлу:

Вот лог упавшего DAG:
[paste error]

Найди причину в @dags/load_transactions.py и предложи фикс.

Автодокументация. Агент хорошо пишет SQL-комментарии и dbt-описания — особенно если рядом есть примеры из хорошо задокументированных моделей. Дайте два-три образца, и новые модели будут выдержаны в том же стиле.

Ограничения и осторожность

Права доступа. Подключайте агента через пользователя с минимальными привилегиями. Для аналитических задач достаточно SELECT и CREATE TEMP TABLE. Давать агенту DROP, TRUNCATE или UPDATE на продакшн-базе — плохая идея вне зависимости от настроек разрешений Claude Code.

Большие результаты съедают контекст. Если запрос возвращает 500 000 строк, а агент пытается вывести их в диалог — контекст быстро кончится. Всегда добавляйте LIMIT к разведочным запросам или просите агента агрегировать данные вместо выгрузки сырых строк. О стратегиях контроля контекста — в Управление контекстным окном.

SQL нужно проверять. Агент уверенно генерирует запросы, которые выглядят правильно, но могут содержать логические ошибки: неправильная гранулярность join, пропущенные фильтры по партиции, неожиданная дедупликация. Всегда проверяйте результат на небольшой выборке (LIMIT 100, WHERE date = '2024-01-01') прежде чем запускать на полном датасете.

NotebookEdit ≠ запуск кода. Не ждите от встроенного инструмента результатов выполнения ячеек — их там нет. Если нужен настоящий цикл «написал → запустил → исправил», потратьте 10 минут на Jupyter MCP Server.