SQL-ячейки

Новая SQL-ячейка содержит поле редактирования SQL-запроса и панель управления. После выполнения запроса в ячейку добавляется статистика выполнения запроса QUERY STATS и панель результатов запроса (или панель Error, если при выполнении запроса возникла ошибка).

SQL-ячейка
SQL-ячейка
SQL-ячейка
SQL-ячейка

При создании ноутбук содержит одну SQL-ячейку.

Текст запроса

В поле редактирования SQL-запроса поддерживается следующая функциональность:

  • Подсветка синтаксиса SQL.

  • Нумерация строк (включается/отключается в настройках, см. ниже). Клик по номеру строки выделяет всю строку целиком.

  • Автоматическое закрытие скобок и кавычек при вводе (включается/отключается соответствующей настройкой).

  • Автоматическое увеличение/уменьшение поля редактирования в зависимости от размера SQL-кода. Размер поля также можно изменять вручную, двигая мышью его нижнюю границу. Двойной клик по маркеру изменения размера на нижней границе поля возвращает его к размеру, определяемому автоматически в зависимости от размера текста запроса.

Поле редактирования SQL-запроса
Поле редактирования SQL-запроса
Поле редактирования SQL-запроса
Поле редактирования SQL-запроса

Автоматическое форматирование кода SQL (Beautify SQL)

Используйте иконку beautify sql icon dark beautify sql icon light Beautify SQL, чтобы автоматически привести код запроса к более читаемому виду следующим образом:

  • применить единообразные отступы и пробелы для логического структурирования кода;

  • разместить основные выражения (SELECT, FROM, WHERE, JOIN и др.) на отдельных строках;

  • использовать заглавные буквы для ключевых слов SQL (например, SELECT, AS, FROM, GROUP BY, ORDER BY);

  • разбить длинные списки считываемых столбцов на строки — по одному столбцу в каждой строке.

ПРИМЕЧАНИЕ

Beautify SQL применяет форматирование к тексту запроса на основе результатов EXPLAIN SYNTAX, поэтому для работы этой функциональности необходимо, чтобы сервер ClickHouse был доступен.

Использование опции Beautify SQL
Использование опции Beautify SQL
Использование опции Beautify SQL
Использование опции Beautify SQL
Пример применения Beautify SQL

 

Код запроса, приведенного на рисунке выше, после применения функции Beautify SQL будет выглядеть следующим образом.

Отформатированный текст запроса
Отформатированный текст запроса
Отформатированный текст запроса
Отформатированный текст запроса

Настройки поля редактирования запроса

Для поля редактирования текста запроса в SQL-ячейке можно настроить следующие параметры (окно с настройками открывается кликом по иконке settings icon dark settings icon light Settings в правом верхнем углу интерфейса):

  • Font Size — размер шрифта (настройка не влияет на текстовые ячейки);

  • Word Wrap — включает/отключает перенос строк (в текстовых ячейках перенос строк всегда включен, независимо от этого параметра);

  • Line Numbers — включает/отключает нумерацию строк (в текстовых ячейках нумерация строк может быть включена только для режима редактирования);

  • Auto-Close Brackets & Quotes — включает/отключает автоматическое закрытие скобок и кавычек при вводе.

Настройки
Настройки
Настройки
Настройки

Переменные в запросах

На панели VARIABLES можно определять переменные в виде пар ключ/значение. На переменную можно ссылаться в запросе по ключу, используя формат {{variable_name}} — перед отправкой запроса на выполнение эта запись будет автоматически заменяться значением переменной. Ключи переменных сопоставляются без учета регистра (например, записи {{MyVar}}, {{myvar}}, {{MYVAR}} соответствуют одной и той же переменной).

Использование переменной в запросе
Использование переменной в запросе
Использование переменной в запросе
Использование переменной в запросе

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

Панель управления

Панель управления SQL-ячейки, расположенная выше поля редактирования текста запроса, содержит следующие элементы:

  • drag to order icon dark drag to order icon light Drag to reorder — при нажатии и удержании иконки можно перемещать ячейку относительно других ячеек в рамках ноутбука с помощью механизма drag-and-drop.

  • [n] — монотонно растущий идентификатор создания ячейки, который не меняется при ее перемещении или удалении.

  • settings icon dark settings icon light Query settings — открыть настройки, с помощью которых можно установить ограничения, позволяющие предотвратить выполнение потенциально ресурсозатратного запроса. Доступные настройки:

    • max_memory_usage — максимальный объем оперативной памяти для выполнения запроса на сервере;

    • max_execution_time — максимальное время выполнения запроса;

    • max_threads — максимальное количество потоков, которые могут быть использованы одновременно во время выполнения запроса;

    • join_algorithm — алгоритм выполнения операции JOIN.

    Эти настройки (кроме алгоритма выполнения соединений) также можно установить для всех запросов на уровне ноутбука. При этом ограничения, установленные в рамках SQL-ячейки, имеют более высокий приоритет.

  • beautify sql icon dark beautify sql icon light Beautify SQL — выполнить автоматическое форматирование текста запроса.

  • Статус выполнения запроса:

    query status grey icon dark query status grey icon light — запрос не выполнялся;

    query status yellow icon dark query status yellow icon light — запрос выполняется в данный момент;

    query status green icon dark query status green icon light — запрос выполнен успешно;

    query status red icon dark query status red icon light — ошибка выполнения запроса.

    Для запроса, выполнение которого завершилось (успешно или неуспешно), рядом с индикатором статуса также показывается время последнего запуска запроса.

  • run icon Run — запустить выполнение запроса.

  • toggle query icon dark toggle query icon light Toggle query — свернуть/развернуть поле с кодом запроса (если это поле свернуто, начало текста запроса отображается на панели управления).

  • expand all queries icon dark expand all queries icon light Fullscreen — развернуть (или свернуть) SQL-ячейку на полный экран.

  • copy query icon dark copy query icon light Duplicate cell — скопировать ячейку.

  • move up icon dark move up icon light Move up — переместить ячейку на одну позицию выше предыдущей ячейки.

  • move down icon dark move down icon light Move down — переместить ячейку на одну позицию ниже следующей ячейки.

  • add cell below icon dark add cell below icon light Add cell below — создать новую ячейку того же типа ниже.

  • delete cell icon dark delete cell icon light Delete cell — удалить ячейку.

Панель управления SQL-ячейки
Панель управления SQL-ячейки
Панель управления SQL-ячейки
Панель управления SQL-ячейки

Выполнение запроса

Чтобы запустить запрос, выполните одно из действий:

  • Кликните run icon Run на панели управления соответствующей SQL-ячейки. Во время выполнения запроса кнопка Run визуально меняется на Stop — клик по ней отменяет выполнение запроса (отправляется KILL QUERY).

  • Кликните по SQL-ячейке, чтобы ее выбрать (выбранная ячейка подсвечивается зеленым цветом), и нажмите CTRL+ENTER (или CMD+ENTER).

Выполнение запроса
Выполнение запроса
Выполнение запроса
Выполнение запроса

В интерфейсе ADQM Notebook, несколько SQL-ячеек, запущенных по отдельности, могут выполнять свои запросы одновременно. Команда run all icon запускает запросы в ячейках последовательно сверху вниз, ожидая завершения каждого запроса, прежде чем запускать следующий.

Запуск выполнения всех запросов в ноутбуке
Запуск выполнения всех запросов в ноутбуке
Запуск выполнения всех запросов в ноутбуке
Запуск выполнения всех запросов в ноутбуке

В настройках ADQM Notebook с помощью параметра Max Rows per Query можно установить максимальное количество строк в результатах запроса ячейки. При достижении лимита выполнение запроса прерывается (отправляется KILL QUERY), результаты помечаются как truncated.

Панель результатов запроса

После выполнения запроса результаты выводятся на панели результатов, которая содержит вкладки Table и Chart, где полученные данные можно посмотреть в виде таблицы или графика соответственно. На панели результатов также располагается:

  • общая информация по результатам выполнения запроса (количество полученных строк данных и время выполнения);

  • поле Search results…​, с помощью которого можно фильтровать данные в результирующем наборе в режиме реального времени по любому столбцу — на панели будут показаны только значения, соответствующие указанному фильтру;

  • иконка download icon dark download icon light Download, с помощью которой можно сохранить результаты запроса в одном из поддерживаемых форматах (CSV, TSV, JSON, JSONLines, Parquet).

    Данные в форматах CSV, TSV, JSON и JSONLines генерируются на стороне клиента из кешированных результатов. Для Parquet повторно выполняется весь запрос на сервере ADQMDB, поскольку формат требует генерации на стороне сервера. Это значит:

    • Запрос может вернуть другие результаты, если данные изменились.

    • Возможна дополнительная нагрузка на сервер.

Панель результатов можно сворачивать/разворачивать с помощью иконки toggle query icon dark toggle query icon light в левом верхнем углу.

Панель результатов запроса
Панель результатов запроса
Панель результатов запроса
Панель результатов запроса

Чтобы удалить результаты выполнения запросов всех SQL-ячеек в ноутбуке, откройте контекстное меню Clear на панели управления ноутбука и выберите Clear Results.

Удаление результатов запросов
Удаление результатов запросов
Удаление результатов запросов
Удаление результатов запросов

Панель ошибки выполнения запроса

В случае возникновения ошибки при выполнении запроса соответствующее сообщение выводится на панели Error (вместо панели результатов).

Ошибка выполнения запроса
Ошибка выполнения запроса
Ошибка выполнения запроса
Ошибка выполнения запроса

Таблица результатов

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

  • Отображение имен столбцов и типов данных в заголовках.

  • Сортировка данных — клик по заголовку столбца.

  • Поиск данных — фильтрация значений в результирующем наборе по любому столбцу в режиме реального времени с помощью поля Search results…​.

  • Smart-форматирование:

    • числовые столбцы выравниваются по правому краю, текстовые — по левому краю;

    • URL-адреса автоматически определяются и преобразуются в ссылки, по которым можно перейти;

    • значения NULL визуально отличаются от других;

    • данные JSON выводятся в отформатированном виде;

    • массивы и объекты JSON можно сворачивать/разворачивать (поведение по умолчанию регулируется опцией Expand JSON/Arrays by default в настройках интерфейса — настройка влияет на отображение результатов только что выполненного запроса, уже отображаемые результаты не будут сворачиваться/разворачиваться при переключении опции);

    • обобщающая информация по столбцам в виде меток в заголовках: доля значений NULL в столбце (если 0% — зеленая метка, если больше 0% — красная), количество уникальных значений в столбце, диапазон значений в числовых столбцах и столбцах типа DateTime.

Таблица результатов запроса
Таблица результатов запроса
Таблица результатов запроса
Таблица результатов запроса
ПРИМЕЧАНИЕ

Максимальное количество ячеек (rows * columns) в одном наборе результатов, чтобы предотвратить сбои в работе браузера — 100000.

Результаты запроса в виде графика

Числовые результаты запроса можно просматривать в виде графиков. Для этого на панели результатов откройте вкладку Chart и настройте следующие параметры для построения графика:

  • TYPE — тип графика line icon dark line icon light Line, area icon dark area icon light Area или bar icon dark bar icon light Bar;

  • X-AXIS — один столбец, значения которого будут строиться по оси X;

  • Y-AXIS — один или несколько столбцов, значения которых будут строиться по оси Y.

График строится по обеим осям между минимальными и максимальными значениями из результатов запроса.

Результаты запросов в виде графиков
Результаты запросов в виде графиков
Результаты запросов в виде графиков
Результаты запросов в виде графиков

На графике отображается максимум 2000 точек за счет прореживания. Если оно применяется, показывается примечание downsampled to N of M points, таблица результатов при этом по-прежнему содержит все строки.

Статистика выполнения запроса

Если в ADQM включено логирование запросов (активирован параметр query_log), в SQL-ячейке показывается панель QUERY STATS со следующей информацией о выполнении запроса:

  • Duration — время выполнения запроса;

  • Read — общее количество строк, считанных из всех таблиц и табличных функций, участвующих в запросе;

  • Scanned — общее количество байт, считанных из всех таблиц и табличных функций, участвующих в запросе;

  • Memory — использованная запросом память;

  • Threads — максимальное количество потоков, используемых одновременно во время выполнения запроса;

  • Node Breakdown — информация о выполнении запроса на каждом хосте (при выполнении запроса в кластере ADQM);

  • Details — детальная информация, включающая: тип запроса (SELECT, INSERT и т.д.), количество записанных строк (для запросов на запись), количество записанных байтов, количество строк в результате запроса, размер результата запроса в байтах, а также имена баз данных/таблиц/столбцов, к которым обращался запрос.

Панель QUERY STATS
Панель QUERY STATS
Панель QUERY STATS
Панель QUERY STATS

Статистика показывается автоматически после выполнения запроса, если опция Show Query Statistics включена в настройках интерфейса ADQM Notebook. Если эта опция выключена (по умолчанию), для просмотра статистики нужно кликнуть Show Query Stats на панели.

Получение статистики выполнения запроса
Получение статистики выполнения запроса
Получение статистики выполнения запроса
Получение статистики выполнения запроса

Кластер для получения статистики по запросам устанавливается с помощью настройки Cluster for Statistics. Если в конфигурации ADQM не определено ни одного кластера, эта настройка имеет фиксированное значение Single node.

Настройки для получения статистики по запросам
Настройки для получения статистики по запросам
Настройки для получения статистики по запросам
Настройки для получения статистики по запросам
Нашли ошибку? Выделите текст и нажмите Ctrl+Enter чтобы сообщить о ней