Поиск по документации

Документация по встроенному веб-интерфейсу поиска по документации, доступному по пути /docs HTTP-интерфейса и работающему на основе таблицы system.documentation

Страница поиска по документации — это небольшой автономный веб-интерфейс для мгновенного поиска по встроенной справочной документации. Он доступен по пути /docs на любом HTTP-порту ClickHouse.

Чтобы открыть его, перейдите по пути /docs на любом HTTP-порту ClickHouse (например, http://localhost:8123/docs).

​

Что здесь можно делать

По мере ввода на странице выполняются HTTP-запросы к таблице system.documentation, а затем отображается Markdown для выбранной сущности. Поскольку страница читает system.documentation, она охватывает все сущности, доступные через эту таблицу, — функции, агрегатные функции, табличные функции, движки таблиц, движки баз данных, типы данных, настройки, форматы, кодеки сжатия, события профилирования, метрики, сами системные таблицы и многое другое — и всегда соответствует документации, встроенной в работающий сервер.

Введите текст в поле поиска, и совпадения появятся в списке с цветовой маркировкой по типам; при выборе совпадения отображается его документация. Отображение включает:

• ссылку с иконкой карандаша рядом с заголовком сущности, которая открывает ее исходный файл на GitHub; путь берется из столбца source таблицы system.documentation;
• подсветку синтаксиса ClickHouse SQL в блоках кода с использованием того же встроенного лексера (Lexer.wasm), что и в интерфейсе /play;
• математические формулы TeX через KaTeX (например, формулу на странице corr);
• блоки :::note/:::tip/…, якоря заголовков с доступными для публикации ссылками и кнопку «Copy», появляющуюся при наведении на блоки кода;
• относительные ссылки, которые открывают другую документированную сущность внутри приложения, если она существует, и ведут на https://clickhouse.com/docs в противном случае; ссылки «Related» и «Alias of» также становятся внутренними ссылками приложения.

Текущий поисковый запрос, открытая сущность и раздел отражаются во фрагменте URL, поэтому на конкретную страницу или раздел можно дать прямую ссылку, а состояние восстанавливается при навигации браузера назад/вперед. Переключатель светлой/темной темы (с автоопределением) соответствует /play.

​

Подключение

В заголовке есть поля URL, user и password — как и в /play. Если страница загружается с ClickHouse, в качестве URL по умолчанию используется текущий origin; если страница открывается как локальный файл, по умолчанию используется http://localhost:8123/, поэтому страницу также можно открыть локально для работы с удаленным сервером. Кэш имен перекрестных ссылок автоматически перестраивается при изменении соединения.

​

Ресурсы

Все ресурсы — включая средство рендеринга Markdown (Marked), средство рендеринга математических формул (KaTeX вместе с его шрифтами) и SQL-лексер — отдаются прямо из бинарного файла ClickHouse, когда страница обслуживается по HTTP. С HTTP-источника ClickHouse не загружаются сторонние CDN, поэтому страница полностью самодостаточна, работает офлайн и не выполняет сторонний сетевой код наряду с учетными данными, которые она обрабатывает.

​

Соображения безопасности

Страница отправляет запросы к HTTP-конечной точке ClickHouse с учетными данными, указанными в заголовке, поэтому здесь действуют те же меры предосторожности, что и для HTTP-протокола:

• Всегда отдавайте /docs по HTTPS в ненадежных средах, чтобы защитить учетные данные.
• Ограничивайте доступ на уровне сети (межсетевой экран, обратный прокси или конфигурация listen_host) так же, как вы ограничиваете доступ к HTTP-протоколу.

system.documentation содержит только статическую справочную документацию, встроенную в сервер, поэтому страница не раскрывает никаких данных из ваших таблиц.