ADQM Notebook
ADQM Notebook — инструмент для работы с базами данных ADQM, расширяющий возможности встроенного веб-интерфейса ClickHouse.
Чтобы открыть интерфейс ADQM Notebook, введите в браузере адрес http://<adqm_host_IP>:8123/notebook, где <adqm_host_IP> — IP-адрес хоста ADQM. В полях ввода user и password, расположенных справа в верхней части интерфейса, укажите имя пользователя и пароль для подключения к серверу ClickHouse (пользователь должен быть определен в секции users конфигурационного файла сервера users.xml). По умолчанию используется имя пользователя default без пароля.
|
ПРИМЕЧАНИЕ
Интерфейс ADQM Notebook доступен только в Enterprise-версии ADQM (начиная с 25.8.16.34.1.b1). |
Обзор интерфейса
Основные объекты, которыми можно оперировать в интерфейсе ADQM Notebook: ноутбуки (notebook) и ячейки (cell).
Ноутбук — набор ячеек, которые могут быть двух типов:
-
SQL-ячейки (SQL cell) — для выполнения SQL-запросов с большим набором функциональных возможностей, включающих редактирование кода запросов, просмотр результатов выполнения запросов в виде интерактивных таблиц или графиков, а также сохранение результатов в различных форматах.
-
Текстовые ячейки (Text cell) — для заметок и комментариев с поддержкой разметки markdown для форматирования текста.
Интерфейс ADQM Notebook предоставляет возможность создания нескольких ноутбуков и опцию для их автоматического сохранения. Снепшоты ноутбуков (notebook snapshot) можно сохранять в JSON-файлы или в отдельной базе данных на сервере ClickHouse и затем импортировать их для использования другими пользователями (sharing) или резервного копирования (backup).
В левой части интерфейса расположены панели:
В правом верхнем углу интерфейса расположены иконки для доступа к следующей функциональности:
-
Keyboard shortcuts — просмотр комбинаций клавиш для выполнения различных команд по управлению ячейками в интерфейсе; -
Share notebook — получение ссылки на ноутбук, которой можно поделиться с другими пользователями; -
Settings — доступ к настройкам интерфейса; -
/ 
Toggle theme — переключение между темной и светлой темой интерфейса.
Ноутбуки
Панель Notebooks
Панель NOTEBOOKS предназначена для управления ноутбуками в интерфейсе ADQM Notebook.
Чтобы создать новый ноутбук, кликните по иконке 
New Notebook в заголовке панели NOTEBOOKS — будет создан ноутбук с одной SQL-ячейкой.
Чтобы изменить имя ноутбука, наведите курсор мыши на строку ноутбука, кликните по иконке 
Rename и введите новое имя в поле редактирования.
Ноутбуки можно перемещать в списке, используя механизм drag-and-drop.
Чтобы удалить ноутбук, наведите курсор мыши на строку ноутбука в панели NOTEBOOKS и кликните по иконке 
Delete.
Рабочее пространство ноутбука
Основное рабочее пространство ноутбука (notebook workspace) включает:
-
Область для работы с ячейками, где можно создавать/редактировать/удалять ячейки типа SQL и Text.
-
Панель управления, которая содержит следующие элементы:
-
— запустить выполнение запросов во всех SQL-ячейках ноутбука. -
Clear
— развернуть список команд для очистки ячеек (Clear Results — удалить результаты запросов всех SQL-ячеек; Clear All Cells — удалить все ячейки из ноутбука, оставив одну пустую SQL-ячейку). -
Collapse all queries — свернуть все запросы в ноутбуке. -
Expand all queries — развернуть все запросы в ноутбуке. -
Export — экспортировать ноутбук в JSON-файл. -
Import — импортировать ноутбук из JSON-файла. -
Server — развернуть список команд для хранения ноутбуков на сервере ClickHouse.
-
Экспорт/импорт ноутбуков в формате JSON
Чтобы экспортировать текущий ноутбук в JSON-файл, кликните Export в панели управления ноутбука.
В каталоге Downloads будет создан JSON-файл с тем же именем, что и ноутбук. В этом файле будет содержаться полная информация о состоянии ноутбука:
-
ячейки, в том числе запросы со статусами их выполнения, результатами и статистикой (если данные были получены на момент экспорта);
-
переменные;
-
настройки, включая состояние сортировки (столбец, направление), параметры графиков (тип, оси);
-
адрес подключения (но он не будет применяться при импорте для удобства передачи на другой хост).
Пароль не сохраняется.
Чтобы импортировать ранее экспортированный ноутбук, кликните Import в панели управления ноутбука и выберите JSON-файл.
Импортированный ноутбук будет добавлен в список на панели NOTEBOOKS c именем в формате <notebook_name> (dd-mm-yyyy hh:mm:ss), где <notebook_name> — имя JSON-файла, соответствующее имени ноутбука, dd-mm-yyyy hh:mm:ss — дата и время импорта.
Хранение ноутбуков на сервере ClickHouse
Ноутбуки, созданные в интерфейсе ADQM Notebook, можно сохранять в отдельную базу данных сервера ClickHouse и позже загружать их оттуда. Кроме того, при подключении будет выполняться автоматическая синхронизация с сервером — при успешном подключении ноутбуки автоматически будут загружаться из серверного хранилища, если оно доступно. При подключении от имени другого пользователя все локальные ноутбуки (не сохраненные на сервере) очищаются.
Сохранение ноутбука на сервер
Чтобы загрузить ноутбук на сервер, на панели управления ноутбука откройте список Server и выберите команду Save to Server.
Если хранилище для ноутбуков не было ранее подготовлено, при первой попытке сохранить ноутбук на сервер будет показано окно, где нужно подтвердить создание таблицы notebooks в базе данных adqm_notebooks на текущем хосте ADQM. В дальнейшем по запросу ноутбуки будут сохраняться в эту таблицу.
Чтобы загрузить все локальные ноутбуки на сервер, выполните Upload All Local….
Загрузка ноутбука с сервера
Чтобы загрузить ноутбук с сервера ClickHouse в интерфейс ADQM Notebook, кликните Load from Server… и выберите нужный ноутбук в открывшемся окне.
Если выбран ноутбук с именем уже существующего в интерфейсе ноутбука и существующий ноутбук отличается от загружаемого, то откроется окно, где можно указать какая версия должна быть в интерфейсе: локальная, серверная или обе (в этом случае загруженный с сервера ноутбук будет отмечен как from server).
Получение ссылки на ноутбук
Чтобы поделиться ссылкой на ноутбук с другими пользователями, кликните Share notebook на панели управления ADQM Notebook — ссылка на текущий ноутбук будет скопирована в буфер обмена.
Ссылка содержит полное состояние ноутбука (ячейки, переменные, настройки графиков), сжатые в хеш URL-адреса. В ссылку не включаются результаты запросов; URL-адрес подключения к серверу ADQMDB включается, а учетные данные — нет. Для выполнения запросов получателям требуется доступ к тому же серверу ADQMDB.
Панель Databases
На панели DATABASES в интерактивном виде выводится информация о базах данных и таблицах ADQM. Если в конфигурации ADQM не описан ни один логический кластер, на панели выводятся базы данных, расположенные на текущем хосте ADQM.
Если в конфигурации есть описание одного или нескольких кластеров, панель содержит две вкладки:
-
LOCAL — показывает базы данных на текущем хосте ADQM (включая
information_schemaиsystem); -
CLUSTER — показывает иерархическое дерево баз данных и таблиц кластера (без базы данных
information_schema). Если в конфигурации описан один кластер, он будет отображаться на вкладке по умолчанию. Если сконфигурировано несколько кластеров ADQM, кластер для отображения на панели DATABASES можно выбрать из выпадающего списка.
Клик по иконке 
Refresh обновляет информацию по базам данным и таблицам.
Чтобы развернуть базу данных и посмотреть таблицы, которые в ней находятся, кликните по строке базы данных. В строке каждой таблицы указывается ее размер, а по цветовому индикатору можно визуально оценить размер таблицы относительно самой большой таблицы в базе данных. На вкладке CLUSTER для таблиц также указывается количество хостов в кластере, на которых располагаются табличные данные.
При наведении курсора мыши на строку таблицы:
-
Во всплывающем окне (tooltip) можно посмотреть дополнительную информацию о таблице: табличный движок, общее количество строк, общий размер и распределение данных по хостам (на вкладке CLUSTER).
Общая информация о таблице на вкладке CLUSTER
Общая информация о таблице на вкладке CLUSTER -
С помощью иконки
Insert SELECT query можно автоматически вставить в выбранную SQL-ячейку (или в новую, если ни одна ячейка не выбрана) запрос на выборку 100 строк из данной таблицы:-
на вкладке LOCAL:
SELECT * FROM "<database_name>"."<table_name>" LIMIT 100; -
на вкладке CLUSTER:
SELECT * FROM clusterAllReplicas('<cluster_name>', '<table_name>', '<table_name>') LIMIT 100.
Вставка запроса на чтение данных из таблицы
Вставка запроса на чтение данных из таблицы
-
Чтобы развернуть таблицу и посмотреть ее столбцы, кликните по строке таблицы. Для каждого столбца показывается его имя и тип данных. При наведении курсора мыши на строку, соответствующую столбцу таблицы, в ней показывается иконка Insert column name, клик по которой вставляет имя столбца в редактор запроса выбранной SQL-ячейки (или в новую ячейку, если ни одна не выбрана).
Чтобы развернуть структуру всех таблиц в рамках одной базы данных, в строке базы данных кликните по иконке Expand all tables, которая становится видимой при наведении курсора мыши на базу данных в панели DATABASES (если все таблицы уже развернуты, иконка 
Collapse all tables в строке базы данных позволяет их свернуть).
SQL-ячейки
Новая SQL-ячейка содержит поле редактирования SQL-запроса и панель управления. После выполнения запроса в ячейку добавляется статистика выполнения запроса QUERY STATS и панель результатов запроса (или панель Error, если при выполнении запроса возникла ошибка).
При создании ноутбук содержит одну SQL-ячейку.
Текст запроса
В поле редактирования SQL-запроса поддерживается следующая функциональность:
-
Подсветка синтаксиса SQL.
-
Нумерация строк (включается/отключается в настройках, см. ниже). Клик по номеру строки выделяет всю строку целиком.
-
Автоматическое увеличение/уменьшение поля редактирования в зависимости от размера SQL-кода. Размер поля также можно изменять вручную, двигая мышью его нижнюю границу. Двойной клик по маркеру изменения размера на нижней границе поля возвращает его к размеру, определяемому автоматически в зависимости от размера текста запроса.
Для поля редактирования текста запроса в SQL-ячейке можно настроить следующие параметры (окно с настройками открывается кликом по иконке Settings в правом верхнем углу интерфейса):
-
Font Size — размер шрифта (настройка не влияет на текстовые ячейки);
-
Word Wrap — включает/отключает перенос строк (в текстовых ячейках перенос строк всегда включен, независимо от этого параметра);
-
Line Numbers — включает/отключает нумерацию строк (в текстовых ячейках нумерация строк может быть включена только для режима редактирования);
-
Max Rows per Query — максимальное количество строк в запросе. Возможные значения:
100,500,1000,5000,10000. Значение по умолчанию:1000.
Переменные в запросах
В панели VARIABLES можно определять переменные в виде пар ключ/значение. На переменную можно ссылаться в запросе по ключу, используя формат {{variable_name}} — перед отправкой запроса на выполнение эта запись будет автоматически заменяться значением переменной. Ключи переменных сопоставляются без учета регистра (например, записи {{MyVar}}, {{myvar}}, {{MYVAR}} соответствуют одной и той же переменной).
В заголовке панели VARIABLES справа показывается счетчик добавленных переменных. При добавлении переменной с повторяющимся именем соответствующие поля подсвечиваются красным, счетчик переменных не увеличивается, а значение дублирующейся переменной будет игнорироваться.
Панель управления
Панель управления SQL-ячейки, расположенная выше поля редактирования текста запроса, содержит следующие элементы:
-
Drag to reorder — при нажатии и удержании иконки можно перемещать ячейку относительно других ячеек в рамках ноутбука с помощью механизма drag-and-drop. -
[n] — порядковый номер ячейки в ноутбуке.
-
Статус выполнения запроса:
— запрос не выполнялся;
— запрос выполняется в данный момент;
— запрос выполнен успешно;
— ошибка выполнения запроса.Для запроса, выполнение которого завершилось (успешно или неуспешно), рядом с индикатором статуса также показывается время выполнения.
-
Run — запустить выполнение запроса. -
Toggle query — свернуть/развернуть поле с кодом запроса (если это поле свернуто, начало текста запроса отображается в панели управления).
-
Fullscreen — развернуть (или свернуть) SQL-ячейку на полный экран.
-
Copy query — скопировать текст запроса. -
Move up — переместить ячейку на одну позицию выше предыдущей ячейки.
-
Move down — переместить ячейку на одну позицию ниже следующей ячейки. -
Add cell below — создать новую ячейку того же типа ниже.
-
Delete cell — удалить ячейку.
Выполнение запроса
Чтобы запустить запрос, выполните одно из действий:
-
Кликните
Run в панели управления соответствующей SQL-ячейки. Во время выполнения запроса кнопка Run визуально меняется на Stop — клик по ней отменяет выполнение HTTP-запроса. -
Кликните по SQL-ячейке, чтобы ее выбрать (выбранная ячейка подсвечивается зеленым цветом), и нажмите
CTRL+ENTER(илиCMD+ENTER).
В интерфейсе ADQM Notebook, несколько SQL-ячеек, запущенные по отдельности, могут выполнять свои запросы одновременно. Команда запускает запросы в ячейках последовательно сверху вниз, ожидая завершения каждого запроса, прежде чем запускать следующий.
Панель результатов запроса
После выполнения запроса результаты выводятся на панели результатов, которая содержит вкладки Table и Chart, где полученные данные можно посмотреть в виде таблицы или графика соответственно. На панели результатов также располагается:
-
общая информация по результатам выполнения запроса (количество полученных строк данных и время выполнения);
-
поле Search results…, с помощью которого можно фильтровать данные в результирующем наборе в режиме реального времени по любому столбцу — на панели будут показаны только значения, соответствующие указанному фильтру;
-
иконка
Download, с помощью которой можно сохранить результаты запроса в одном из поддерживаемых форматах (CSV, TSV, JSON, JSONLines, Parquet).Данные в форматах CSV, TSV, JSON и JSONLines генерируются на стороне клиента из кешированных результатов. Для Parquet повторно выполняется весь запрос на сервере ADQMDB, поскольку формат требует генерации на стороне сервера. Это значит:
-
Запрос может вернуть другие результаты, если данные изменились.
-
Возможна дополнительная нагрузка на сервер.
-
Панель результатов можно сворачивать/разворачивать с помощью иконки в левом верхнем углу.
Чтобы удалить результаты выполнения запросов всех SQL-ячеек в ноутбуке, откройте контекстное меню Clear в панели управления ноутбука и выберите Clear Results.
Панель ошибки выполнения запроса
В случае возникновения ошибки при выполнении запроса соответствующее сообщение выводится на панели Error (вместо панели результатов).
Таблица результатов
После выполнения запроса в 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.
График строится по обеим осям между минимальными и максимальными значениями из результатов запроса.
Статистика выполнения запроса
Если в 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.
Текстовые ячейки
Для различных записей и комментариев в ноутбуке можно использовать текстовые ячейки.
Текст форматируется с помощью разметки markdown. Поддерживаемый markdown-синтаксис:
-
# H1,## H2,### H3— заголовки; -
**text**или__text__— жирный текст; -
*text*или_text_— курсив; -
***text***или___text___— жирный курсив; -
`code`— фрагменты кода внутри строки (inline); -
```multiline code```— многострочные блоки кода; -
- itemили1. item— списки; -
> quote— цитаты; -
[text](url)— ссылки; -
---— горизонтальная линия для разделения блоков текста.
В текстовых ячейках содержатся те же элементы управления, что в SQL-ячейках, за исключением тех, что относятся к выполнению запросов (кнопка запуска, индикаторы статуса и времени выполнения запроса).
Управление ячейками
Добавление ячейки
Добавить новую ячейку можно одним из следующих способов:
-
Кликните Add SQL Cell в рабочей области ноутбука — добавится новая SQL-ячейка. Также можно выбрать тип добавляемой ячейки из контекстного меню.
Добавление новой ячейки в ноутбук
Добавление новой ячейки в ноутбук -
Нажмите на иконку
Add cell below на панели управления существующей ячейки — ниже этой ячейки будет добавлена новая ячейка того же типа.
Создание новой ячейки из существующей
Создание новой ячейки из существующей
Копирование содержимого ячейки
Чтобы скопировать запрос из SQL-ячейки или текст с применяемой markdown-разметкой из текстовой ячейки, используйте иконку в панели управления ячейки.
Изменение типа ячейки
Каждая ячейка имеет выпадающий список, позволяющий изменить ее тип:
-
SQL → Text: код запроса преобразуется в текстовое содержимое;
-
Text → SQL: текстовое содержимое преобразуется в код запроса, включается подсветка синтаксиса.
Перемещение ячейки
Перемещать ячейку можно следующими способами:
-
Используйте иконки
Move up и Move down на панели управления ячейки.
Иконки для перемещения ячейки вверх/вниз
Иконки для перемещения ячейки вверх/вниз -
Нажмите на иконку
Drag to reorder и переместите ячейку на новое место, используя механизм drag-and-drop.
Перемещение ячейки с помощью drag-and-drop
Перемещение ячейки с помощью drag-and-drop
Удаление ячейки
Чтобы удалить текстовую или SQL-ячейку, нажмите на иконку Delete cell на панели управления ячейки.
При выборе Clear All Cells из контекстного меню Clear в панели управления ноутбука удаляются все ячейки в ноутбуке, остается только одна пустая SQL-ячейка.
Комбинации клавиш
В интерфейсе ADQM Notebook также предусмотрены различные комбинации клавиш для управления ячейками в ноутбуке, которые можно посмотреть, кликнув по иконке Keyboard shortcuts в правом верхнем углу интерфейса.
Настройки
Чтобы открыть настройки интерфейса ADQM Notebook, кликните по иконке Settings в правом верхнем углу интерфейса.
Настройки включают:
-
параметры для конфигурирования поля редактирования ячеек;
-
Auto-save Notebook — определяет, сохранять ли автоматически ноутбуки в localStorage при их изменении;
-
Expand JSON/Arrays by default — определяет, сворачивать ли по умолчанию JSON-объекты и массивы в результатах запроса;
-
параметры, которые определяют как показывать статистику выполнения запроса.