SQL Plan Manager

Эта тема вводит базовые понятия и сценарии использования функции SQL Plan Manager, а также показывает, как с её помощью фиксировать (регуляризовать) планы выполнения запросов.

Начиная с версии 3.5.0, StarRocks поддерживает SQL Plan Manager.

Обзор

SQL Plan Manager позволяет привязать план к конкретному запросу, предотвращая изменение плана из‑за изменения состояния системы (прежде всего обновлений данных и статистики), тем самым стабилизируя производительность.

Рабочий процесс

Необходимо заранее указать исходный SQL-запрос и закрепляемый план (Baseline), который должен применяться. «Запрос» — это фактически исполняемый пользователем SQL; «план» — это вручную оптимизированный SQL или SQL с добавленными подсказками (hints).

Процесс работы состоит из двух этапов:

  1. Создание Baseline: выполните CREATE BASELINE, чтобы привязать план к заданному запросу.

  2. Переписывание запроса: поступающие в StarRocks запросы сопоставляются с хранилищем Baseline. При успешном совпадении к запросу применяется план из Baseline.

Важные замечания при создании Baseline:

  • Необходимо обеспечить логическую согласованность между исходным SQL и SQL плана в Baseline. StarRocks выполняет базовые проверки (таблицы, параметры), но полную корректность должен гарантировать пользователь.

  • По умолчанию в Baseline сохраняется SQL‑отпечаток (fingerprint). Константы заменяются параметрами (например, t1.v1 > 1000 → t1.v1 > ?), что повышает вероятность совпадения.

  • План, привязываемый в Baseline, можно настраивать через изменение логики SQL или добавлением Hints (Join‑подсказки, SET_VAR).

  • Для сложных SQL автоматическое связывание может не выполниться. В этом случае используйте ручное связывание (см. раздел «Расширенное использование»).

Замечания по переписыванию запросов:

  • Сопоставление выполняется по SQL-отпечатку. Если найден соответствующий Baseline, параметры из запроса подставляются в план Baseline.

  • Если совпало несколько включённых (enable) Baseline, оптимизатор выбирает лучший.

  • SQL Plan Manager валидирует соответствие Baseline и запроса; при неудаче план Baseline не используется.

  • Для переписанных планов EXPLAIN содержит Using baseline plan[id].

Управление Baseline

Создать Baseline

Синтаксис:

CREATE [GLOBAL] BASELINE [ON <BindSQL>] USING <PlanSQL> 
[PROPERTIES ("key" = "value"[, ...])]

Параметры:

  • GLOBAL — (необязательно) создаёт глобальный Baseline.

  • BindSQL — (необязательно) конкретный запрос, к которому привязывается план. Если не указан, Baseline привязывается к самому себе и использует собственный план.

  • PlanSQL — запрос, по которому определяется план.

Примеры:

-- Сессионный BASELINE: план привязывается к самому себе
CREATE BASELINE
USING SELECT t1.v2, t2.v3 FROM t1 JOIN t2 ON t1.v2 = t2.v2 WHERE t1.v2 > 100;

-- Глобальный BASELINE с Join Hint
CREATE GLOBAL BASELINE
USING SELECT t1.v2, t2.v3 FROM t1 JOIN[BROADCAST] t2 ON t1.v2 = t2.v2 WHERE t1.v2 > 100;

-- Сессионный BASELINE: привязка отдельного BindSQL к PlanSQL с Join Hint
CREATE BASELINE ON SELECT t1.v2, t2.v3 FROM t1, t2 WHERE t1.v2 = t2.v2 AND t1.v2 > 100
USING SELECT t1.v2, t2.v3 FROM t1 JOIN[BROADCAST] t2 on t1.v2 = t2.v2 where t1.v2 > 100;

Просмотр Baseline

Синтаксис:

SHOW BASELINE [WHERE <condition>]

SHOW BASELINE [ON <query>]

Удаление/вкл‑выкл Baseline

DROP BASELINE <id>,<id>...
ENABLE BASELINE <id>,<id>...
DISABLE BASELINE <id>,<id>...

Переписывание запросов

Включите переписывание:

SET enable_spm_rewrite = true;

После привязки плана StarRocks автоматически применит план из Baseline. В EXPLAIN появится строка Using baseline plan[<id>].

Расширенное использование

Для гибкого управления параметрами используйте функции SQL Plan Manager:

  • _spm_const_var(placeholdID) — одиночная константа.

  • _spm_const_list(placeholdID) — список констант (для IN).

  • _spm_const_range(placeholdID, min, max) — константа внутри интервала [min, max].

  • _spm_const_num(placeholdID, value...) — константа из перечисления.

Кратко о процессах создания Baseline и переписывания: параметризация BindSQL → привязка плейсхолдеров в PlanSQL → оптимизация → сериализация плана в SQL с hints → сохранение Baseline; нормализация запроса → поиск Baseline → извлечение и подстановка параметров → возврат PlanSQL.

Автоматический захват (Auto‑Capture)

Auto‑Capture периодически просматривает историю запросов (по умолчанию 3 часа), генерирует Baselines в состоянии disable, что упрощает откат плана после апгрейда/изменения статистик.

Включение:

set global enable_query_history=true;
set global enable_plan_capture=true;

Полезные параметры: query_history_keep_seconds, plan_capture_interval, plan_capture_include_pattern.

Рекомендация: включите за 1–2 дня до апгрейда, после обновления сравните производительность и при необходимости включите подходящий Baseline (enable baseline <id>), затем set enable_spm_rewrite = true.

Планы на будущее

  • Расширенные проверки стабильности планов;

  • Автоматическая оптимизация фиксированных планов;

  • Больше способов условной параметрической привязки.