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

  • Article

APPLIES TO: NoSQL MongoDB Gremlin Table

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, Azure Cosmos DB API for Gremlin, Table API and the Azure Cosmos DB API for MongoDB.

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 the backuppolicy parameter enables continuous backup and point-in-time restore. This mode is referred to as 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 point-in-time restore and continuous backup enabled by default. The continuous backup tier can be set to Continuous7Days or Continuous30Days. By default, if no tier is provided, Continuous30Days is applied on the account.

Note

Currently the point-in-time restore feature is available for Azure Cosmos DB for NoSQL, API for MongoDB, Table and Gremlin accounts. After you create an account with continuous mode you can't switch it to a periodic mode. The Continuous7Days tier is in preview.

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.

publicNetworkAccess

This property needs to be set to 'Disabled' to restore account without public network access. If this property is not provided, restore of the account will proceed with publicNetworkAccess as Enabled.

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. For more information, see restorable SQL resources. 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. For more information, see restorable Gremlin resources. If this value is empty, then the entire account is restored.
restoreWithTtlDisabled boolean flag values (true/false) to disable Time-To-Live in the restored account upon completion of the restore. (preview)
tablesToRestore List of TableRestoreResource objects to specify which tables should be restored. Each resource represents a table under that database. For more information, see restorable Table resources. 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": "chinanorth",
  "properties": {
    "databaseAccountOfferType": "Standard",
    "locations": [
      {
        "failoverPriority": "0",
        "locationName": "chinaeast",
        "isZoneRedundant": "false"
      }
    ],
    "createMode": "Restore",
    "publicNetworkAccess":"Disabled",
    "restoreParameters": {
      "restoreMode": "PointInTime",
      "restoreWithTtlDisabled" : "true",
      "restoreSource": "/subscriptions/subid/providers/Microsoft.DocumentDB/locations/chinanorth/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 includes:

  • Where the resources can be restored
  • Locations where the resources can be restored from
  • 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 multiple-region 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.
OldestRestorableTimeStamp The earliest time in UTC to which restore can be performed. For the 30 day tier, this time can be maximum 30 days from now, for the seven days tier, this time can be up to seven days from now.

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.
database The properties of the SQL database at the time of the event,

Note

Possible values for operationType include:

  • 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 mutations, see Restorable NoSQL 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.
container The properties of the SQL container at the time of the event.

Note

Possible values for operationType include:

  • 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

To get a list of all container mutations under the same database, see Restorable NoSQL 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 NoSQL 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.

Note

Possible values for operationType include:

  • 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.

Note

Possible values for operationType include:

  • 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 resources - list.

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.

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.

Note

Possible values for operationType include:

  • 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, see restorable graph databases - list.

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.

Note

Possible values for operationType include:

  • 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 API for Table 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.

Note

Possible values for operationType include:

  • 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