Skip to main content
Skip to main content
Edit this page

Atomic

The Atomic engine supports non-blocking DROP TABLE and RENAME TABLE queries, and atomic EXCHANGE TABLES queries. The Atomic database engine is used by default.

Note

On ClickHouse Cloud, the Replicated database engine is used by default.

Creating a Database​

CREATE DATABASE test [ENGINE = Atomic];

Specifics and Recommendations​

Table UUID​

Each table in the Atomic database has a persistent UUID and stores its data in the following directory:

/clickhouse_path/store/xxx/xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy/

Where xxxyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy is the UUID of the table.

By default, the UUID is generated automatically. However, users can explicitly specify the UUID when creating a table, though this is not recommended.

For example:

CREATE TABLE name UUID '28f1c61c-2970-457a-bffe-454156ddcfef' (n UInt64) ENGINE = ...;
Note

You can use the show_table_uuid_in_table_create_query_if_not_nil setting to display the UUID with the SHOW CREATE query.

RENAME TABLE​

RENAME queries do not modify the UUID or move table data. These queries execute immediately and do not wait for other queries that are using the table to complete.

DROP/DETACH TABLE​

When using DROP TABLE, no data is removed. The Atomic engine just marks the table as dropped by moving it's metadata to /clickhouse_path/metadata_dropped/ and notifies the background thread. The delay before the final table data deletion is specified by the 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 setting to do this. In this case DROP waits for running SELECT, INSERT and other queries which are using the table to finish. The table will be removed when it's not in use.

EXCHANGE TABLES/DICTIONARIES​

The EXCHANGE query swaps tables or dictionaries atomically. For instance, instead of this non-atomic operation:

Non-atomic
RENAME TABLE new_table TO tmp, old_table TO new_table, tmp TO old_table;

you can use an atomic one:

Atomic
EXCHANGE TABLES new_table AND old_table;

ReplicatedMergeTree in Atomic Database​

For ReplicatedMergeTree tables, it is recommended not to specify the engine parameters for the path in ZooKeeper and the replica name. In this case, the configuration parameters default_replica_path and default_replica_name will be used. If you want to specify engine parameters explicitly, it is recommended to use the {uuid} macros. This ensures that unique paths are automatically generated for each table in ZooKeeper.

See Also​