FORCE RESTORE

Forces the restoration of a specific backup even if that backup is incomplete. Requires a target keyspace or a list of target tables within that keyspace, and a backup store name. Custom backup store settings can be specified as can a new keyspace for restored data. Returns a UUID for the restore operation.

After a FORCE RESTORE, you must run a nodetool repair or schedule a manual nodesync on the node. See:

Synopsis

RESTORE <targets>
    FROM BACKUP <backup_id>
    FROM STORE <store_name>
    [ WITH settings=<settings> ]
    [ INTO <keyspace_name_new> ] ;

Syntax legend

Syntax conventions Description

Syntax conventions	Description
UPPERCASE	Literal keyword, unless bold. If bold, it is a variable. For example, `DESCRIBE KEYSPACE KEYSPACE_NAME;` includes the CQL keywords `DESCRIBE KEYSPACE` and the variable `KEYSPACE_NAME`. If you ran this command, you would replace `KEYSPACE_NAME` with the name of the keyspace you want to describe, such as `DESCRIBE KEYSPACE customers;`.
Lowercase	Not literal
`< >` or bold	Often represents a variable placeholder that you must replace with a user-defined value. However, angle brackets are also required to surround data types in a set, list, map, or tuple.
`[]`	Optional command arguments. Do not type the square brackets.
`( )`	A group of options you can choose from. Do not type the parentheses.
`\|`	Separates alternative elements when you can choose one of several elements. Type any one of the elements. Do not type the vertical bar.
`...`	A repeatable syntax element. Can be reused as often as required.
`'`	Single quotation marks must surround literal strings in CQL statements, such as `'example_string'`. Use single quotation marks to preserve upper case. Additionally, single quotation marks are used in Search CQL to surround an entire XML schema declaration. For example: `' <schema> ... </schema> '`
`{ <key> : <value> }`	Curly braces enclose map collections or key value pairs. A colon separates the key and the value.
`<datatype2`	Angle brackets enclose data types in a set, list, map, or tuple. Separate the data types with a comma.
`;`	Marks the end of a CQL statement.
`[--]`	Separate command line options from command arguments with two hyphens. This syntax is useful when arguments might be mistaken for command line options.
`@<xml_entity>='<xml_entity_type>'`	Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.

UPPERCASE

Literal keyword, unless bold. If bold, it is a variable. For example, DESCRIBE KEYSPACE KEYSPACE_NAME; includes the CQL keywords DESCRIBE KEYSPACE and the variable KEYSPACE_NAME. If you ran this command, you would replace KEYSPACE_NAME with the name of the keyspace you want to describe, such as DESCRIBE KEYSPACE customers;.

Lowercase

Not literal

< > or bold

Often represents a variable placeholder that you must replace with a user-defined value. However, angle brackets are also required to surround data types in a set, list, map, or tuple.

[]

Optional command arguments. Do not type the square brackets.

( )

A group of options you can choose from. Do not type the parentheses.

|

Separates alternative elements when you can choose one of several elements. Type any one of the elements. Do not type the vertical bar.

...

A repeatable syntax element. Can be reused as often as required.

'

Single quotation marks must surround literal strings in CQL statements, such as 'example_string'. Use single quotation marks to preserve upper case.

Additionally, single quotation marks are used in Search CQL to surround an entire XML schema declaration. For example: ' <schema> ... </schema> '

{ <key> : <value> }

Curly braces enclose map collections or key value pairs. A colon separates the key and the value.

<datatype2

Angle brackets enclose data types in a set, list, map, or tuple. Separate the data types with a comma.

;

Marks the end of a CQL statement.

[--]

Separate command line options from command arguments with two hyphens. This syntax is useful when arguments might be mistaken for command line options.

@<xml_entity>='<xml_entity_type>'

Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.

targets

A full single keyspace or a list of tables within that keyspace. Tables are prefixed with the keyspace and multiple tables are separated by commas, for example, keyspace_1.my_table_1, keyspace_1.my_table_2.

store_name

Name of the backup store. Store names can use alphanumeric characters and underscores only. They are case insensitive.

keyspace_name_new

Name of the new keyspace into which the backup data should be restored. The keyspace must exist.

settings

A key/value list of settings particular to the store class. For example, for an FSBlobStore class:

settings = {'path':'/path/to/data', 'retention_time':'1w'}

Common settings for all store classes: The following optional settings can be used with any store class.

transfer_rate_limit_mbs (int): Maximum upload rate per node in MB per second. Not supported for the CompositeStore class.
retention_time (duration): Time duration for which a snapshot is retained. Can be used alone or with retention_number. If set to 0, this parameter is ignored. For example, to retain snapshots for one week, set 'retention_time':'1w'.

retention_number (int): Minimum number of snapshots retained. Can be used alone or with retention_time. If set to 0, this parameter is ignored. For example, to retain a minimum of three snapshots, set 'retention_number':3.

If both retention_time and retention_number are set, the retention time only applies if there are more than retention_number snapshots.

For example, assume you set 'retention_time':'1w', 'retention_number':3, and there are only two backups in the last week. In order to meet the retention_number, both current backups are retained in addition to the most recent backup that is older than one week.

Any partial backups with a status of INCOMPLETE or QUORUM that occur between full backups are also retained.

FSBlobStore class settings: For the FSBlobStore class, you must include the path setting. This is a text value that specifies the path where snapshots are stored. The target directory must already exist.
AzureBlobStore class settings: The following settings are applicable to the AzureBlobStore class only. All are required.
- container (text): Azure container in which snapshots are stored.
- endpoint (text): Azure endpoint or Azure account name.
- sas_token (text): Azure Shared Access Signature (SAS) token. Not required if using the Azure Managed Identity authentication mechanism.
GoogleCloudBlobStore class settings: The following settings are applicable to the GoogleCloudBlobStore class only:
- bucket (text): Required. Google Cloud bucket in which snapshots are stored.
- project_id (text): Optional. Project ID associated with the Google Cloud bucket.
- endpoint (text): Optional. Google Cloud Endpoint.
- client_email (text): Email address associated with the Google Cloud account. Required only if private_key is set.
- client_id (text): Optional. Client ID associated with the Google Cloud account.
- private_key (text): Private key associated with the Google Cloud account. Required only if client_email is set.
- private_key_id (text): Optional. Private key ID of the private_key associated with the Google Cloud account.
  
  If no credentials are set in the GoogleCloudBlobStore settings, then the Application Default Credentials (ADC) are used. To find credentials, ADC checks if the environment variable GOOGLE_APPLICATION_CREDENTIALS is set. If it is set, ADC uses the referenced service account file. If it isn’t set, ADC uses the default service account provided by the Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions, depending on the environment on which the application is running. If no credentials are found, an error occurs.
S3BlobStore class settings: The following settings are applicable to only the S3BlobStore class.
- bucket (text): Required. AWS bucket in which snapshots are stored.
- region (text): AWS region, an alternative to the endpoint setting. Required if endpoint is not set.
- endpoint (text): Endpoint for the AWS S3 server, an alternative to the region setting. Required if region is not set.
- default_socket_timeout (int): Optional. Socket timeout in ms. Default: 50,000.
- max_error_retry (int): Optional. Maximum retries when an error occurs. Default: 3.
- default_throttle_retries (Boolean): Optional. Whether to enable retry throttling. Default: true.
- server_side_encryption (Boolean): Optional. Whether to enable server-side encryption (AES256). Default: true.
- accelerated_mode_enabled (Boolean): Optional. Whether to enable AWS transfer acceleration. Only applicable to AWS S3. Default: false.
- storage_class (text): Optional. Storage class in which Binary Large Objects (BLOBS) are stored.
- canned_acl (text): Optional. Access Control List (ACL) for buckets and objects.
- access_key (text): Optional. Access key used for authentication.
- secret_key (text): Optional. Secret key used for authentication.
  
  If no authentication details are specified in the S3BlobStore settings, the DefaultAWSCredentialsProviderChain is used. The DefaultAWSCredentialsProviderChain searches for credentials by first checking the environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. If these aren’t set, it checks the Java system properties aws.accessKeyId and aws.secretKey. If it still doesn’t find credentials, it checks for a credential profile located at ~/.aws/credentials. If no profile is found, it checks for credentials provided through the Amazon EC2 container service if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access that variable. If none of these methods provide credentials, it checks for instance profile credentials delivered using the Amazon EC2 metadata service.
CompositeStore class settings: For the CompositeStore class, you must include the data-center-name setting. This setting accepts a key-value pair where the key is a valid DSE datacenter name and the value is an existing configured backup store (one of FSBlobStore, AzureBlobStore, GoogleCloudBlobStore, or S3BlobStore).

Examples

Restore a full keyspace backup

Restore a specific backup from a file system store class:

FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1;

02d2603a-7e22-11e9-8f9e-2a86e4085a59

Restore tables within a keyspace

Restore specific tables within a keyspace:

FORCE RESTORE keyspace_1.data_table_1, keyspace_1.data_table_2
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1;

02d3333a-7e22-11e9-8f9e-2a86e4085a59

Restore a keyspace into a new keyspace

Restore a keyspace to a new keyspace:

FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1
    INTO KEYSPACE keyspace_2;

12f5533a-7e22-11e9-8f9e-2a86e4085a59

Restore a backup with custom store settings into a new cluster

On a node in a new cluster with the Backup and Restore Service enabled, restore a specific backup from an existing FSBlobStore backup store:

FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    USING 'FSBlobStore'
    WITH settings={'path': '/my/backup/path'};

12e2603b-7e22-11e9-8f9e-2a86e4085a62

The required settings for each backup store class are:

FSBlobStore: <path>
GoogleCloudBlobStore: <bucket>
S3BlobStore: <bucket> and <region> or <bucket> and <endpoint>