Merge pull request #21950 from adevyatova/annadevyatova-DOCSUP-6113-atomic

DOCSUP-6113: Document the Atomic database engine

docs/en/engines/database-engines/atomic.md

@@ -3,15 +3,52 @@ toc_priority: 32
 toc_title: Atomic
 ---
 
-
 # Atomic {#atomic}
 
-It supports non-blocking `DROP` and `RENAME TABLE` queries and atomic `EXCHANGE TABLES t1 AND t2` queries. `Atomic` database engine is used by default.
+It supports non-blocking [DROP TABLE](#drop-detach-table) and [RENAME TABLE](#rename-table) queries and atomic [EXCHANGE TABLES t1 AND t2](#exchange-tables) queries. `Atomic` database engine is used by default.
 
 ## Creating a Database {#creating-a-database}
 
+``` sql
+    CREATE DATABASE test[ ENGINE = Atomic];
+```
+
+## Specifics and recommendations {#specifics-and-recommendations}
+
+### Table UUID {#table-uuid}
+
+All tables in database `Atomic` have persistent [UUID](../../sql-reference/data-types/uuid.md) and store data in directory `/clickhouse_path/store/xxx/xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/`, where `xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy` is UUID of the table. 
+Usually, the UUID is generated automatically, but the user can also explicitly specify the UUID in the same way when creating the table (this is not recommended). To display the `SHOW CREATE` query with the UUID you can use setting [show_table_uuid_in_table_create_query_if_not_nil](../../operations/settings/settings.md#show_table_uuid_in_table_create_query_if_not_nil). For example:
+
 ```sql
-CREATE DATABASE test ENGINE = Atomic;
+CREATE TABLE name UUID '28f1c61c-2970-457a-bffe-454156ddcfef' (n UInt64) ENGINE = ...;
 ```
+### RENAME TABLE {#rename-table}
+
+`RENAME` queries are performed without changing UUID and moving table data. These queries do not wait for the completion of queries using the table and will be executed instantly.
+
+### DROP/DETACH TABLE {#drop-detach-table}
+
+On `DROP TABLE` no data is removed, database `Atomic` just marks table as dropped by moving metadata to `/clickhouse_path/metadata_dropped/` and notifies background thread. Delay before final table data deletion is specify by [database_atomic_delay_before_drop_table_sec](../../operations/server-configuration-parameters/settings.md#database_atomic_delay_before_drop_table_sec) setting.
+You can specify synchronous mode using `SYNC` modifier. Use the [database_atomic_wait_for_drop_and_detach_synchronously](../../operations/settings/settings.md#database_atomic_wait_for_drop_and_detach_synchronously) setting to do this. In this case `DROP` waits for running `SELECT`, `INSERT` and other queries which are using the table to finish. Table will be actually removed when it's not in use.
+
+### EXCHANGE TABLES {#exchange-tables}
+
+`EXCHANGE` query swaps tables atomically. So instead of this non-atomic operation:
+
+```sql
+RENAME TABLE new_table TO tmp, old_table TO new_table, tmp TO old_table;
+```
+you can use one atomic query:
+
+``` sql
+EXCHANGE TABLES new_table AND old_table;
+```
+
+### ReplicatedMergeTree in Atomic Database {#replicatedmergetree-in-atomic-database}
+
+For [ReplicatedMergeTree](../table-engines/mergetree-family/replication.md#table_engines-replication) tables is recomended do not specify parameters of engine - path in ZooKeeper and replica name. In this case will be used parameters of the configuration [default_replica_path](../../operations/server-configuration-parameters/settings.md#default_replica_path) and [default_replica_name](../../operations/server-configuration-parameters/settings.md#default_replica_name). If you want specify parameters of engine explicitly than recomended to use {uuid} macros. This is useful so that unique paths are automatically generated for each table in the ZooKeeper.
+
+## See Also
 
-[Original article](https://clickhouse.tech/docs/en/engines/database-engines/atomic/) <!--hide-->
+-   [system.databases](../../operations/system-tables/databases.md) system table

docs/en/operations/server-configuration-parameters/settings.md

@@ -100,6 +100,11 @@ Default value: `1073741824` (1 GB).
     <size_limit>1073741824</size_limit>
 </core_dump> 
 ```
+## database_atomic_delay_before_drop_table_sec {#database_atomic_delay_before_drop_table_sec}
+
+Sets the delay before remove table data in seconds. If the query has `SYNC` modifier, this setting is ignored.
+
+Default value: `480` (8 minute).
 
 ## default_database {#default-database}
 
@@ -125,6 +130,25 @@ Settings profiles are located in the file specified in the parameter `user_confi
 <default_profile>default</default_profile>
 ```
 
+## default_replica_path {#default_replica_path}
+
+The path to the table in ZooKeeper.
+
+**Example**
+
+``` xml
+<default_replica_path>/clickhouse/tables/{uuid}/{shard}</default_replica_path>
+```
+## default_replica_name {#default_replica_name}
+
+ The replica name in ZooKeeper.
+
+**Example**
+
+``` xml
+<default_replica_name>{replica}</default_replica_name>
+```
+
 ## dictionaries_config {#server_configuration_parameters-dictionaries_config}
 
 The path to the config file for external dictionaries.

docs/en/operations/settings/settings.md

@@ -2787,6 +2787,28 @@ Possible values:
 
 Default value: `0`.
 
+## database_atomic_wait_for_drop_and_detach_synchronously {#database_atomic_wait_for_drop_and_detach_synchronously}
+
+Adds a modifier `SYNC` to all `DROP` and `DETACH` queries. 
+
+Possible values:
+
+-   0 — Queries will be executed with delay.
+-   1 — Queries will be executed without delay.
+
+Default value: `0`.
+
+## show_table_uuid_in_table_create_query_if_not_nil {#show_table_uuid_in_table_create_query_if_not_nil}
+
+Sets the `SHOW TABLE` query display.
+
+Possible values:
+
+-   0 — The query will be displayed without table UUID.
+-   1 — The query will be displayed with table UUID.
+
+Default value: `0`.
+
 ## allow_experimental_live_view {#allow-experimental-live-view}
 
 Allows creation of experimental [live views](../../sql-reference/statements/create/view.md#live-view).

docs/en/sql-reference/statements/create/table.md

@@ -287,7 +287,9 @@ REPLACE TABLE myOldTable SELECT * FROM myOldTable WHERE CounterID <12345;
 
 ### Syntax
 
-{CREATE [OR REPLACE]|REPLACE} TABLE [db.]table_name
+``` sql
+{CREATE [OR REPLACE] | REPLACE} TABLE [db.]table_name
+```
 
 All syntax forms for `CREATE` query also work for this query. `REPLACE` for a non-existent table will cause an error.
 

docs/ru/development/developer-instruction.md

@@ -7,15 +7,15 @@ toc_title: "Инструкция для разработчиков"
 
 Сборка ClickHouse поддерживается на Linux, FreeBSD, Mac OS X.
 
-# Если вы используете Windows {#esli-vy-ispolzuete-windows}
+## Если вы используете Windows {#esli-vy-ispolzuete-windows}
 
 Если вы используете Windows, вам потребуется создать виртуальную машину с Ubuntu. Для работы с виртуальной машиной, установите VirtualBox. Скачать Ubuntu можно на сайте: https://www.ubuntu.com/#download Создайте виртуальную машину из полученного образа. Выделите для неё не менее 4 GB оперативной памяти. Для запуска терминала в Ubuntu, найдите в меню программу со словом terminal (gnome-terminal, konsole или что-то в этом роде) или нажмите Ctrl+Alt+T.
 
-# Если вы используете 32-битную систему {#esli-vy-ispolzuete-32-bitnuiu-sistemu}
+## Если вы используете 32-битную систему {#esli-vy-ispolzuete-32-bitnuiu-sistemu}
 
 ClickHouse не работает и не собирается на 32-битных системах. Получите доступ к 64-битной системе и продолжайте.
 
-# Создание репозитория на GitHub {#sozdanie-repozitoriia-na-github}
+## Создание репозитория на GitHub {#sozdanie-repozitoriia-na-github}
 
 Для работы с репозиторием ClickHouse, вам потребуется аккаунт на GitHub. Наверное, он у вас уже есть.
 
@@ -34,7 +34,7 @@ ClickHouse не работает и не собирается на 32-битны
 
 Подробное руководство по использованию Git: https://git-scm.com/book/ru/v2
 
-# Клонирование репозитория на рабочую машину {#klonirovanie-repozitoriia-na-rabochuiu-mashinu}
+## Клонирование репозитория на рабочую машину {#klonirovanie-repozitoriia-na-rabochuiu-mashinu}
 
 Затем вам потребуется загрузить исходники для работы на свой компьютер. Это называется «клонирование репозитория», потому что создаёт на вашем компьютере локальную копию репозитория, с которой вы будете работать.
 
@@ -78,7 +78,7 @@ ClickHouse не работает и не собирается на 32-битны
 
 После этого, вы сможете добавлять в свой репозиторий обновления из репозитория Яндекса с помощью команды `git pull upstream master`.
 
-## Работа с сабмодулями Git {#rabota-s-sabmoduliami-git}
+### Работа с сабмодулями Git {#rabota-s-sabmoduliami-git}
 
 Работа с сабмодулями git может быть достаточно болезненной. Следующие команды позволят содержать их в порядке:
 
@@ -110,7 +110,7 @@ The next commands would help you to reset all submodules to the initial state (!
     git submodule foreach git submodule foreach git reset --hard
     git submodule foreach git submodule foreach git clean -xfd
 
-# Система сборки {#sistema-sborki}
+## Система сборки {#sistema-sborki}
 
 ClickHouse использует систему сборки CMake и Ninja.
 
@@ -130,11 +130,11 @@ Ninja - система запуска сборочных задач.
 
 Проверьте версию CMake: `cmake --version`. Если версия меньше 3.3, то установите новую версию с сайта https://cmake.org/download/
 
-# Необязательные внешние библиотеки {#neobiazatelnye-vneshnie-biblioteki}
+## Необязательные внешние библиотеки {#neobiazatelnye-vneshnie-biblioteki}
 
 ClickHouse использует для сборки некоторое количество внешних библиотек. Но ни одну из них не требуется отдельно устанавливать, так как они собираются вместе с ClickHouse, из исходников, которые расположены в submodules. Посмотреть набор этих библиотек можно в директории contrib.
 
-# Компилятор C++ {#kompiliator-c}
+## Компилятор C++ {#kompiliator-c}
 
 В качестве компилятора C++ поддерживается GCC начиная с версии 9 или Clang начиная с версии 8.
 
@@ -148,7 +148,7 @@ ClickHouse использует для сборки некоторое коли
 
 Если вы решили использовать Clang, вы также можете установить `libc++` и `lld`, если вы знаете, что это такое. При желании, установите `ccache`.
 
-# Процесс сборки {#protsess-sborki}
+## Процесс сборки {#protsess-sborki}
 
 Теперь вы готовы к сборке ClickHouse. Для размещения собранных файлов, рекомендуется создать отдельную директорию build внутри директории ClickHouse:
 
@@ -206,7 +206,7 @@ Mac OS X:
 
     ls -l programs/clickhouse
 
-# Запуск собранной версии ClickHouse {#zapusk-sobrannoi-versii-clickhouse}
+## Запуск собранной версии ClickHouse {#zapusk-sobrannoi-versii-clickhouse}
 
 Для запуска сервера из под текущего пользователя, с выводом логов в терминал и с использованием примеров конфигурационных файлов, расположенных в исходниках, перейдите в директорию `ClickHouse/programs/server/` (эта директория находится не в директории build) и выполните:
 
@@ -233,7 +233,7 @@ Mac OS X:
     sudo service clickhouse-server stop
     sudo -u clickhouse ClickHouse/build/programs/clickhouse server --config-file /etc/clickhouse-server/config.xml
 
-# Среда разработки {#sreda-razrabotki}
+## Среда разработки {#sreda-razrabotki}
 
 Если вы не знаете, какую среду разработки использовать, то рекомендуется использовать CLion. CLion является платным ПО, но его можно использовать бесплатно в течение пробного периода. Также он бесплатен для учащихся. CLion можно использовать как под Linux, так и под Mac OS X.
 
@@ -243,7 +243,7 @@ Mac OS X:
 
 На всякий случай заметим, что CLion самостоятельно создаёт свою build директорию, самостоятельно выбирает тип сборки debug по-умолчанию, для конфигурации использует встроенную в CLion версию CMake вместо установленного вами, а для запуска задач использует make вместо ninja. Это нормально, просто имейте это ввиду, чтобы не возникало путаницы.
 
-# Написание кода {#napisanie-koda}
+## Написание кода {#napisanie-koda}
 
 Описание архитектуры ClickHouse: https://clickhouse.tech/docs/ru/development/architecture/
 
@@ -253,7 +253,7 @@ Mac OS X:
 
 Список задач: https://github.com/ClickHouse/ClickHouse/issues?q=is%3Aopen+is%3Aissue+label%3A%22easy+task%22
 
-# Тестовые данные {#testovye-dannye}
+## Тестовые данные {#testovye-dannye}
 
 Разработка ClickHouse часто требует загрузки реалистичных наборов данных. Особенно это важно для тестирования производительности. Специально для вас мы подготовили набор данных, представляющий собой анонимизированные данные Яндекс.Метрики. Загрузка этих данных потребует ещё 3 GB места на диске. Для выполнения большинства задач разработки, загружать эти данные не обязательно.
 
@@ -274,7 +274,7 @@ Mac OS X:
     clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.hits FORMAT TSV" < hits_v1.tsv
     clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.visits FORMAT TSV" < visits_v1.tsv
 
-# Создание Pull Request {#sozdanie-pull-request}
+## Создание Pull Request {#sozdanie-pull-request}
 
 Откройте свой форк репозитория в интерфейсе GitHub. Если вы вели разработку в бранче, выберите этот бранч. На странице будет доступна кнопка «Pull request». По сути, это означает «создать заявку на принятие моих изменений в основной репозиторий».
 

docs/ru/engines/database-engines/atomic.md

@@ -3,15 +3,52 @@ toc_priority: 32
 toc_title: Atomic
 ---
 
-
 # Atomic {#atomic}
 
-Поддерживает неблокирующие запросы `DROP` и `RENAME TABLE` и запросы `EXCHANGE TABLES t1 AND t2`. Движок `Atomic` используется по умолчанию.
+Поддерживает неблокирующие запросы [DROP TABLE](#drop-detach-table) и [RENAME TABLE](#rename-table) и атомарные запросы [EXCHANGE TABLES t1 AND t](#exchange-tables). Движок `Atomic` используется по умолчанию.
 
 ## Создание БД {#creating-a-database}
 
+``` sql
+    CREATE DATABASE test[ ENGINE = Atomic];
+```
+
+## Особенности и рекомендации {#specifics-and-recommendations}
+
+### UUID {#table-uuid}
+
+Каждая таблица в базе данных `Atomic` имеет уникальный [UUID](../../sql-reference/data-types/uuid.md) и хранит данные в папке `/clickhouse_path/store/xxx/xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/`, где `xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy` - это UUID таблицы.
+Обычно UUID генерируется автоматически, но пользователь также может явно указать UUID в момент создания таблицы (однако это не рекомендуется). Для отображения UUID в запросе `SHOW CREATE` вы можете использовать настройку [show_table_uuid_in_table_create_query_if_not_nil](../../operations/settings/settings.md#show_table_uuid_in_table_create_query_if_not_nil). Результат выполнения в таком случае будет иметь вид:
+
 ```sql
-CREATE DATABASE test ENGINE = Atomic;
+CREATE TABLE name UUID '28f1c61c-2970-457a-bffe-454156ddcfef' (n UInt64) ENGINE = ...;
 ```
+### RENAME TABLE {#rename-table}
+
+Запросы `RENAME` выполняются без изменения UUID и перемещения табличных данных. Эти запросы не ожидают завершения использующих таблицу запросов и будут выполнены мгновенно. 
+
+### DROP/DETACH TABLE {#drop-detach-table}
+
+При выполнении запроса `DROP TABLE` никакие данные не удаляются. Таблица помечается как удаленная, метаданные перемещаются в папку `/clickhouse_path/metadata_dropped/` и база данных уведомляет фоновый поток. Задержка перед окончательным удалением данных задается настройкой [database_atomic_delay_before_drop_table_sec](../../operations/server-configuration-parameters/settings.md#database_atomic_delay_before_drop_table_sec).
+Вы можете задать синхронный режим, определяя модификатор `SYNC`. Используйте для этого настройку [database_atomic_wait_for_drop_and_detach_synchronously](../../operations/settings/settings.md#database_atomic_wait_for_drop_and_detach_synchronously). В этом случае запрос `DROP` ждет завершения `SELECT`, `INSERT` и других запросов, которые используют таблицу. Таблица будет фактически удалена, когда она не будет использоваться.
+
+### EXCHANGE TABLES {#exchange-tables}
+
+Запрос `EXCHANGE` меняет местами две таблицы атомарно. Вместо неатомарной операции:
+
+```sql
+RENAME TABLE new_table TO tmp, old_table TO new_table, tmp TO old_table;
+```
+вы можете использовать один атомарный запрос:
+
+``` sql
+EXCHANGE TABLES new_table AND old_table;
+```
+
+### ReplicatedMergeTree in Atomic Database {#replicatedmergetree-in-atomic-database}
+
+Для таблиц [ReplicatedMergeTree](../table-engines/mergetree-family/replication.md#table_engines-replication) рекомендуется не указывать параметры движка - путь в ZooKeeper и имя реплики. В этом случае будут использоваться параметры конфигурации: [default_replica_path](../../operations/server-configuration-parameters/settings.md#default_replica_path) и [default_replica_name](../../operations/server-configuration-parameters/settings.md#default_replica_name). Если вы хотите определить параметры движка явно, рекомендуется использовать макрос {uuid}. Это удобно, так как автоматически генерируются уникальные пути для каждой таблицы в ZooKeeper.
+
+## Смотрите также
 
-[Оригинальная статья](https://clickhouse.tech/docs/ru/engines/database-engines/atomic/) <!--hide-->
+-   Системная таблица [system.databases](../../operations/system-tables/databases.md).

docs/ru/operations/server-configuration-parameters/settings.md

@@ -101,6 +101,12 @@ ClickHouse проверяет условия для `min_part_size` и `min_part
 </core_dump> 
 ```
 
+## database_atomic_delay_before_drop_table_sec {#database_atomic_delay_before_drop_table_sec}
+
+Устанавливает задержку перед удалением табличных данных, в секундах. Если запрос имеет идентификатор `SYNC`, эта настройка игнорируется.
+
+Значение по умолчанию: `480` (8 минут).
+
 ## default\_database {#default-database}
 
 База данных по умолчанию.

docs/ru/operations/settings/settings.md

@@ -2690,6 +2690,28 @@ SELECT * FROM test2;
 
 Значение по умолчанию: `0`.
 
+## database_atomic_wait_for_drop_and_detach_synchronously {#database_atomic_wait_for_drop_and_detach_synchronously}
+
+Добавляет модификатор `SYNC` ко всем запросам `DROP` и `DETACH`. 
+
+Возможные значения:
+
+-   0 — Запросы будут выполняться с задержкой.
+-   1 — Запросы будут выполняться без задержки.
+
+Значение по умолчанию: `0`.
+
+## show_table_uuid_in_table_create_query_if_not_nil {#show_table_uuid_in_table_create_query_if_not_nil}
+
+Устанавливает отображение запроса `SHOW TABLE`.
+
+Возможные значения:
+
+-   0 — Запрос будет отображаться без UUID таблицы.
+-   1 — Запрос будет отображаться с UUID таблицы.
+
+Значение по умолчанию: `0`.
+
 ## allow_experimental_live_view {#allow-experimental-live-view}
 
 Включает экспериментальную возможность использования [LIVE-представлений](../../sql-reference/statements/create/view.md#live-view).