system.backups

Description

Contains a list of all BACKUP or RESTORE operations with their current states and other properties. Note, that table is not persistent and it shows only operations executed after the last server restart.

Columns

• id (String) — Operation ID, can be either passed via SETTINGS id=... or be randomly generated UUID.
• name (String) — Operation name, a string like Disk('backups', 'my_backup')
• base_backup_name (String) — Base Backup Operation name, a string like Disk('backups', 'my_base_backup')
• query_id (String) — Query ID of a query that started backup.
• status (Enum8('CREATING_BACKUP' = 0, 'BACKUP_CREATED' = 1, 'BACKUP_FAILED' = 2, 'RESTORING' = 3, 'RESTORED' = 4, 'RESTORE_FAILED' = 5, 'BACKUP_CANCELLED' = 6, 'RESTORE_CANCELLED' = 7)) — Status of backup or restore operation.
• error (String) — The error message if any.
• start_time (DateTime64(6)) — The time when operation started.
• end_time (DateTime64(6)) — The time when operation finished.
• num_files (UInt64) — The number of files stored in the backup.
• total_size (UInt64) — The total size of files stored in the backup.
• num_entries (UInt64) — The number of entries in the backup, i.e. the number of files inside the folder if the backup is stored as a folder.
• uncompressed_size (UInt64) — The uncompressed size of the backup.
• compressed_size (UInt64) — The compressed size of the backup.
• files_read (UInt64) — Returns the number of files read during RESTORE from this backup.
• bytes_read (UInt64) — Returns the total size of files read during RESTORE from this backup.
• ProfileEvents (Map(LowCardinality(String), UInt64)) — All the profile events captured during this operation.

Restore atomicity

RESTORE is not transactional and does not roll back on failure. For each table, all selected parts are copied before any are attached, but the attach phase itself is not transactional — parts are made visible one at a time. Tables are processed independently.

Tables are independent. A table whose restore completes stays in place even if another table in the same command later fails:

RESTORE TABLE db.t0, TABLE db.t1
FROM S3('<endpoint>', '<access_key>', '<secret_key>')
SETTINGS
    allow_non_empty_tables = true;

If this command fails after db.t0 has been fully restored but db.t1 has not finished, db.t0 remains restored.

The PARTITIONS clause is not a commit boundary. It only selects which parts of a table are restored:

RESTORE TABLE db.t0 PARTITIONS '2026-06-01', '2026-06-02', '2026-06-03'
FROM S3('<endpoint>', '<access_key>', '<secret_key>')
SETTINGS
    allow_non_empty_tables = true;

All selected parts of the table are copied first and attached only once every one of them is ready. So if this command fails during the copy phase — e.g. after partition 2026-06-01 has been fully copied but 2026-06-02 and 2026-06-03 have not finished — then 2026-06-01 is not committed and the table is left with no restored data from this command. Once the copy phase completes and the attach step begins, parts are committed one at a time, so a failure during attach can leave the table partially restored, without rollback.

To commit partitions independently (so a completed partition survives a later failure and can be retried in isolation), run a separate RESTORE per partition, using SETTINGS allow_non_empty_tables = true after the first.