Отладка DataStore

Отлаживайте операции DataStore с помощью explain(), данных профилирования и логирования

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

​

Обзор инструментов для отладки

Инструмент	Назначение	Когда использовать
explain()	Просмотр плана выполнения	Понять, какой SQL будет выполнен
профилировщик	Измерение производительности	Найти медленные операции
Логирование	Просмотр деталей выполнения	Разобраться в неожиданном поведении

​

Краткая матрица выбора

Потребность	Инструмент	Команда
Посмотреть план выполнения	explain()	ds.explain()
Измерить производительность	Профилировщик	config.enable_profiling()
Отладить SQL-запросы	Логирование	config.enable_debug()
Всё перечисленное	Комбинация	См. ниже

​

Быстрый запуск

​

Включить полный режим отладки

from chdb import datastore as pd
from chdb.datastore.config import config

# Включить все отладочные функции
config.enable_debug()        # Подробное логирование
config.enable_profiling()    # Данные профилирования

ds = pd.read_csv("data.csv")
result = ds.filter(ds['age'] > 25).groupby('city').agg({'salary': 'mean'})

# Просмотр плана выполнения
result.explain()

# Получить отчёт профилировщика
from chdb.datastore.config import get_profiler
profiler = get_profiler()
profiler.report()

---

​

Метод explain()

Просмотрите план выполнения запроса перед его запуском.

Query

ds = pd.read_csv("data.csv")

query = (ds
    .filter(ds['amount'] > 1000)
    .groupby('region')
    .agg({'amount': ['sum', 'mean']})
)

# Просмотр плана
query.explain()

Response

Pipeline:
  Source: file('data.csv', 'CSVWithNames')
  Filter: amount > 1000
  GroupBy: region
  Aggregate: sum(amount), avg(amount)

Generated SQL:
SELECT region, SUM(amount) AS sum, AVG(amount) AS mean
FROM file('data.csv', 'CSVWithNames')
WHERE amount > 1000
GROUP BY region

Подробнее см. в документации по explain().

---

​

Данные профилирования

Измеряйте время выполнения каждой операции.

Query

from chdb.datastore.config import config, get_profiler

# Включить профилирование
config.enable_profiling()

# Выполнить операции
ds = pd.read_csv("large_data.csv")
result = (ds
    .filter(ds['amount'] > 100)
    .groupby('category')
    .agg({'amount': 'sum'})
    .sort('sum', ascending=False)
    .head(10)
    .to_df()
)

# Просмотреть отчёт
profiler = get_profiler()
profiler.report(min_duration_ms=0.1)

Response

Отчёт о производительности
==================
Шаг                           Duration    Вызовы
----                          --------    -----
read_csv                      1.234s      1
filter                        0.002s      1
groupby                       0.001s      1
agg                           0.089s      1
sort                          0.045s      1
head                          0.001s      1
to_df (SQL execution)         0.567s      1
----                          --------    -----
Итого                         1.939s      7

Подробности см. в Руководстве по профилированию.

---

​

Логирование

Просматривайте подробные журналы выполнения.

from chdb.datastore.config import config

# Включить отладочное логирование
config.enable_debug()

# Выполнить операции — в журнале будет показано:
# - сгенерированные SQL-запросы
# - используемый движок выполнения
# - попадания/промахи кэша
# - информация о времени выполнения

Пример вывода логов:

DEBUG - DataStore: Creating from file 'data.csv'
DEBUG - Query: SELECT region, SUM(amount) FROM ... WHERE amount > 1000 GROUP BY region
DEBUG - Engine: Using chdb for aggregation
DEBUG - Execution time: 0.089s
DEBUG - Cache: Storing result (key: abc123)

Подробности см. в разделе Конфигурация логирования.

---

​

Типичные сценарии отладки

​

1. Запрос не возвращает ожидаемых результатов

# Шаг 1: Просмотр плана выполнения
query = ds.filter(ds['age'] > 25).groupby('city').sum()
query.explain(verbose=True)

# Шаг 2: Включить логирование для просмотра SQL
config.enable_debug()

# Шаг 3: Выполнить запрос и проверить журнал
result = query.to_df()

​

2. Запрос выполняется медленно

# Шаг 1: Включить данные профилирования
config.enable_profiling()

# Шаг 2: Выполнить запрос
result = process_data()

# Шаг 3: Проверить отчёт профилировщика
profiler = get_profiler()
profiler.report()

# Шаг 4: Определить медленные операции и оптимизировать

​

3. Разбор выбора движка

# Включить подробное логирование
config.enable_debug()

# Выполнить операции
result = ds.filter(ds['x'] > 10).apply(custom_func)

# В журнале будет указано, какой движок использовался для каждой операции:
# DEBUG - filter: Using chdb engine
# DEBUG - apply: Using pandas engine (custom function)

​

4. Диагностика проблем с кэшем

# Включить отладку для просмотра операций кэширования
config.enable_debug()

# Первый запуск
result1 = ds.filter(ds['x'] > 10).to_df()
# LOG: Промах кэша, выполняется запрос

# Второй запуск (должен использовать кэш)
result2 = ds.filter(ds['x'] > 10).to_df()
# LOG: Попадание в кэш, возвращается кэшированный результат

# Если кэширование не работает, как ожидается, проверьте:
# - Идентичны ли операции?
# - Включено ли кэширование? config.cache_enabled

---

​

Рекомендации

​

1. Отлаживайте в среде Development, а не в продакшне

# Разработка
config.enable_debug()
config.enable_profiling()

# Продакшн
config.set_log_level(logging.WARNING)
config.set_profiling_enabled(False)

​

2. Используйте explain() перед запуском ресурсоёмких запросов

# Построить запрос
query = ds.filter(...).groupby(...).agg(...)

# Сначала проверить план
query.explain()

# Если план выглядит корректно, выполнить
result = query.to_df()

​

3. Соберите данные профилирования перед оптимизацией

# Не гадайте, что работает медленно — измерьте это
config.enable_profiling()
result = your_pipeline()
get_profiler().report()

​

4. Проверьте SQL-запрос, если результаты неверны

# Просмотр сгенерированного SQL
print(query.to_sql())

# Сравнить с ожидаемым SQL
# Выполнить SQL напрямую в ClickHouse для проверки

---

​

Сводка по инструментам отладки

Инструмент	Команда	Вывод
План выполнения	ds.explain()	Шаги выполнения + SQL
Подробный explain	ds.explain(verbose=True)	+ Метаданные
Показать SQL	ds.to_sql()	Строка SQL-запроса
Включить отладку	config.enable_debug()	Подробные журналы
Включить данные профилирования	config.enable_profiling()	Данные о времени выполнения
Отчёт профилировщика	get_profiler().report()	Сводка производительности
Очистить профилировщик	get_profiler().reset()	Сброс данных о времени выполнения

---

​

Следующие шаги

• Метод explain() - Подробная документация по плану выполнения
• Руководство по данным профилирования - Измерение производительности
• Конфигурация логирования - Настройка уровня логирования и формата