Когда появляется необходимость документировать схемы баз данных, разные DBMS предоставляют свои инструменты для подобных задач. И большинство из них поддерживает DESC table_name, в том числе и ClickHouse. Однако, результат этой команды не столь выразителен, как хотелось бы.

DESCRIBE TABLE data_lr  name        type      default_type   default_expression   comment   codec_expression   ttl_expression Path        String                                                  ZSTD(3) Value       Float64                                                 Gorilla, LZ4 Time        UInt32                                                  DoubleDelta, LZ4 Date        Date                                                    DoubleDelta, LZ4 Timestamp   UInt32                                                  DoubleDelta, LZ4

При этом, системные таблицы tables и columns содержат исчерпывающую информацию, объединив которую, можно получить вот такой симпатичный результат:

Вдохновение

Перед тем, как начать заботливо пилить собственное решение, лишённое фатальных недостатков, я поискал доступные варианты. И вот эта работа вдохновила меня начать собственный проект. Некоторые заготовки с благодарностью позаимствованы оттуда, с указанием авторства.

Что такое PlantUML

Несколько слов о том, что это представляет из себя этот продукт. Для наилучшего понимания советую зайти на официальную страницу. Если в двух словах, то это программа, которая преобразует текстовое описание диаграмм, например:

@startuml Bob -> Alice : hello @enduml

в изображения

Поддерживаются очень многие форматы, например диаграммы прецедентов, классов, деятельности, компонентов и другие. Имеется плагин для Atlassian Confluence, позволяющий использовать макрос и генерировать изображения прямо на страницах wiki. Плагин для pandoc (и не один), для LaTeX, и многое другое.

Можно даже попробовать прямо на сайте.

Идея

Идея проста: в таблице system.tables содержится общая информация о таблицах, движках, ключах партиционирования, сортировки и сэмплирования, и др. А в другой системной таблице, system.columns, подробные данные о каждой из колонок. Комбинируя эти данные, можно легко сгенерировать часть, которая относится к колонкам и ключам таблиц. Это вторая половина каждой из таблиц на диаграмме.

Реализация

Про таблицы с колонками ясно, но есть ещё одна часть, которой я уделил отдельное внимание. Каждый из движков таблиц имеет параметры, которые необходимо распарсить. Например, ReplacingMergeTree содержит опциональный параметр Version. И параметры определяются исключительно движком. Дополнительные параметры необходимы для создания Replicated*MergeTree. Также для MaterializedView всегда создаётся таблица с данными. Эту таблицу не имеет смысла показывать отдельно, и она отображается как отдельная часть конфига для MV.

Это было одной из самых интересных для меня частей проекта. Пришлось познакомиться с токенами и парсингом текста, хотя записать строки и идентификаторы в массив настроек движка оказалось ± легко. А уже при помощи них записать пары ключ-значение. И это первая половина таблиц на диаграмме.

Также некоторые таблицы зависят друг от друга. Например, Distributed всегда указывает на локальные таблицы, а Buffer располагается перед *MergeTree таблицами, чтобы принимать мелкие вставки. И для этих таблиц отдельно устанавливаются отношения. На диаграмме они представлены стрелочками.

Результат

@startuml ' This diagram is generated with https://github.com/Felixoid/clickhouse-plantuml !define Table(x) class x << (T,mistyrose) >> !define View(x) class x << (V,lightblue) >> !define MaterializedView(x) class x << (m,orange) >> !define Distributed(x) class x << (D,violet) >>  hide empty methods hide stereotypes skinparam classarrowcolor gray  Distributed(graphite.data) {   ENGINE=**Distributed**   ..engine config..   cluster: graphite_data   database: graphite   table: data_lr   sharding_key: cityHash64(Path)   ==columns==   Path: String   Value: Float64   Time: UInt32   Date: Date   Timestamp: UInt32 }  Table(graphite.data_lr) {   ENGINE=**ReplicatedGraphiteMergeTree**   ..engine config..   rollup_config: graphite_rollup   ..replication..   zoo_path: /clickhouse/tables/graphite.data_lr/{shard}   replica: {replica}   ==columns==   Path: String <size:15><&signal></size>   Value: Float64   Time: UInt32 <size:15><&signal></size>   Date: Date <size:15><&list-rich></size>   Timestamp: UInt32   ..<size:15><&list-rich></size>partition key..   toYYYYMMDD(toStartOfInterval(Date, toIntervalDay(3)))   ..<size:15><&signal></size>sorting key..   Path, Time }  Table(graphite.index) {   ENGINE=**ReplicatedReplacingMergeTree**   ..engine config..   version: Version   ..replication..   zoo_path: /clickhouse/tables/graphite.index/1   replica: {replica}   ==columns==   Date: Date <size:15><&list-rich></size> <size:15><&signal></size>   Level: UInt32 <size:15><&signal></size>   Path: String <size:15><&signal></size>   Version: UInt32   ..<size:15><&list-rich></size>partition key..   toYYYYMM(Date)   ..<size:15><&signal></size>sorting key..   Level, Path, Date }  Table(graphite.tagged) {   ENGINE=**ReplicatedReplacingMergeTree**   ..engine config..   version: Version   ..replication..   zoo_path: /clickhouse/tables/graphite.tagged/1   replica: {replica}   ==columns==   Date: Date <size:15><&list-rich></size> <size:15><&signal></size>   Tag1: String <size:15><&signal></size>   Path: String <size:15><&signal></size>   Tags: Array(String)   Version: UInt32   ..<size:15><&list-rich></size>partition key..   toYYYYMM(Date)   ..<size:15><&signal></size>sorting key..   Tag1, Path, Date }  graphite.data_lr -|> graphite.data @enduml

Ближайшие планы

Добавить тесты, в идеале — интеграционные с поддержкой нескольких версий ClickHouse. А также добавить генерацию диаграмм для кластеров ClickHouse. Возможно, кто-то найдёт для себя интересные кейсы и составит issue. Например можно добавить опциональное описание кодеков сжатия, хотя для меня они пока не важны.

Вместо заключения

Я буду рад, если этот маленький проект позволит кому-то сэкономить время и предоставит возможность составить хорошую документацию.

Начать пользоваться можно, просто скачав модуль из pypi:

pip install clickhouse-plantuml clickhouse-plantuml -h

Исходный код находится здесь.

Спасибо, что потратили время на прочтение!