---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://ydb.tech/docs/en/concepts/datamodel/backup-collection.md?version=main
  - https://ydb.tech/docs/ru/concepts/datamodel/backup-collection.md?version=main
sourcePath: en/core/concepts/datamodel/backup-collection.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt

# Backup collection

A backup collection organizes full and incremental backups of selected [row tables](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=main#row-oriented-tables) into manageable chains. It allows you to **restore data to the state of the latest backup in the chain**, providing protection against accidental data loss — erroneous deletions or modifications.

{% note info %}

For practical instructions on creating and managing backup collections, see the [Backup collections](https://ydb.tech/docs/en/devops/backup-and-recovery/index.md?version=main#backup-collections) section of the 'Backup and Restore' document.

{% endnote %}

## Overview

Backup collections solve typical backup tasks for production workloads:

- **Storage efficiency**: Incremental backups capture only changes since the previous backup, significantly reducing storage requirements compared to multiple full backups.
- **Consistent restore**: All tables in the collection are created from a single global snapshot, ensuring referential integrity between tables when restoring.
- **Chain restore**: Restore to the state of the **latest** backup in the current chain — see [`RESTORE`](https://ydb.tech/docs/en/yql/reference/syntax/restore-backup-collection.md?version=main).

For comparison with other backup methods (export/import, dump/restore), see [Backup concepts](https://ydb.tech/docs/en/concepts/backup.md?version=main).

## Key concepts

These terms are essential for understanding backup collections. For detailed definitions, see the [glossary](https://ydb.tech/docs/en/concepts/glossary.md?version=main#backup-collection).

- **[Full backup](https://ydb.tech/docs/en/concepts/glossary.md?version=main#backup)**: A complete snapshot of all data in the collection at a specific point in time. Serves as the basis for subsequent incremental backups.
- **[Incremental backup](https://ydb.tech/docs/en/concepts/glossary.md?version=main#backup)**: Captures only changes (inserts, updates, deletes) since the previous backup. Requires the entire backup chain for restoration.
- **[Backup chain](https://ydb.tech/docs/en/concepts/glossary.md?version=main#backup-chain)**: An ordered sequence starting with a full backup, followed by zero or more incremental backups.

## Limitations {#limitations}

Before using backup collections, consider these limitations:

- **Row tables only**: [Column tables](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=main#column-oriented-tables) are not supported.
- **One collection per table**: A table can belong to only one backup collection. To include a table in another collection, run [`DROP BACKUP COLLECTION`](https://ydb.tech/docs/en/yql/reference/syntax/drop-backup-collection.md?version=main) for the current collection and create a new one with the desired set of tables.
- **Immutable composition**: After creation, the list of tables in a collection cannot be changed. To add new tables, create a new collection with all the required tables.
- **No partial restore**: You cannot restore individual tables from a collection; the entire collection is restored.
- **External scheduling**: YDB does not provide built-in backup scheduling. Use external tools, such as cron, for automation.

## Architecture

Backup collections use a copy-on-write mechanism combined with [change streams](https://ydb.tech/docs/en/concepts/cdc.md?version=main) for efficient incremental backups. This section explains how the components work together.

### How backup collections work

The following diagram illustrates the backup process:


```mermaid
block-beta
    columns 5

    CREATE["Создание\nколлекции"]
    FULL["Полная\nкопия"]
    INC1["Инкрементальная\nкопия"]
    INC2["Инкрементальная\nкопия"]
    DROP["Удаление\nколлекции"]

    CREATE --> FULL
    FULL --> INC1
    INC1 --> INC2
    INC2 --> DROP

    style CREATE fill:#1976D2,color:#fff
    style FULL fill:#1565C0,color:#fff
    style INC1 fill:#42A5F5,color:#fff
    style INC2 fill:#64B5F6,color:#000
    style DROP fill:#E91E63,color:#fff
```


**Creating a collection** defines which tables to include and creates a schema object. This is a fast, metadata-only operation.

**Full backup** creates a consistent snapshot of all tables in the collection. Key characteristics:

- Uses a **global snapshot**, which ensures consistency across all tables in the collection.
- Creates **change streams** for each table to track subsequent modifications.
- Uses **copy-on-write**: The backup is created quickly by referencing existing data; actual data copying occurs only when the source data is modified.

**Incremental backup** captures all changes since the previous backup:

- Uses a **distributed transaction** to read change streams from all tables at a consistent point, ensuring referential integrity of the entire collection.
- Reads accumulated changes from change streams created during the full backup and accumulating changes **since the previous backup (full or incremental)**.
- Records all modifications: inserts, updates, and deletes (including as deletion records).
- Saves change stream data to incremental backup tables.

{% note warning %}

Schema changes (ALTER TABLE) of tables in the backup collection are not tracked by incremental backups. If you need to change the schema of a table with a backup, create a new full backup after the schema change so that the backup chain reflects the new structure.

{% endnote %}

{% note info %}

Change streams created during a full backup are automatically deleted when the backup collection is deleted. They cannot be manually deleted or used for other purposes while the collection exists.

{% endnote %}

### Storage

Backup collections are stored in the YDB cluster in a dedicated directory structure:


```text
/Root/database/.backups/collections/
├── my_collection/
│   ├── 20250821141425Z_full/
│   │   ├── table_1/
│   │   └── table_2/
│   └── 20250821151519Z_incremental/
│       ├── table_1/
│       └── table_2/
```


{% note info %}

The `.backups` directory is created automatically when the first backup collection is created and is managed by the system. After it is created, you can manage backup tables inside it (for example, when exporting or importing backups).

{% endnote %}

#### Cluster storage

By default, backups are stored in the cluster. Backups in the cluster are intended for recovery from **logical errors**, such as accidental `DROP TABLE`, `TRUNCATE TABLE`, or erroneous data changes. Advantages:

- Fast backup and restore operations.
- Integrated security mechanisms.
- No external infrastructure required.

{% note warning %}

Backups in the cluster are in the same failure zone as the protected data. If the cluster fails beyond its fault tolerance (for example, complete cluster loss or catastrophic events in the data center), both data and backups may be lost. To protect against such scenarios, use external storage.

{% endnote %}

#### External storage {#external-storage}

For **disaster recovery** and protection against failures of the entire cluster, regularly export backup collections to external storage (S3-compatible storage or file system) using [export/import operations](https://ydb.tech/docs/en/reference/ydb-cli/export-import/index.md?version=main).

To export backups to external storage, use the YDB CLI:

- [`ydb export s3`](https://ydb.tech/docs/en/reference/ydb-cli/export-import/export-s3.md?version=main) for S3-compatible storage.
- [`ydb export nfs`](https://ydb.tech/docs/en/reference/ydb-cli/export-import/export-nfs.md?version=main) for NFS on cluster hosts.
- [`ydb tools dump`](https://ydb.tech/docs/en/reference/ydb-cli/export-import/tools-dump.md?version=main) for file system on a local computer.

Each backup in the chain must be exported separately. Preserve the chain order during export/import for successful recovery.

### Background operations

All backup and restore operations are performed asynchronously, allowing you to continue normal database operations. Track progress using [`ydb operation list incbackup`](https://ydb.tech/docs/en/reference/ydb-cli/operation-list.md?version=main).

## Restore from backups

Restore returns data to the state of the latest backup in the chain that is in the cluster. To restore to an earlier state, import only the required chain prefix from external storage — see [Import and restore](https://ydb.tech/docs/en/recipes/backup-collections/importing-and-restoring.md?version=main).

### Restore process

1. **Import from external storage** (if necessary): If backups were exported, import the full backup and all incremental backups up to the desired restore point.
2. **Perform restore**: Run `RESTORE collection_name` to restore all tables from the backup collection. The system applies the full backup and all incremental backups sequentially to reach the latest backup point.

{% note warning %}

The restore operation will fail if at least one of the tables being restored already exists at the same path. Rename or delete conflicting tables before restoring.

{% endnote %}

All tables in the collection are restored to the same point in time: data from different tables will be mutually consistent.

{% note info %}

During the restore operation, the target tables are unavailable for modifications. Partially restored data may be visible to read workloads. Plan the restore for a maintenance window or disable application access to the affected tables until the operation completes.

{% endnote %}

## See also

- [Backup concepts](https://ydb.tech/docs/en/concepts/backup.md?version=main): Overview of all backup approaches in YDB
- [Backup and restore: backup collections](https://ydb.tech/docs/en/devops/backup-and-recovery/index.md?version=main#backup-collections): step-by-step scenarios and CLI commands
- [Recipes and examples](https://ydb.tech/docs/en/recipes/backup-collections/index.md?version=main): Typical scenarios and examples
- YQL reference:

  - [CREATE BACKUP COLLECTION](https://ydb.tech/docs/en/yql/reference/syntax/create-backup-collection.md?version=main)
  - [BACKUP](https://ydb.tech/docs/en/yql/reference/syntax/backup.md?version=main)
  - [RESTORE](https://ydb.tech/docs/en/yql/reference/syntax/restore-backup-collection.md?version=main)
  - [DROP BACKUP COLLECTION](https://ydb.tech/docs/en/yql/reference/syntax/drop-backup-collection.md?version=main)