SQL-ячейки
Новая SQL-ячейка содержит поле редактирования SQL-запроса и панель управления. После выполнения запроса в ячейку добавляется статистика выполнения запроса QUERY STATS и панель результатов запроса (или панель Error, если при выполнении запроса возникла ошибка).
При создании ноутбук содержит одну SQL-ячейку.
Текст запроса
В поле редактирования SQL-запроса поддерживается следующая функциональность:
-
Подсветка синтаксиса SQL.
-
Нумерация строк (включается/отключается в настройках, см. ниже). Клик по номеру строки выделяет всю строку целиком.
-
Автодополнение — при наборе текста SQL-запроса на основе уже введенных символов показывается список возможных ключевых слов, выражений, функций, имен баз данных/таблиц/столбцов. Данная функция включается/отключается соответствующей настройкой; при этом даже если она выключена, можно посмотреть список вариантов автодополнения, нажав
Ctrl+Space. -
Автоматическое закрытие скобок и кавычек при вводе (включается/отключается соответствующей настройкой).
-
Автоматическое увеличение/уменьшение поля редактирования в зависимости от размера SQL-кода. Размер поля также можно изменять вручную, двигая мышью его нижнюю границу. Двойной клик по маркеру изменения размера на нижней границе поля возвращает его к размеру, определяемому автоматически в зависимости от размера текста запроса.
Автоматическое форматирование кода SQL (Beautify SQL)
Используйте иконку 
Beautify SQL, чтобы автоматически привести код запроса к более читаемому виду следующим образом:
-
применить единообразные отступы и пробелы для логического структурирования кода;
-
разместить основные выражения (
SELECT,FROM,WHERE,JOINи др.) на отдельных строках; -
использовать заглавные буквы для ключевых слов SQL (например,
SELECT,AS,FROM,GROUP BY,ORDER BY); -
разбить длинные списки считываемых столбцов на строки — по одному столбцу в каждой строке.
|
ПРИМЕЧАНИЕ
Beautify SQL применяет форматирование к тексту запроса на основе результатов EXPLAIN SYNTAX, поэтому для работы этой функциональности необходимо, чтобы сервер ClickHouse был доступен. |
Код запроса, приведенного на рисунке выше, после применения функции Beautify SQL будет выглядеть следующим образом.
Настройки поля редактирования запроса
Для поля редактирования текста запроса в SQL-ячейке можно настроить следующие параметры (окно с настройками открывается кликом по иконке 
Settings в правом верхнем углу интерфейса):
-
Font Size — размер шрифта (настройка не влияет на текстовые ячейки);
-
Word Wrap — включает/отключает перенос строк (в текстовых ячейках перенос строк всегда включен, независимо от этого параметра);
-
Line Numbers — включает/отключает нумерацию строк (в текстовых ячейках нумерация строк может быть включена только для режима редактирования);
-
Auto-Close Brackets & Quotes — включает/отключает автоматическое закрытие скобок и кавычек при вводе;
-
SQL Autocomplete — включает/отключает автоматическое отображение вариантов дополнения ключевых слов, функций, имен баз данных/таблиц/столбцов при наборе SQL-кода.
Переменные в запросах
На панели VARIABLES можно определять переменные в виде пар ключ/значение. На переменную можно ссылаться в запросе по ключу, используя формат {{variable_name}} — перед отправкой запроса на выполнение эта запись будет автоматически заменяться значением переменной. Ключи переменных сопоставляются без учета регистра (например, записи {{MyVar}}, {{myvar}}, {{MYVAR}} соответствуют одной и той же переменной).
В заголовке панели VARIABLES справа показывается счетчик добавленных переменных. При добавлении переменной с повторяющимся именем соответствующие поля подсвечиваются красным, счетчик переменных не увеличивается, а значение дублирующейся переменной будет игнорироваться.
Панель управления
Панель управления SQL-ячейки, расположенная выше поля редактирования текста запроса, содержит следующие элементы:
-
Drag to reorder — при нажатии и удержании иконки можно перемещать ячейку относительно других ячеек в рамках ноутбука с помощью механизма drag-and-drop. -
[n] — монотонно растущий идентификатор создания ячейки, который не меняется при ее перемещении или удалении.
-
Query settings — открыть настройки, с помощью которых можно установить ограничения, позволяющие предотвратить выполнение потенциально ресурсозатратного запроса. Доступные настройки:
-
max_memory_usage — максимальный объем оперативной памяти для выполнения запроса на сервере;
-
max_execution_time — максимальное время выполнения запроса;
-
max_threads — максимальное количество потоков, которые могут быть использованы одновременно во время выполнения запроса;
-
join_algorithm — алгоритм выполнения операции JOIN.
Эти настройки (кроме алгоритма выполнения соединений) также можно установить для всех запросов на уровне ноутбука. При этом ограничения, установленные в рамках SQL-ячейки, имеют более высокий приоритет.
-
-
Beautify SQL — выполнить автоматическое форматирование текста запроса.
-
AI — преобразовать текстовый вопрос в SQL-запрос SELECT(доступно, если в кластере ADQM установлен сервис Text-to-SQL). -
Статус выполнения запроса:
— запрос не выполнялся;
— запрос выполняется в данный момент;
— запрос выполнен успешно;
— ошибка выполнения запроса.Для запроса, выполнение которого завершилось (успешно или неуспешно), рядом с индикатором статуса также показывается время последнего запуска запроса.
-
n statements — количество запросов в ячейке (показывается, если в ячейке указано более одного запроса через точку с запятой).
-
n — история выполнения запросов в ячейке (показывается, если было выполнено более одного запуска; n — количество запусков в истории). -
Run — запустить выполнение запроса. -
Toggle query — свернуть/развернуть поле с кодом запроса (если это поле свернуто, начало текста запроса отображается на панели управления). -
Copy cell as image — скопировать ячейку как изображение. -
Fullscreen — развернуть (или свернуть) SQL-ячейку на полный экран. -
Duplicate cell — скопировать ячейку. -
Move up — переместить ячейку на одну позицию выше предыдущей ячейки. -
Move down — переместить ячейку на одну позицию ниже следующей ячейки. -
Add cell below — создать новую ячейку того же типа ниже. -
Delete cell — удалить ячейку.
Выполнение запроса
Чтобы запустить запрос, выполните одно из действий:
-
Кликните
Run на панели управления соответствующей SQL-ячейки. Во время выполнения запроса кнопка Run визуально меняется на Stop — клик по ней отменяет выполнение запроса (отправляется KILL QUERY). -
Кликните по SQL-ячейке, чтобы ее выбрать (выбранная ячейка подсвечивается зеленым цветом), и нажмите
Ctrl+Enter(илиCmd+Enter).
В интерфейсе ADQM Notebook, несколько SQL-ячеек, запущенных по отдельности, могут выполнять свои запросы одновременно. Команда 
запускает запросы в ячейках последовательно сверху вниз, ожидая завершения каждого запроса, прежде чем запускать следующий.
В настройках ADQM Notebook с помощью параметра Max Rows per Query можно установить максимальное количество строк в результатах запроса ячейки. При достижении лимита выполнение запроса прерывается (отправляется KILL QUERY), результаты помечаются как truncated.
Выполнение запроса также прерывает переключение ноутбука или Clear Results.
Панель результатов запроса
После выполнения запроса результаты выводятся на панели результатов, которая содержит вкладки Table и Chart, где полученные данные можно посмотреть в виде таблицы или графика соответственно. На панели результатов также располагается:
-
общая информация по результатам выполнения запроса (количество полученных строк данных и время выполнения);
-
поле Search results…, с помощью которого можно фильтровать данные в результирующем наборе в режиме реального времени по любому столбцу — на панели будут показаны только значения, соответствующие указанному фильтру;
-
иконка
Download, с помощью которой можно сохранить результаты запроса в одном из поддерживаемых форматах (CSV, TSV, JSON, JSONLines, Parquet).Данные в форматах CSV, TSV, JSON и JSONLines генерируются на стороне клиента из кешированных результатов. Для Parquet повторно выполняется весь запрос на сервере ADQMDB, поскольку формат требует генерации на стороне сервера. Это значит:
-
Запрос может вернуть другие результаты, если данные изменились.
-
Возможна дополнительная нагрузка на сервер.
-
Панель результатов можно сворачивать/разворачивать с помощью иконки в левом верхнем углу.
Чтобы удалить результаты выполнения запросов всех SQL-ячеек в ноутбуке, откройте контекстное меню Clear на панели управления ноутбука и выберите Clear Results.
Панель ошибки выполнения запроса
В случае возникновения ошибки при выполнении запроса соответствующее сообщение выводится на панели Error (вместо панели результатов).
История выполнения запросов
Если в ячейке запрос (или нескольких запросов) выполнялся более одного раза, с помощью опции Run history можно сравнивать запуски или переключаться на предыдущие.
Во всплывающем окне RUN HISTORY показывается пять последних запусков запросов в ячейке; внизу — сравнение текущего запуска с выбранным в истории. Чтобы переключиться на один из прошлых запусков, кликните restore в соответствующей строке истории — в ячейку загрузится текст запроса, результаты и план его выполнения, полученные при прошлом запуске (без повторного выполнения этого запроса).
Таблица результатов
После выполнения запроса в SQL-ячейке результирующий набор данных показывается на вкладке Table в виде интерактивной таблицы, в которой поддерживается следующая функциональность для удобного просмотра полученных данных:
-
Отображение имен столбцов и типов данных в заголовках.
-
Сортировка данных — клик по заголовку столбца.
-
Поиск данных — фильтрация значений в результирующем наборе по любому столбцу в режиме реального времени с помощью поля Search results….
-
Smart-форматирование:
-
числовые столбцы выравниваются по правому краю, текстовые — по левому краю;
-
URL-адреса автоматически определяются и преобразуются в ссылки, по которым можно перейти;
-
значения NULL визуально отличаются от других;
-
данные JSON выводятся в отформатированном виде;
-
массивы и объекты JSON можно сворачивать/разворачивать (поведение по умолчанию регулируется опцией Expand JSON/Arrays by default в настройках интерфейса — настройка влияет на отображение результатов только что выполненного запроса, уже отображаемые результаты не будут сворачиваться/разворачиваться при переключении опции);
-
обобщающая информация по столбцам в виде меток в заголовках: доля значений NULL в столбце (если
0%— зеленая метка, если больше0%— красная), количество уникальных значений в столбце, диапазон значений в числовых столбцах и столбцах типа DateTime.
-
|
ПРИМЕЧАНИЕ
Максимальное количество ячеек ( |
Результаты запроса в виде графика
Числовые результаты запроса можно просматривать в виде графиков. Для этого на панели результатов откройте вкладку Chart и настройте следующие параметры для построения графика:
-
TYPE — тип графика
Line, 
Area или 
Bar; -
X-AXIS — один столбец, значения которого будут строиться по оси X;
-
Y-AXIS — один или несколько столбцов, значения которых будут строиться по оси Y.
График строится по обеим осям между минимальными и максимальными значениями из результатов запроса.
На графике отображается максимум 2000 точек за счет прореживания. Если оно применяется, показывается примечание downsampled to N of M points, таблица результатов при этом по-прежнему содержит все строки.
План выполнения запроса
На панели результатов запроса SELECT (в том числе с использованием CTE) доступна вкладка Plan с планом выполнения запроса. Для просмотра плана можно выбрать одну из опций (соответствующие переключатели расположены справа):
-
Estimated — прогнозируемый план выполнения запроса (аналогичный тому, что предоставляет EXPLAIN без реального запуска запроса).
-
Actual — план фактического выполнения запроса (требуется подключение таблицы
system.processors_profile_log). При выборе этой опции в верхней части панели выводится общая информация о выполнении запроса на чтение данных из таблицы:-
wall — сколько времени потрачено;
-
cpu — работа процессора, параллельность выполнения запроса;
-
mem — количество используемой памяти;
-
outside plan steps — процент времени, потраченного на выполнение внутренних процессов ClickHouse для обработки запроса, не относящихся непосредственно к чтению данных.
Кроме того, время выполнения и количество обработанных строк выводятся для каждого этапа плана запроса.
-
ADQM Notebook также поддерживает следующие два представления плана выполнения запроса:
-
Pipe — конвейер выполнения запроса, аналогичный тому, что выводит EXPLAIN PIPELINE.
-
Logical — логический план выполнения запроса в виде схемы, включающей только этапы, которые относятся к получению запрашиваемых данных (чтение/фильтрация/агрегирование/сортировка данных). Неинформативные блоки (для внутренних процессов, которые выполняются "под капотом" ClickHouse при обработке запроса) здесь не показываются. Читать план запроса нужно снизу вверх.
Если выбраны опции Actual и Logical, информация о каждом шаге выполнения запроса обозначается в плане следующим образом:
-
Толщина стрелок между блоками соответствует количеству строк данных, полученных в результате выполнения предыдущего шага и поступивших на вход следующего шага.
-
Блок, соответствующий самому долгому этапу выполнения запроса, подсвечивается цветом.
-
Внутри блока плана запроса или во всплывающей подсказке (показывается при наведении курсора мыши на блок) можно посмотреть информацию о количестве обработанных на этом этапе строк данных, время выполнения этапа, а также какую долю составляет это время относительно общего времени выполнения запроса. Для блока Read указывается число кусков данных (data parts) и гранул, считанных из таблицы.
-
Линия внутри блока показывает, на что тратилось время на данном этапе плана — во всплывающей подсказке можно посмотреть, какие процессы соответствуют разным цветам линии и сколько времени выполнялся каждый процесс.
Если в запросе используется неэффективный фильтр или для таблицы не определен ключ сортировки, что может существенно снизить скорость выполнения запроса, внизу показывается панель FINDINGS, где выводится:
-
описание возможной проблемы (кликните Show step, чтобы подсветить шаг плана, на который она влияет);
-
рекомендация, как можно обойти проблему и повысить производительность запроса (кликните How to fix, чтобы посмотреть рекомендацию).
Например, на рисунке выше, в панели FINDINGS указано, что запрос фильтрует данные по столбцу b, а не по столбцу a, который указан первым в ключе сортировки таблицы (a, b) — поэтому при чтении из таблицы обрабатываются все 92 гранулы (лишние данные не пропускаются), что отрицательно сказывается на производительности запроса. Чтобы ускорить запрос, рекомендуется либо добавить в запрос фильтрацию по первому ключевому столбцу a, либо (для запросов с фильтрацией только по столбцу b) создать проекцию таблицы с ключом сортировки b или (b, a). Подробная информация с рекомендациями о назначении и использовании ключевых столбцов таблиц ADQM приведена в разделе Разреженный первичный индекс.
Потенциальные проблемы, которые могут быть обнаружены и выведены на панели FINDINGS:
-
Table has no sorting key -
Filter can’t use the sorting key -
Filter skips the leading key column -
Aggregation/Sort spilled to disk
Статистика выполнения запроса
Если в ADQM включено логирование запросов (активирован параметр query_log), в SQL-ячейке показывается панель QUERY STATS со следующей информацией о выполнении запроса:
-
Duration — время выполнения запроса;
-
Read — общее количество строк, считанных из всех таблиц и табличных функций, участвующих в запросе;
-
Scanned — общее количество байт, считанных из всех таблиц и табличных функций, участвующих в запросе;
-
Memory — использованная запросом память;
-
Threads — максимальное количество потоков, используемых одновременно во время выполнения запроса;
-
Node Breakdown — информация о выполнении запроса на каждом хосте (при выполнении запроса в кластере ADQM);
-
Details — детальная информация, включающая: тип запроса (
SELECT,INSERTи т.д.), количество записанных строк (для запросов на запись), количество записанных байтов, количество строк в результате запроса, размер результата запроса в байтах, а также имена баз данных/таблиц/столбцов, к которым обращался запрос.
Статистика показывается автоматически после выполнения запроса, если опция Show Query Statistics включена в настройках интерфейса ADQM Notebook. Если эта опция выключена (по умолчанию), для просмотра статистики нужно кликнуть Show Query Stats на панели.
Кластер для получения статистики по запросам устанавливается с помощью настройки Cluster for Statistics. Если в конфигурации ADQM не определено ни одного кластера, эта настройка имеет фиксированное значение Single node.
Несколько запросов в ячейке
В одну SQL-ячейку можно ввести несколько (не более восьми) запросов, разделяя их точкой с запятой. Количество запросов в ячейке показывается на панели управления как n statements.
Если в SQL-ячейку введено несколько запросов, после их выполнения (запускаются кнопкой Run как и в случае одного запроса в ячейке) панель результатов будет содержать соответствующее количество вкладок — отдельная вкладка для каждого запроса с его результатами (на вкладках Table, Chart, Plan) и статистикой выполнения QUERY STATS. Справа на панели результатов показывается количество выполненных запросов, общее количество прочитанных строк данных и общее время выполнения.
Запросы выполняются последовательно друг за другом в указанном порядке (Stop прерывает текущий запрос). Если необходимо изменить текущую базу данных или установить значения параметров, чтобы они применялись ко всем запросам в ячейке, запросы USE и SET должны находиться перед остальными запросами в списке.