Ноутбуки

Елена Дворядкина

Ноутбук (notebook) в контексте ADQM Notebook — это набор SQL-ячеек с выполняемыми запросами и текстовых ячеек с комментариями, состояние которого можно сохранить для последующего восстановления или передачи другим пользователям. В данной статье описаны функциональные возможности интерфейса ADQM Notebook для работы с ноутбуками.

Панель Notebooks

Панель NOTEBOOKS предназначена для управления ноутбуками в интерфейсе ADQM Notebook.

Чтобы создать новый ноутбук, кликните по иконке add cell below icon dark add cell below icon light New Notebook в заголовке панели NOTEBOOKS — будет создан ноутбук с одной SQL-ячейкой.

Создание нового ноутбука
Создание нового ноутбука
Создание нового ноутбука
Создание нового ноутбука

Чтобы изменить имя ноутбука, наведите курсор мыши на строку ноутбука, кликните по иконке edit text icon dark edit text icon light Rename и введите новое имя в поле редактирования.

Переименование ноутбука
Переименование ноутбука
Переименование ноутбука
Переименование ноутбука

Ноутбуки можно перемещать в списке, используя механизм drag-and-drop.

Перемещение ноутбука
Перемещение ноутбука
Перемещение ноутбука
Перемещение ноутбука

Чтобы удалить ноутбук, наведите курсор мыши на строку ноутбука в панели NOTEBOOKS и кликните по иконке delete notebook icon dark delete notebook icon light Delete.

Удаление ноутбука
Удаление ноутбука
Удаление ноутбука
Удаление ноутбука

 
В строке каждого ноутбука (при наведении курсора мыши) также доступа иконка settings icon dark settings icon light Query defaults, которая открывает список параметров для настройки ограничений по использованию ресурсов при выполнении запросов в ноутбуке: max_memory_usage, max_execution_time, max_threads. Указанные значения будут использоваться по умолчанию при выполнении запросов в SQL-ячейках ноутбука. Также для каждой SQL-ячейки можно назначить другие значения этих параметров, которые будут иметь более высокий приоритет, чем указанные на уровне ноутбука — см. Query settings на панели управления SQL-ячейки.

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

Рабочее пространство ноутбука

Основное рабочее пространство ноутбука (notebook workspace) включает:

  • Область для работы с ячейками, где можно создавать/редактировать/удалять ячейки типа SQL и Text.

  • Панель управления, которая содержит следующие элементы:

    • run all icon — запустить выполнение запросов во всех SQL-ячейках ноутбука.

    • Clear toggle query icon dark toggle query icon light — развернуть список команд для очистки ячеек (Clear Results — удалить результаты запросов всех SQL-ячеек; Clear All Cells — удалить все ячейки из ноутбука, оставив одну пустую SQL-ячейку).

    • notebook overview icon dark notebook overview icon light Overview — посмотреть обобщенную информацию о ноутбуке.

    • collapse all queries icon dark collapse all queries icon light Collapse all queries — свернуть все запросы в ноутбуке.

    • expand all queries icon dark expand all queries icon light Expand all queries — развернуть все запросы в ноутбуке.

    • export icon dark export icon light Export — экспортировать ноутбук в JSON-файл.

    • import icon dark import icon light Import — импортировать ноутбук из JSON-файла.

    • server icon dark server icon light Server toggle query icon dark toggle query icon light — развернуть список команд для хранения ноутбуков на сервере ClickHouse.

Рабочее пространство ноутбука
Рабочее пространство ноутбука
Рабочее пространство ноутбука
Рабочее пространство ноутбука

Обзор ноутбука (Overview)

Чтобы понять и проанализировать общее состояние ноутбука, в который добавлено множество ячеек с различными типами запросов, обращающихся к разным таблицам, может быть удобно посмотреть информацию о ноутбуке в обобщенном виде. Чтобы это сделать, кликните notebook overview icon dark notebook overview icon light Overview в панели управления ноутбука.

Просмотр общей информации о ноутбуке
Просмотр общей информации о ноутбуке
Просмотр общей информации о ноутбуке
Просмотр общей информации о ноутбуке

Открывшееся модальное окно Overview of <notebook_name> показывает содержимое ноутбука <notebook_name> в сокращенном формате.

Окно Notebook Overview
Окно Notebook Overview
Окно Notebook Overview
Окно Notebook Overview

В верхней части окна выводится общая информация о ячейках ноутбука:

  • общее количество ячеек в ноутбуке;

  • количество ячеек каждого типа (SQL, Text);

  • количество ячеек с разными статусами выполнения запросов (OK, pending, errors);

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

  • общее время выполнения запросов в ячейках.

 
Ниже расположена панель TABLES, где перечисляются все таблицы, к которым обращаются запросы в SQL-ячейках ноутбука, с указанием для каждой таблицы общего числа запросов, обращающихся к ней. Клик по таблице подсвечивает все ячейки с запросами, где используется эта таблица.

 
В левой части окна находится общий список ячеек ноутбука с сокращенной информацией. Для каждой ячейки показывается порядковый номер, индикатор статуса выполнения запроса (для текстовых ячеек — индикатор query status grey icon dark query status grey icon light), тип ячейки (SQL или TEXT), а также "заголовок" ячейки в зависимости от типа:

  • TEXT — первая строка текста в ячейке;

  • SQL — имя объекта, к которому обращается запрос (например: имя базы данных или таблицы при создании объекта; имя таблицы при вставке данных или запись вида source_table → target_table при вставке данных из одной таблицы в другую; имена таблиц/табличных функций при чтении данных).

С помощью расположенных выше списка предопределенных фильтров All, SQL, TEXT, Errors можно выбрать ячейки какого типа должны быть показаны в окне.

 
В основной области окна Overview показывается более подробная (но также агрегированная) информация по ячейкам ноутбука. Для каждой SQL-ячейки дополнительно выводится:

  • время, когда запрос выполнялся последний раз;

  • длительность выполнения запроса и количество возвращенных строк данных (для запросов, которые читают данные);

  • тип запроса (CREATE, SELECT, INSERT и др.);

  • таблицы, участвующие в запросе (не более 20 таблиц для одного запроса). Таблицы для записи данных отмечаются иконкой edit text icon dark edit text icon light, читаемые таблицы — read table icon dark read table icon light. Для каждой таблицы также показывается количество запросов в ячейках ноутбука, в которых она задействована. При наведении курсора мыши на таблицу в ячейке также подсвечиваются другие ячейки с запросами, обращающимися к этой таблице. Клик по таблице также подсвечивает все ячейки с этой таблицей, при этом соответствующий фильтр фиксируется в панели TABLES.

Клик по ячейке в этой области выполняет переход на эту ячейку в рабочем пространстве ноутбука.

Просмотр ячеек ноутбука в окне Notebook Overview
Просмотр ячеек ноутбука в окне Notebook Overview
Просмотр ячеек ноутбука в окне Notebook Overview
Просмотр ячеек ноутбука в окне Notebook Overview

Экспорт/импорт ноутбуков в формате JSON

Чтобы экспортировать текущий ноутбук в JSON-файл, кликните export icon dark export icon light Export в панели управления ноутбука.

Экспорт ноутбука в JSON-файл
Экспорт ноутбука в JSON-файл
Экспорт ноутбука в JSON-файл
Экспорт ноутбука в JSON-файл

В каталоге Downloads будет создан JSON-файл с тем же именем, что и ноутбук. В этом файле будет содержаться полная информация о состоянии ноутбука:

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

  • переменные;

  • настройки, включая состояние сортировки (столбец, направление), параметры графиков (тип, оси);

  • адрес подключения (но он не будет применяться при импорте для удобства передачи на другой хост);

  • имя пользователя.

Пароль не сохраняется.

 

Чтобы импортировать ранее экспортированный ноутбук, кликните import icon dark import icon light Import в панели управления ноутбука и выберите JSON-файл.

Импорт ноутбука из JSON-файла
Импорт ноутбука из JSON-файла
Импорт ноутбука из JSON-файла
Импорт ноутбука из JSON-файла

Импортированный ноутбук будет добавлен в список на панели NOTEBOOKS c именем в формате <notebook_name> (dd-mm-yyyy hh:mm:ss), где <notebook_name> — имя JSON-файла, соответствующее имени ноутбука, dd-mm-yyyy hh:mm:ss — дата и время импорта.

Хранение ноутбуков на сервере ClickHouse

Ноутбуки, созданные в интерфейсе ADQM Notebook, можно сохранять в отдельную базу данных сервера ClickHouse и позже загружать их оттуда. Кроме того, при подключении будет выполняться автоматическая синхронизация с сервером — при успешном подключении ноутбуки автоматически будут загружаться из серверного хранилища, если оно доступно.

Настройка хранилища ноутбуков

Чтобы подготовить хранилище для ноутбуков на сервере ClickHouse, выполните следующие шаги:

  1. Откройте список server icon dark server icon light Server на панели управления ноутбука и выберите команду settings icon dark settings icon light Manage Storage.

    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков

    Подтвердите переход к настройке хранилища.

    Переход к настройке хранилища ноутбуков
    Переход к настройке хранилища ноутбуков
    Переход к настройке хранилища ноутбуков
    Переход к настройке хранилища ноутбуков

    Вам также будет предложено настроить хранилище ноутбуков, если оно не было ранее подготовлено, при первой попытке сохранить ноутбук на сервер.

  2. В открывшемся окне Setup Server Storage подтвердите создание таблицы notebooks в базе данных adqm_notebooks (в эту таблицу в дальнейшем по запросу будут сохраняться ноутбуки) и выберите вариант хранения ноутбуков:

    • Local — локальная таблица на основе движка ReplacingMergeTree, которая будет храниться на текущем хосте ADQM. Каждый хост будет "видеть" только свои ноутбуки.

    • Replicated — реплицированная таблица на основе движка ReplicatedReplacingMergeTree, которая будет храниться на всех хостах кластера ADQM. Ноутбуки, созданные на каком-либо хосте и сохраненные на сервер, будут доступны для загрузки в интерфейс ADQM Notebook с любого хоста. При выборе этой опции необходимо указать целевой кластер.

    Если изначально выбран тип хранилища Local, его можно будет позже изменить на Replicated и автоматически переместить ноутбуки, которые хранились в локальных таблицах на отдельных хостах, в одну реплицированную таблицу (см. Изменение типа хранилища ноутбуков ниже).

    Создание локальной таблицы ADQM для хранения ноутбуков
    Создание локальной таблицы ADQM для хранения ноутбуков
    Создание локальной таблицы ADQM для хранения ноутбуков
    Создание локальной таблицы ADQM для хранения ноутбуков

  3. Нажмите Create Storage.

Особенности хранилища ноутбуков:

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

  • для сжатия данных используется алгоритм ZSTD(3);

  • применяется партиционирование по месяцу (toYYYYMM(created_at)).

Сохранение ноутбука на сервер

Чтобы загрузить ноутбук на сервер, на панели управления ноутбука откройте список server icon dark server icon light Server и выберите команду export icon dark export icon light Save to Server.

Сохранение ноутбука на сервер ClickHouse
Сохранение ноутбука на сервер ClickHouse
Сохранение ноутбука на сервер ClickHouse
Сохранение ноутбука на сервер ClickHouse

Чтобы загрузить все локальные ноутбуки на сервер, выполните server icon dark server icon light Upload All Local…​.

Сохранение всех ноутбуков на сервер
Сохранение всех ноутбуков на сервер
Сохранение всех ноутбуков на сервер
Сохранение всех ноутбуков на сервер

Загрузка ноутбука с сервера

Чтобы загрузить ноутбук с сервера ClickHouse в интерфейс ADQM Notebook, кликните import icon dark import icon light Load from Server…​ и выберите нужный ноутбук в открывшемся окне.

Загрузка ноутбука с сервера
Загрузка ноутбука с сервера
Загрузка ноутбука с сервера
Загрузка ноутбука с сервера
Выбор ноутбука для загрузки
Выбор ноутбука для загрузки
Выбор ноутбука для загрузки
Выбор ноутбука для загрузки

Если выбран ноутбук с именем уже существующего в интерфейсе ноутбука и существующий ноутбук отличается от загружаемого, то откроется окно, где можно указать какая версия должна быть в интерфейсе: локальная, серверная или обе (в этом случае загруженный с сервера ноутбук будет отмечен как from server).

Выбор версии ноутбука для загрузки
Выбор версии ноутбука для загрузки
Выбор версии ноутбука для загрузки
Выбор версии ноутбука для загрузки

Изменение типа хранилища ноутбуков

Чтобы изменить тип хранилища ноутбуков с Local на Replicated и объединить все ранее сохраненные в локальных таблицах ноутбуки в одну реплицированную таблицу, выполните миграцию данных следующим образом:

  1. Выберите settings icon dark settings icon light Manage Storage в меню server icon dark server icon light Server на панели управления ноутбука.

    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков
    Управление хранилищем ноутбуков

  2. В открывшемся окне Setup Server Storage выберите кластер ADQM и нажмите Migrate to Replicated.

    Перенос ноутбуков из локальных таблиц в реплицированную
    Перенос ноутбуков из локальных таблиц в реплицированную
    Перенос ноутбуков из локальных таблиц в реплицированную
    Перенос ноутбуков из локальных таблиц в реплицированную

После успешного выполнения миграции на каждом хосте выбранного кластера ADQM будет создана реплицированная таблица adqm_notebooks.notebooks со списком ноутбуков, скопированных со всех хостов, на которых они были ранее сохранены локально. При этом локальные таблицы с ноутбуками на соответствующих хостах будут переименованы в notebooks_local_backup — их можно будет позже удалить из базы данных adqm_notebooks через диалог Server Storage Settings или вручную.

После миграции все ноутбуки будут автоматически загружены в интерфейс ADQM Notebook. При подключении от имени другого пользователя ноутбуки, которые были синхронизированы с сервером предыдущим пользователем, очищаются, а локальные (не сохраненные на сервере) — остаются.

Если на текущем узле все еще используется локальная таблица для хранения ноутбуков, а на других узлах кластера — уже реплицированная (например, если шард был недоступен во время миграции), сохранение ноутбуков блокируется с сообщением Split storage detected — Saves are blocked until you migrate.

Получение ссылки на ноутбук

Чтобы поделиться ссылкой на ноутбук с другими пользователями, кликните share notebook icon dark share notebook icon light Share notebook на панели управления ADQM Notebook — ссылка на текущий ноутбук будет скопирована в буфер обмена.

Копирование ссылки на ноутбук
Копирование ссылки на ноутбук
Копирование ссылки на ноутбук
Копирование ссылки на ноутбук

Ссылка содержит полное состояние ноутбука (ячейки, переменные, настройки графиков), сжатые в хеш URL-адреса. В ссылку не включаются результаты запросов; URL-адрес подключения к серверу ADQMDB включается, а учетные данные — нет. Для выполнения запросов получателям требуется доступ к тому же серверу ADQMDB.

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