> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kinetica.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CREATE BACKUP

Creates a new *full*, *incremental*, or *differential snapshot* of the given
database objects and data; storing the backup files at the location accessible
through the given [data sink](https://docs.kinetica.com/content/sql/ddl/create-data-sink.md#sql-create-data-sink).

```sql Full Backup Syntax theme={null}
CREATE BACKUP <backup name>
DATA SINK = <data sink name>
[OBJECTS (<object type> = <object name>[,...])]
[WITH OPTIONS (<backup option name> = '<backup option value>'[,...])]
```

```sql Incremental Backup Syntax theme={null}
BACKUP <backup name>
DATA SINK = <data sink name>
[WITH OPTIONS (<backup option name> = '<backup option value>'[,...])]
```

```sql Differential Backup Syntax theme={null}
BACKUP <backup name>
TYPE = 'differential'
DATA SINK = <data sink name>
[WITH OPTIONS (<backup option name> = '<backup option value>'[,...])]
```

## Parameters

> [accordion] CREATE
>
> Keyword indicating a *backup* should be created with an initial *full snapshot*.  If omitted, an
> *incremental snapshot* will be created, using the most recent *full* or *incremental snapshot*
> as the baseline.

> [accordion] \<backup name>
>
> Name of the *backup* to create.

> [accordion] \<data sink name>
>
> Name of the [data sink](https://docs.kinetica.com/content/sql/ddl/create-data-sink.md#sql-create-data-sink) to use to send the database *backup*
> files to the remote file store.

> [accordion] TYPE
>
> Type of *snapshot* to create.
>
> *Snapshot* type designations include:
>
> <table>
>   <thead>
>     <tr>
>       <th>Snapshot Type</th>
>       <th>Description</th>
>     </tr>
>   </thead>
>
>   <tbody>
>     <tr>
>       <td>`full`</td>
>       <td>Create a *full snapshot* of the specified database objects.  This is the default when `CREATE` is specified.</td>
>     </tr>
>
>     <tr>
>       <td>`incremental`</td>
>       <td>Create a *snapshot* of the changes to the specified database objects since the most recent *snapshot* of any kind was created. This is the default when `CREATE` is omitted.</td>
>     </tr>
>
>     <tr>
>       <td>`differential`</td>
>       <td>Create a *snapshot* of the changes to the specified database objects since the most recent *full snapshot* was created.</td>
>     </tr>
>   </tbody>
> </table>

> [accordion] OBJECTS
>
> List of key/value pairs, each being an `object type` and an `object name` of that type, to
> back up.
>
> > [!NOTE]
> >
> > The `OBJECTS` clause should only be specified for *full snapshots*.  Both
> > *incremental* & *differential snapshots* will operate on the objects specified
> > during the original *full snapshot* associated with the `backup name`
> > specified for them.
>
> `object type` designations include:
>
> <table>
>   <thead>
>     <tr>
>       <th>Object Type</th>
>       <th>Description</th>
>     </tr>
>   </thead>
>
>   <tbody>
>     <tr>
>       <td>`ALL`</td>
>       <td>[Schema](https://docs.kinetica.com/content/sql/ddl/create-schema.md#sql-create-schema), and all the objects & data it contains</td>
>     </tr>
>
>     <tr>
>       <td>`CONTEXT`</td>
>       <td>[SQL-GPT context](https://docs.kinetica.com/content/sql/sqlgpt/create-context.md#sql-gpt-create-context)</td>
>     </tr>
>
>     <tr>
>       <td>`CREDENTIAL`</td>
>       <td>[Credential](https://docs.kinetica.com/content/sql/ddl/create-credential.md#sql-create-credential)</td>
>     </tr>
>
>     <tr>
>       <td>`DATA SINK`</td>
>       <td>[Data sink](https://docs.kinetica.com/content/sql/ddl/create-data-sink.md#sql-create-data-sink)</td>
>     </tr>
>
>     <tr>
>       <td>`DATA SOURCE`</td>
>       <td>[Data source](https://docs.kinetica.com/content/sql/ddl/create-data-source.md#sql-create-data-source)</td>
>     </tr>
>
>     <tr>
>       <td>`DIRECTORY`</td>
>       <td>[KiFS directory](https://docs.kinetica.com/content/sql/kifs.md)</td>
>     </tr>
>
>     <tr>
>       <td>`FUNCTION`</td>
>       <td>[UDF](https://docs.kinetica.com/content/sql/udf/create-function.md#sql-create-function)</td>
>     </tr>
>
>     <tr>
>       <td>`FUNCTION ENVIRONMENT`</td>
>       <td>[UDF environment](https://docs.kinetica.com/content/sql/udf/create-function-environment.md#sql-create-function-environment)</td>
>     </tr>
>
>     <tr>
>       <td>`GRAPH`</td>
>       <td>[Graph](https://docs.kinetica.com/content/sql/graph.md).  Source tables, if applicable, are required in order to restore it.</td>
>     </tr>
>
>     <tr>
>       <td>`PROCEDURE`</td>
>       <td>[SQL procedure](https://docs.kinetica.com/content/sql/procedure.md#sql-procedures)</td>
>     </tr>
>
>     <tr>
>       <td>`RESOURCE GROUP`</td>
>       <td>[Resource group](https://docs.kinetica.com/content/sql/resource_group/create-resource-group.md#sql-rg-create)</td>
>     </tr>
>
>     <tr>
>       <td>`ROLE`</td>
>       <td>[User role](https://docs.kinetica.com/content/sql/security/create-role.md#sql-security-role-mgmt)</td>
>     </tr>
>
>     <tr>
>       <td>`STREAM`</td>
>       <td>[Stream](https://docs.kinetica.com/content/sql/ddl/create-stream.md#sql-create-stream)</td>
>     </tr>
>
>     <tr>
>       <td>`TABLE`</td>
>       <td>[Table](https://docs.kinetica.com/content/sql/ddl/create-table.md#sql-create-table) or [view](https://docs.kinetica.com/content/sql/ddl/create-view.md#sql-create-view)</td>
>     </tr>
>
>     <tr>
>       <td>`USER`</td>
>       <td>[User](https://docs.kinetica.com/content/sql/security/create-user.md#sql-security-user-mgmt)</td>
>     </tr>
>   </tbody>
> </table>

> [accordion] WITH OPTIONS
>
> Optional indicator that a comma-delimited list of *backup* option name/value assignments will
> follow.
>
> See [Options](https://docs.kinetica.com/content/sql/backup_restore/create-backup.md#sql-backup-create-opt) for the complete list of options.

## Options

The following options can be specified to further modify a *backup*
configuration.

> [accordion] BLOCK\_TABLE\_MUTATIONS
>
> Block all data mutations on the tables being backed up, for the duration of the back up.  Blocked
> mutations are rejected with an error; they are not queued.  The default (`false`) is to allow
> mutations, blocking them on a given table only at the point a disk eviction of that table's data
> is necessary.
>
> > [!NOTE]
> >
> > Alterations to the type or attributes of a table are blocked for the duration of any
> > back up, whether or not this option is used; this option governs data mutations
> > specifically.

> [accordion] CHECKSUM
>
> Calculate and store a checksum of all backed-up objects.  The default (`false`) is to not create
> checksums.

> [accordion] COMMENT
>
> Comment to associate with the *snapshot*.

> [accordion] DDL\_ONLY
>
> For any table, only back up its DDL; don't back up its data.  The default (`false`) is to back
> up data and DDL.
>
> > [!NOTE]
> >
> > In this mode, subsequent *incremental* & *differential snapshot* attempts will return a
> > warning and create no additional *snapshot* if only data has changed since the last *snapshot*.

> [accordion] DELETE\_INTERMEDIATE\_BACKUPS
>
> For *differential snapshot* types only, delete all prior intermediate *differential* &
> *incremental snapshots* between the last *full snapshot* and this one for the given
> `backup name`.  The default (`false`) is to not delete intermediate *snapshots*.

> [accordion] DRY\_RUN
>
> Execute a dry run of a back up without actually backing up any files.  The default (`false`) is
> to not do a dry run.

> [accordion] MAX\_INCREMENTAL\_BACKUPS\_TO\_KEEP
>
> Maximum number of *incremental snapshots* to keep for the given `backup name`; if creating this
> *incremental snapshot* will cause the total number to exceed this maximum, the oldest
> *incremental snapshot* will be removed.  The default is unlimited.

> [accordion] RECREATE
>
> For *full snapshot* types only, replace the existing *backup* with a new *backup*, if it exists.
> The default (`false`) is to not replace the existing *backup* and return an error, if one
> exists.

## Examples

For example, to create a *backup* named `schema_backup` with a *full snapshot*
of schema `example_backup`, copying backup files to a target via *data source*
`backup_ds`:

```sql CREATE BACKUP (Full Snapshot) Example theme={null}
CREATE BACKUP schema_backup
DATA SINK = backup_ds
OBJECTS (ALL = example_backup)
```

To create an *incremental snapshot* based on the previous *snapshot* of the
*backup* with the same name:

```sql CREATE BACKUP (Incremental Snapshot) Example theme={null}
BACKUP schema_backup
DATA SINK = backup_ds
```

To create a *differential snapshot* based on the previous *full snapshot* of the
*backup* with the same name:

```sql CREATE BACKUP (Differential Snapshot) Example theme={null}
BACKUP schema_backup
TYPE = 'differential'
DATA SINK = backup_ds
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.