Skip to content

Files

Latest commit

seesharprunseesharprun
Fix spelling errors
Jun 6, 2022
4dcddeb · Jun 6, 2022

History

History
262 lines (191 loc) · 17.3 KB

continuous-backup-restore-resource-model.md

File metadata and controls

262 lines (191 loc) · 17.3 KB
title description author ms.author ms.service ms.topic ms.date ms.reviewer
Resource model for the Azure Cosmos DB point-in-time restore feature.
This article explains the resource model for the Azure Cosmos DB point-in-time restore feature. It explains the parameters that support the continuous backup and resources that can be restored in Azure Cosmos DB API for SQL and MongoDB accounts.
kanshiG
govindk
cosmos-db
conceptual
03/02/2022
mjbrown

Resource model for the Azure Cosmos DB point-in-time restore feature

[!INCLUDEappliesto-all-apis-except-cassandra]

This article explains the resource model for the Azure Cosmos DB point-in-time restore feature. It explains the parameters that support the continuous backup and resources that can be restored. This feature is supported in Azure Cosmos DB API for SQL and the Cosmos DB API for MongoDB. Currently, this feature is in preview for Azure Cosmos DB Gremlin API and Table API accounts.

Database account's resource model

The database account's resource model is updated with a few extra properties to support the new restore scenarios. These properties are BackupPolicy, CreateMode, and RestoreParameters.

BackupPolicy

A new property in the account level backup policy named Type under backuppolicy parameter enables continuous backup and point-in-time restore functionalities. This mode is called continuous backup. You can set this mode when creating the account or while migrating an account from periodic to continuous mode. After continuous mode is enabled, all the containers and databases created within this account will have continuous backup and point-in-time restore functionalities enabled by default.

Note

Currently the point-in-time restore feature is available for Azure Cosmos DB API for MongoDB and SQL accounts. After you create an account with continuous mode you can't switch it to a periodic mode.

CreateMode

This property indicates how the account was created. The possible values are Default and Restore. To perform a restore, set this value to Restore and provide the appropriate values in the RestoreParameters property.

RestoreParameters

The RestoreParameters resource contains the restore operation details including, the account ID, the time to restore, and resources that need to be restored.

Property Name Description
restoreMode The restore mode should be PointInTime
restoreSource The instanceId of the source account from which the restore will be initiated.
restoreTimestampInUtc Point in time in UTC to restore the account.
databasesToRestore List of DatabaseRestoreResource objects to specify which databases and containers should be restored. Each resource represents a single database and all the collections under that database, see the restorable SQL resources section for more details. If this value is empty, then the entire account is restored.
gremlinDatabasesToRestore List of GremlinDatabaseRestoreResource objects to specify which databases and graphs should be restored. Each resource represents a single database and all the graphs under that database. See the restorable Gremlin resources section for more details. If this value is empty, then the entire account is restored.
tablesToRestore List of TableRestoreResource objects to specify which tables should be restored. Each resource represents a table under that database, see the restorable Table resources section for more details. If this value is empty, then the entire account is restored.

Sample resource

The following JSON is a sample database account resource with continuous backup enabled:

{
  "location": "westus",
  "properties": {
    "databaseAccountOfferType": "Standard",
    "locations": [
      {
        "failoverPriority": "0",
        "locationName": "southcentralus",
        "isZoneRedundant": "false"
      }
    ],
    "createMode": "Restore",
    "restoreParameters": {
      "restoreMode": "PointInTime",
      "restoreSource": "/subscriptions/subid/providers/Microsoft.DocumentDB/locations/westus/restorableDatabaseAccounts/1a97b4bb-f6a0-430e-ade1-638d781830cc",
      "restoreTimestampInUtc": "2020-06-11T22:05:09Z",
      "databasesToRestore": [
        {
          "databaseName": "db1",
          "collectionNames": [
            "collection1",
            "collection2"
          ]
        },
        {
          "databaseName": "db2",
          "collectionNames": [
            "collection3",
            "collection4"
          ]
        }
      ]
    },
    "backupPolicy": {
      "type": "Continuous"
    }
  }
}

Restorable resources

A set of new resources and APIs is available to help you discover critical information about resources, which can be restored, locations where they can be restored from, and the timestamps when key operations were performed on these resources.

Note

All the API used to enumerate these resources require the following permissions:

  • Microsoft.DocumentDB/locations/restorableDatabaseAccounts/*/read
  • Microsoft.DocumentDB/locations/restorableDatabaseAccounts/read

Restorable database account

This resource contains a database account instance that can be restored. The database account can either be a deleted or a live account. It contains information that allows you to find the source database account that you want to restore.

Property Name Description
ID The unique identifier of the resource.
accountName The global database account name.
creationTime The time in UTC when the account was created or migrated.
deletionTime The time in UTC when the account was deleted. This value is empty if the account is live.
apiType The API type of the Azure Cosmos DB account.
restorableLocations The list of locations where the account existed.
restorableLocations: locationName The region name of the regional account.
restorableLocations: regionalDatabaseAccountInstanceId The GUID of the regional account.
restorableLocations: creationTime The time in UTC when the regional account was created r migrated.
restorableLocations: deletionTime The time in UTC when the regional account was deleted. This value is empty if the regional account is live.

To get a list of all restorable accounts, see Restorable Database Accounts - list or Restorable Database Accounts- list by location articles.

Restorable SQL database

Each resource contains information of a mutation event such as creation and deletion that occurred on the SQL Database. This information can help in scenarios where the database was accidentally deleted and if you need to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when the database is created or deleted.
ownerId The name of the SQL database.
ownerResourceId The resource ID of the SQL database
operationType The operation type of this database event. Here are the possible values:
  • Create: database creation event
  • Delete: database deletion event
  • Replace: database modification event
  • SystemOperation: database modification event triggered by the system. This event isn't initiated by the user
database The properties of the SQL database at the time of the event

To get a list of all database mutations, see Restorable Sql Databases - List article.

Restorable SQL container

Each resource contains information of a mutation event such as creation and deletion that occurred on the SQL container. This information can help in scenarios where the container was modified or deleted, and if you need to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this container event happened.
ownerId The name of the SQL container.
ownerResourceId The resource ID of the SQL container.
operationType The operation type of this container event. Here are the possible values:
  • Create: container creation event
  • Delete: container deletion event
  • Replace: container modification event
  • SystemOperation: container modification event triggered by the system. This event isn't initiated by the user
container The properties of the SQL container at the time of the event.

To get a list of all container mutations under the same database, see Restorable Sql Containers - List article.

Restorable SQL resources

Each resource represents a single database and all the containers under that database.

Property Name Description
databaseName The name of the SQL database.
collectionNames The list of SQL containers under this database.

To get a list of SQL database and container combo that exist on the account at the given timestamp and location, see Restorable Sql Resources - List article.

Restorable MongoDB database

Each resource contains information of a mutation event such as creation and deletion that occurred on the MongoDB Database. This information can help in the scenario where the database was accidentally deleted and user needs to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this database event happened.
ownerId The name of the MongoDB database.
ownerResourceId The resource ID of the MongoDB database.
operationType The operation type of this database event. Here are the possible values:
  • Create: database creation event
  • Delete: database deletion event
  • Replace: database modification event
  • SystemOperation: database modification event triggered by the system. This event isn't initiated by the user

To get a list of all database mutation, see Restorable Mongodb Databases - List article.

Restorable MongoDB collection

Each resource contains information of a mutation event such as creation and deletion that occurred on the MongoDB Collection. This information can help in scenarios where the collection was modified or deleted, and user needs to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this collection event happened.
ownerId The name of the MongoDB collection.
ownerResourceId The resource ID of the MongoDB collection.
operationType The operation type of this collection event. Here are the possible values:
  • Create: collection creation event
  • Delete: collection deletion event
  • Replace: collection modification event
  • SystemOperation: collection modification event triggered by the system. This event isn't initiated by the user

To get a list of all container mutations under the same database see Restorable Mongodb Collections - List article.

Restorable MongoDB resources

Each resource represents a single database and all the collections under that database.

Property Name Description
databaseName The name of the MongoDB database.
collectionNames The list of MongoDB collections under this database.

To get a list of all MongoDB database and collection combinations that exist on the account at the given timestamp and location, see Restorable Mongodb Resources - List article.

Restorable Graph resources

Each resource represents a single database and all the graphs under that database.

Property Name Description
gremlinDatabaseName The name of the Graph database.
graphNames The list of Graphs under this database.

To get a list of all Gremlin database and graph combinations that exist on the account at the given timestamp and location, see Restorable Graph Resources - List article.

Restorable Graph database

Each resource contains information about a mutation event, such as a creation and deletion, that occurred on the Graph database. This information can help in the scenario where the database was accidentally deleted and user needs to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this database event happened.
ownerId The name of the Graph database.
ownerResourceId The resource ID of the Graph database.
operationType The operation type of this database event. Here are the possible values:
  • Create: database creation event
  • Delete: database deletion event
  • Replace: database modification event
  • SystemOperation: database modification event triggered by the system. This event isn't initiated by the user.

To get an event feed of all mutations on the Gremlin database for the account, see the Restorable Graph Databases - List article.

Restorable Graphs

Each resource contains information of a mutation event such as creation and deletion that occurred on the Graph. This information can help in scenarios where the graph was modified or deleted, and if you need to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this collection event happened.
ownerId The name of the Graph collection.
ownerResourceId The resource ID of the Graph collection.
operationType The operation type of this collection event. Here are the possible values:
  • Create: Graph creation event
  • Delete: Graph deletion event
  • Replace: Graph modification event
  • SystemOperation: collection modification event triggered by the system. This event isn't initiated by the user.

To get a list of all container mutations under the same database, see graph Restorable Graphs - List article.

Restorable Table resources

Lists all the restorable Azure Cosmos DB Tables available for a specific database account at a given time and location. Note the Table API doesn't specify an explicit database.

Property Name Description
TableNames The list of Table containers under this account.

To get a list of tables that exist on the account at the given timestamp and location, see Restorable Table Resources - List article.

Restorable Table

Each resource contains information of a mutation event such as creation and deletion that occurred on the Table. This information can help in scenarios where the table was modified or deleted, and if you need to find out when that event happened.

Property Name Description
eventTimestamp The time in UTC when this database event happened.
ownerId The name of the Table database.
ownerResourceId The resource ID of the Table resource.
operationType The operation type of this Table event. Here are the possible values:
  • Create: Table creation event
  • Delete: Table deletion event
  • Replace: Table modification event
  • SystemOperation: database modification event triggered by the system. This event isn't initiated by the user

To get a list of all table mutations under the same database, see Restorable Table - List article.

Next steps