From e95223aa07e9a57a38f329aa2414908068b4409c Mon Sep 17 00:00:00 2001 From: alesapin Date: Fri, 13 Sep 2019 16:15:19 +0300 Subject: [PATCH] Better docs --- docs/ru/operations/system_tables.md | 28 +++++++++++++-- docs/ru/operations/table_engines/mergetree.md | 34 +++++++++++-------- docs/ru/query_language/alter.md | 2 +- 3 files changed, 46 insertions(+), 18 deletions(-) diff --git a/docs/ru/operations/system_tables.md b/docs/ru/operations/system_tables.md index bcf61a7f0da..d6c81ee97b9 100644 --- a/docs/ru/operations/system_tables.md +++ b/docs/ru/operations/system_tables.md @@ -280,7 +280,9 @@ SELECT * FROM system.metrics LIMIT 10 - `primary_key_bytes_in_memory_allocated` (UInt64) - выделенный с резервом объем памяти (в байтах) для размещения первичных ключей; - `database (String)` - имя базы данных; - `table (String)` - имя таблицы; -- `engine (String)` - имя движка таблицы, без параметров. +- `engine (String)` - имя движка таблицы, без параметров; +- `path (String)` - путь к куску на диске; +- `disk (String)` - имя диска, на котором находится кусок; - `is_frozen (UInt8)` – Признак, показывающий существование бэкапа партиции. 1, бэкап есть. 0, бэкапа нет. Смотрите раздел [FREEZE PARTITION](../query_language/alter.md#alter_freeze-partition) ## system.part_log {#system_tables-part-log} @@ -291,7 +293,7 @@ SELECT * FROM system.metrics LIMIT 10 Столбцы: -- `event_type` (Enum) — тип события. Столбец может содержать одно из следующих значений: `NEW_PART` — вставка нового куска; `MERGE_PARTS` — слияние кусков; `DOWNLOAD_PART` — загрузка с реплики; `REMOVE_PART` — удаление или отсоединение из таблицы с помощью [DETACH PARTITION](../query_language/alter.md#alter_detach-partition); `MUTATE_PART` — изменение куска. +- `event_type` (Enum) — тип события. Столбец может содержать одно из следующих значений: `NEW_PART` — вставка нового куска; `MERGE_PARTS` — слияние кусков; `DOWNLOAD_PART` — загрузка с реплики; `REMOVE_PART` — удаление или отсоединение из таблицы с помощью [DETACH PARTITION](../query_language/alter.md#alter_detach-partition); `MUTATE_PART` — изменение куска; `MOVE_PART` — перемещение куска между дисками. - `event_date` (Date) — дата события; - `event_time` (DateTime) — время события; - `duration_ms` (UInt64) — длительность; @@ -703,3 +705,25 @@ path: /clickhouse/tables/01-08/visits/replicas **latest_fail_reason** — причина последней ошибки мутации. [Оригинальная статья](https://clickhouse.yandex/docs/ru/operations/system_tables/) + +## system.disks {#system_tables-disks} + +Таблица содержит информацию о дисках, заданных в [конфигурации сервера](#table_engine/mergetree.md#table_engine-mergetree-multiple-volumes_configure). Имеет следующие столбцы: + +- `name String` — имя диска в конфигурации сервера. +- `path String` — путь к точке монтирования на файловой системе. +- `free_space UInt64` — свободное место на диске в данный момент времени в байтах. +- `total_space UInt64` — общее количество места на диске в данный момент времени в байтах. +- `keep_free_space UInt64` — количество байт, которое должно оставаться свободным (задается в конфигурации). + + +## system.storage_policies {#system_tables-storage_policies} + +Таблица содержит информацию о политиках хранения и томах, заданных в [конфигурации сервера](#table_engine/mergetree.md#table_engine-mergetree-multiple-volumes_configure). Данные в таблице денормализованны, имя одной политики хранения может содержаться несколько раз, по количеству томов в ней. Имеет следующие столбцы: + +- `policy_name String` — имя политики хранения в конфигурации сервера. +- `volume_name String` — имя тома, который содержится в данной политике хранения. +- `volume_priority UInt64` — порядковый номер тома, согласно конфигурации. +- `disks Array(String)` — имена дисков, содержащихся в данной политике хранения. +- `max_data_part_size UInt64` — максимальный размер куска, который может храниться на дисках этого тома (0 — без ограничений). +- `move_factor Float64` — доля свободного места, при превышении которой данные начинают перемещаться на следующий том. diff --git a/docs/ru/operations/table_engines/mergetree.md b/docs/ru/operations/table_engines/mergetree.md index 4aa0b0d0843..543c5177bd3 100644 --- a/docs/ru/operations/table_engines/mergetree.md +++ b/docs/ru/operations/table_engines/mergetree.md @@ -399,23 +399,21 @@ ALTER TABLE example_table ## Хранение данных таблицы на нескольких блочных устройствах {#table_engine-mergetree-multiple-volumes} ### Общее -Данные таблиц семейства MergeTree могут храниться на нескольких блочных устройствах. Это может оказаться полезным, например, при неявном разделении данных одной таблицы на "горячие" и "холодные", когда наиболее свежая часть занимает малый объем и запрашивается регулярно, а большой хвост исторических данных запрашивается редко. При наличии в системе нескольких дисков, "горячая" часть данных может быть размещена на быстрых дисках (NVMe SSDs), а холодная на более медленных (HDD). +Данные таблиц семейства MergeTree могут храниться на нескольких блочных устройствах. Это может оказаться полезным, например, при неявном разделении данных одной таблицы на "горячие" и "холодные", когда наиболее свежая часть занимает малый объем и запрашивается регулярно, а большой хвост исторических данных запрашивается редко. При наличии в системе нескольких дисков, "горячая" часть данных может быть размещена на быстрых дисках (NVMe SSDs или даже в памяти), а холодная на более медленных (HDD). -Минимальной перемещаемой единицей для MergeTree является кусок (part). Данные одного куска могут находится только на одном диске. Куски могут перемещаться между дисками в фоне, согласно пользовательским настройкам, а также с помощью [`ALTER`](../../query_language/alter.md#alter_move-partition) запросов. +Минимальной перемещаемой единицей для MergeTree является кусок (part). Данные одного куска могут находится только на одном диске. Куски могут перемещаться между дисками в фоне, согласно пользовательским настройкам, а также с помощью [ALTER](../../query_language/alter.md#alter_move-partition) запросов. ### Термины * Диск — примонтированное в файловой системе блочное устройство. -* Диск по умолчанию — путь на файловой системе, указанный в `` в основной конфигурации. +* Диск по умолчанию — диск, на котором находится путь, указанный в корне `config.xml` в теге ``. * Том (Volume) — упорядоченный набор равноценных дисков (схоже с [JBOD](https://ru.wikipedia.org/wiki/JBOD)) * Политика хранения (StoragePolicy) — множество томов с правилами перемещения данных между ними. -У всех описанных сущностей, при создании, указываются имена, которые будут отражены в системных таблицах `system.storage_policies` и `system.disks`. Имя политики хранения используется как настройка у таблиц семейства MergeTree. +У всех описанных сущностей, при создании, указываются имена, которые будут отражены в системных таблицах [system.storage_policies](../system_tables.md#system_tables-storage_policies) и [system.disks](../system_tables.md#system_tables-disks). Имя политики хранения используется как настройка у таблиц семейства MergeTree. -### Конфигурация +### Конфигурация {#table_engine-mergetree-multiple-volumes_configure} -Диски, тома и политики хранения задаются в конфигурации сервера. - -Конфигурация дисков имеет следующую структуру: +Диски, тома и политики хранения задаются в корне конфигурации (внутри тега ``) в основном файле `config.xml` или в отдельном файле в директории `config.d`. Правила составления данной секции конфигурации имеет следующую структуру: ```xml @@ -434,6 +432,9 @@ ALTER TABLE example_table ... ``` + +Где, + * имя диска задается внутри имени тега. * `path` — путь по которому будут храниться данные сервера (каталоги `data` и `shadow`), должен быть терминирован `/`. * `keep_free_space_bytes` — размер зарезервированного свободного места на диске. @@ -468,11 +469,15 @@ ALTER TABLE example_table ``` +Где, + * имя политики и тома задаются внутри имен тегов. * `disk` — диск, находящийся внутри тома. * `max_data_part_size_bytes` — максимальный размер куска, который может находится на любом из дисков этого тома. * `move_factor` — доля свободного места, при превышении которого данные начинают перемещаться на следующий том, если он есть (по умолчанию 0.1). +В приведенном примере, политика `hdd_in_order` реализует прицип [round-robin](https://ru.wikipedia.org/wiki/Round-robin_(%D0%B0%D0%BB%D0%B3%D0%BE%D1%80%D0%B8%D1%82%D0%BC)). Так как в политике есть всего 1 том (`single`) все записи производятся на его диски по круговому циклу. Такая политика может быть полезна при наличии в системе нескольких похожих дисков. Политика `moving_from_ssd_to_hdd` полезна при наличии в разных типов дисков. В томе `hot` находится один SSD-диск (`fast_ssd`), а также задается ограничение на максимальный размер куска, который может храниться на этом томе (1GB). Все куски такой таблицы больше 1GB будут записываться сразу на том `cold`, в котором содержится один HDD-диск `disk1`. Также, при заполнении диска `fast_ssd` более чем на 80% данные будут переносится на диск `disk1` фоновым процессом. + Порядок томов в политиках хранения важен, при достижении условий на переполнение тома данные переносятся на следующий. Порядок дисков в томах так же важен, данные пишутся по очереди на каждый из них. После задания конфигурации дисков и политик хранения их можно использовать, как настройку при создании таблиц: @@ -489,17 +494,16 @@ PARTITION BY toYYYYMM(EventDate) SETTINGS storage_policy_name='moving_from_ssd_to_hdd' ``` -Все куски такой таблицы больше 1GB будут писаться сразу на диск `disk1`. Также, при заполнении диска `fast_ssd` более чем на 80% данные будут переносится на диск `disk1` фоновым процессом. - -По умолчанию используется политика хранения `default` в которой есть один том и один диск, указанный в ``. +По умолчанию используется политика хранения `default` в которой есть один том и один диск, указанный в ``. В данный момент менять политику хранения после создания таблицы нельзя. ### Особенности работы В таблицах MergeTree данные попадают на диск несколькими способами: + * В результате вставки (запрос `INSERT`). -* В фоновых операциях слияний и мутаций. +* В фоновых операциях слияний и [мутаций](../../query_language/alter.md#alter-mutations). * При скачивании данных с другой реплики. -* В результате заморозки партиций [`ALTER TABLE ... FREEZE PARTITION`](../../query_language/alter.md#alter_freeze-partition). +* В результате заморозки партиций [ALTER TABLE ... FREEZE PARTITION](../../query_language/alter.md#alter_freeze-partition). Во всех случаях, кроме мутаций и заморозки партиций, при записи куска выбирается том и диск в соответствии с указанной конфигурацией хранилища: @@ -508,9 +512,9 @@ SETTINGS storage_policy_name='moving_from_ssd_to_hdd' Мутации и запросы заморозки партиций в реализации используют [жесткие ссылки](https://ru.wikipedia.org/wiki/%D0%96%D1%91%D1%81%D1%82%D0%BA%D0%B0%D1%8F_%D1%81%D1%81%D1%8B%D0%BB%D0%BA%D0%B0). Жесткие ссылки между различными дисками не поддерживаются, поэтому в случае таких операций куски размещаются на тех же дисках, что и исходные. -В фоне куски перемещаются между томами на основе информации о занятом месте (настройка `move_factor`) по порядку, в котором указаны тома в конфигурации. Данные никогда не перемещаются с последнего тома и на первый том. +В фоне куски перемещаются между томами на основе информации о занятом месте (настройка `move_factor`) по порядку, в котором указаны тома в конфигурации. Данные никогда не перемещаются с последнего тома и на первый том. Следить за фоновыми перемещениями можно с помощью системных таблиц [system.part_log](../system_tables.md#system_tables-part-log) (поле `type = MOVE_PART`) и [system.parts](../system_tables.md#system_tables-parts) (поля `path` и `disk`). Также подробная информация о перемещениях доступна в логах сервера. -С помощью запроса `ALTER TABLE ... MOVE PART|PARTITION ... TO VOLUME|DISK ...` пользователь может принудительно перенести кусок или партицию с одного раздела на другой. При этом учитываются все ограничения, указанные для фоновых операций. В случае недостатка места или неудовлетворения ограничениям пользователь получит сообщение об ошибки. +С помощью запроса [ALTER TABLE ... MOVE PART|PARTITION ... TO VOLUME|DISK ...](../../query_language/alter.md#alter_move-partition) пользователь может принудительно перенести кусок или партицию с одного раздела на другой. При этом учитываются все ограничения, указанные для фоновых операций. Запрос самостоятельно инициирует процесс перемещения не дожидаясь фоновых операций. В случае недостатка места или неудовлетворения ограничениям пользователь получит сообщение об ошибке. Перемещения данных не взаимодействуют с репликацией данных, поэтому на разных репликах одной и той же таблицы могут быть указаны разные политики хранения. diff --git a/docs/ru/query_language/alter.md b/docs/ru/query_language/alter.md index 690069fc7ce..21f19323d2d 100644 --- a/docs/ru/query_language/alter.md +++ b/docs/ru/query_language/alter.md @@ -310,7 +310,7 @@ ALTER TABLE table_name FREEZE [PARTITION partition_expr] - `/var/lib/clickhouse/` — рабочая директория ClickHouse, заданная в конфигурационном файле; - `N` — инкрементальный номер резервной копии. -!!! note +!!! note "Примечание" При использовании [нескольких дисков для хранения данных таблицы](../operations/table_engines/mergetree.md#table_engine-mergetree-multiple-volumes) директория `shadow/N` появляется на каждом из дисков, на которых были куски, попавшие под выражение `PARTITION`. Структура директорий внутри резервной копии такая же, как внутри `/var/lib/clickhouse/`. Запрос выполнит 'chmod' для всех файлов, запрещая запись в них.