Get the latest restorable timestamp for continuous backup accounts

Article
09/14/2024

APPLIES TO: NoSQL MongoDB Gremlin Table

This article describes how to get the latest restorable timestamp for accounts with continuous backup mode. It explains how to get the latest restorable time using Azure PowerShell and Azure CLI, and provides the request and response format for the PowerShell and CLI commands.

This feature is supported for Azure Cosmos DB API for NoSQL containers, API for MongoDB , Table API and API for Gremlin graphs.

Important

For multi-region write accounts, the latest restorable timestamp is determinded by a conflict resolution timestamp (crts). This is not returned by the methods listed below. See GitHub sample here to learn how to consume Azure Cosmos DB's Change Feed and return documents with ConflictResolvedTimestamp(crts) in a container.

SQL container

PowerShell

Get-AzCosmosDBSqlContainerBackupInformation -AccountName <System.String> `
  -DatabaseName <System.String> `
  [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] `
  -Location <System.String> `
  -Name <System.String> `
  -ResourceGroupName <System.String> [<CommonParameters>]

Sample request:

Get-AzCosmosDBSqlContainerBackupInformation -ResourceGroupName "rg" `
  -AccountName "sqlpitracc" `
  -DatabaseName "db1" `
  -Name "container1" `
  -Location "chinaeast"

Sample response (in UTC format):

LatestRestorableTimestamp
-------------------------
10/26/2021 6:24:25 PM

CLI

az cosmosdb sql retrieve-latest-backup-time -g {resourcegroup} \
  -a {accountname} \
  -d {db_name} \
  -c {container_name} \
  -l {location}

Sample request:

az cosmosdb sql retrieve-latest-backup-time -g "rg" \
  -a "sqlpitracc" \
  -d "db1" \
  -c "container1" \
  -l "chinaeast"

Sample response (in UTC format):

{
  "continuousBackupInformation": {
    "latestRestorableTimestamp": "10/26/2021 5:27:45 PM"
  }
}

SQL database

Use the following script to get the latest restorable timestamp for a database. This script will iterate through all the containers within the specified database and returns the minimum of latest restorable timestamp of all its containers.

Function Get-LatestRestorableTimestampForSqlDatabase {
[CmdletBinding()]
param(
  [Parameter(Position = 0, mandatory = $true)]
  [string] $resourceGroupName,
  [Parameter(Position = 1, mandatory = $true)]
  [string] $accountName,
  [Parameter(Position = 2, mandatory = $true)]
  [string] $databaseName,
  [Parameter(Position = 3, mandatory = $true)]
  [string] $location)

Write-Host
Write-Host "Latest restorable timestamp for a database is minimum of restorable timestamps of all the underlying containers"
Write-Host

Write-Debug "Listing all containers in database: $databaseName"
$containers = Get-AzCosmosDBSqlContainer -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $databaseName

If (-Not $containers) {
    throw "Error: Found no containers to restore in the given database."
}

Write-Debug "Found $($containers.Length) containers under database $databaseName"

$latestRestorableTimestampForDatabase = [DateTime]::MaxValue
foreach ($container in $containers) {
    Write-Debug "Getting latest restorable timestamp for container: $($container.Name)"

    $latestRestorableTimestampForContainer = Get-AzCosmosDBSqlContainerBackupInformation -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $databaseName -Name $container.Name -Location $location

    Write-Debug "Latest Restorable Timestamp for container $($container.Name): $($latestRestorableTimestampForContainer.LatestRestorableTimestamp)"

    $latestRestorableTimestampForContainerDateTime = [DateTime]$latestRestorableTimestampForContainer.LatestRestorableTimestamp

    If ($latestRestorableTimestampForContainerDateTime -lt $latestRestorableTimestampForDatabase) {
        Write-Debug "Latest Restorable Timestamp for container $($container.Name) is less than current database restorable timestamp: $latestRestorableTimestampForDatabase"

        $latestRestorableTimestampForDatabase = $latestRestorableTimestampForContainerDateTime
    }

    Write-Debug "Latest Restorable Timestamp for database so far: $latestRestorableTimestampForDatabase"
}

if ($latestRestorableTimestampForDatabase -eq [DateTime]::MaxValue) {
    throw "Error: Failed to retrieve latest backup timestamp for database: $databaseName"
}

Write-Debug "Latest Restorable Timestamp in UTC for database $($databaseName): $latestRestorableTimestampForDatabase"

return $latestRestorableTimestampForDatabase
}

Syntax:

Get-LatestRestorableTimestampForSqlDatabase `
  -ResourceGroupName <resourceGroup> `
  -AccountName <accountName> `
  -DatabaseName <databaseName> `
  -Location <location>

Sample request:

Import-Module .\LatestRestorableDatabaseForSqlDatabase.ps1
Get-LatestRestorableTimestampForSqlDatabase `
  -ResourceGroupName rg `
  -AccountName sqlpitracc `
  -DatabaseName db1 `
  -Location chinaeast

Sample response (in UTC format):

Latest restorable timestamp for a database is minimum of restorable timestamps of all the underlying containers
Wednesday, November 3, 2021 8:02:44 PM

SQL account

Use the following script to get the latest restorable timestamp for a SQL account. This script will iterate through all the containers within this account and returns the minimum of latest restorable timestamp of all its containers.

Function Get-LatestRestorableTimestampForSqlAccount {
[CmdletBinding()]
param(
    [Parameter(Position = 0, mandatory = $true)]
    [string] $resourceGroupName,
    [Parameter(Position = 1, mandatory = $true)]
    [string] $accountName,
    [Parameter(Position = 2, mandatory = $true)]
    [string] $location)

Write-Host
Write-Host "Latest restorable timestamp for an account is minimum of restorable timestamps of all the underlying containers"
Write-Host

Write-Debug "Listing all databases in account: $accountName"

$databases = Get-AzCosmosDBSqlDatabase -ResourceGroupName $resourceGroupName -AccountName $accountName
Write-Debug "Found $($databases.Length) databases under account $accountName"

$latestRestorableTimestampForAccount = [DateTime]::MaxValue

foreach ($database in $databases) {
    Write-Debug "Listing all containers in database: $($database.Name)"
    $containers = Get-AzCosmosDBSqlContainer -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $($database.Name)

    If (-Not $containers) {
        throw "Error: Found no containers to restore in the given database."
    }

    Write-Debug "Found $($containers.Length) containers under database $($database.Name)"

    foreach ($container in $containers) {
        Write-Debug "Getting latest restorable timestamp for container: $($container.Name)"

        $latestRestorableTimestampForContainer = Get-AzCosmosDBSqlContainerBackupInformation -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $database.Name -Name $container.Name -Location $location

        Write-Debug "Latest Restorable Timestamp for container $($container.Name): $($latestRestorableTimestampForContainer.LatestRestorableTimestamp)"

        $latestRestorableTimestampForContainerDateTime = [DateTime]$latestRestorableTimestampForContainer.LatestRestorableTimestamp

        If ($latestRestorableTimestampForContainerDateTime -lt $latestRestorableTimestampForAccount) {
            Write-Debug "Latest Restorable Timestamp for container $($container.Name) is less than current database restorable timestamp: $latestRestorableTimestampForAccount"

            $latestRestorableTimestampForAccount = $latestRestorableTimestampForContainerDateTime
        }

        Write-Debug "Latest Restorable Timestamp for database so far: $latestRestorableTimestampForAccount"
    }
}

if ($latestRestorableTimestampForAccount -eq [DateTime]::MaxValue) {
    throw "Error: Failed to retrieve latest backup timestamp for account: $accountName"
}
    
Write-Debug "Latest Restorable Timestamp in UTC for account $($accountName): $latestRestorableTimestampForAccount"

return $latestRestorableTimestampForAccount
}

Syntax:

Get-LatestRestorableTimestampForSqlAccount `
  -ResourceGroupName <resourceGroupName> `
  -AccountName <accountName> `
  -Location <location>

Sample request:

Import-Module .\LatestRestorableTimestampForSqlAccount.ps1

Get-LatestRestorableTimestampForSqlAccount `
  -ResourceGroupName rg `
  -AccountName sqlpitracc `
  -location chinaeast

Sample response (in UTC format):

Latest restorable timestamp for an account is minimum of restorable timestamps of all the underlying containers
Wednesday, November 3, 2021 8:11:03 PM

MongoDB collection

PowerShell

Get-AzCosmosDBMongoDBCollectionBackupInformation `
  -AccountName <System.String> `
  -DatabaseName <System.String> `
  [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] `
  -Location <System.String> `
  -Name <System.String> `
  -ResourceGroupName <System.String> [<CommonParameters>]

Sample request:

Get-AzCosmosDBMongoDBCollectionBackupInformation `
  -ResourceGroupName "rg" `
  -AccountName "mongodbpitracc" `
  -DatabaseName "db1" `
  -Name "col1" `
  -Location "chinaeast"

Sample response (in UTC format):

LatestRestorableTimestamp
-------------------------
10/26/2021 6:27:22 PM

CLI

az cosmosdb mongodb retrieve-latest-backup-time \
  -g {resourcegroup} \
  -a {accountname} \
  -d {db_name} \
  -c {collection_name} \
  -l {location}

Sample request:

az cosmosdb mongodb retrieve-latest-backup-time \
  -g "rg" \
  -a "mongodbpitracc" \
  -d "db1" \
  -c "col1" \
  -l "chinaeast"

Sample response:

{
  "continuousBackupInformation": {
    "latestRestorableTimestamp": "10/26/2021 5:27:45 PM"
  }
}

MongoDB database

Use the following script to get the latest restorable timestamp for a database. This script will iterate through all the collections within this database and will return the minimum of latest restorable timestamp of all its collections.

Function Get-LatestRestorableTimestampForMongoDBDatabase {
[CmdletBinding()]
param(
    [Parameter(Position = 0, mandatory = $true)]
    [string] $resourceGroupName,
    [Parameter(Position = 1, mandatory = $true)]
    [string] $accountName,
    [Parameter(Position = 2, mandatory = $true)]
    [string] $databaseName,
    [Parameter(Position = 3, mandatory = $true)]
    [string] $location)
    
Write-Host
Write-Host "Latest restorable timestamp for a database is minimum of restorable timestamps of all the underlying collections"
Write-Host

Write-Debug "Listing all collections in database: $databaseName"
$collections = Get-AzCosmosDBMongoDBCollection -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $databaseName

If (-Not $collections) {
    throw "Error: Found no collections to restore in the given database."
}

Write-Debug "Found $($collections.Length) collections under database $databaseName"

$latestRestorableTimestampForDatabase = [DateTime]::MaxValue
foreach ($collection in $collections) {
    Write-Debug "Getting latest restorable timestamp for collection: $($collection.Name)"

    $latestRestorableTimestampForCollection = Get-AzCosmosDBMongoDBCollectionBackupInformation -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $databaseName -Name $collection.Name -Location $location

    Write-Debug "Latest Restorable Timestamp for collection $($collection.Name): $($latestRestorableTimestampForCollection.LatestRestorableTimestamp)"

    $latestRestorableTimestampForCollectionDateTime = [DateTime]$latestRestorableTimestampForCollection.LatestRestorableTimestamp

    If ($latestRestorableTimestampForCollectionDateTime -lt $latestRestorableTimestampForDatabase) {
        Write-Debug "Latest Restorable Timestamp for collection $($collection.Name) is less than current database restorable timestamp: $latestRestorableTimestampForDatabase"

        $latestRestorableTimestampForDatabase = $latestRestorableTimestampForCollectionDateTime
    }

    Write-Debug "Latest Restorable Timestamp for database so far: $latestRestorableTimestampForDatabase"
}

if ($latestRestorableTimestampForDatabase -eq [DateTime]::MaxValue) {
    throw "Error: Failed to retrieve latest backup timestamp for database: $databaseName"
}

Write-Debug "Latest Restorable Timestamp in UTC for database $($databaseName): $latestRestorableTimestampForDatabase"

return $latestRestorableTimestampForDatabase
}

Syntax:

Get-LatestRestorableTimestampForMongoDBDatabase `
  -ResourceGroupName <resourceGroup> `
  -AccountName <account> `
  -DatabaseName <database> `
  -Location <location>

Sample request:

Import-Module .\LatestRestorableTimestampForMongoDBDatabase.ps1
Get-LatestRestorableTimestampForMongoDBDatabase -ResourceGroupName rg -accountName mongopitracc -databaseName db1 -location chinaeast

Sample response (in UTC format):

Latest restorable timestamp for a database is minimum of restorable timestamps of all the underlying collections
Wednesday, November 3, 2021 8:31:27 PM

MongoDB account

Use can use the following script to get the latest restorable timestamp for a MongoDB account. This script will iterate through all the collections within this account and will return the minimum of latest restorable timestamp of all its collections.

Function Get-LatestRestorableTimestampForMongoDBAccount {
[CmdletBinding()]
param(
    [Parameter(Position = 0, mandatory = $true)]
    [string] $resourceGroupName,
    [Parameter(Position = 1, mandatory = $true)]
    [string] $accountName,
    [Parameter(Position = 2, mandatory = $true)]
    [string] $location)

Write-Host
Write-Host "Latest restorable timestamp for an account is minimum of restorable timestamps of all the underlying collections"
Write-Host

Write-Debug "Listing all databases in account: $accountName"

$databases = Get-AzCosmosDBMongoDBDatabase -ResourceGroupName $resourceGroupName -AccountName $accountName
Write-Debug "Found $($databases.Length) databases under account $accountName"

$latestRestorableTimestampForAccount = [DateTime]::MaxValue

foreach ($database in $databases) {
    Write-Debug "Listing all collections in database: $($database.Name)"
    $collections = Get-AzCosmosDBMongoDBCollection -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $($database.Name)

    If (-Not $collections) {
        throw "Error: Found no collections to restore in the given database."
    }

    Write-Debug "Found $($collections.Length) collections under database $($database.Name)"

    foreach ($collection in $collections) {
        Write-Debug "Getting latest restorable timestamp for collection: $($collection.Name)"

        $latestRestorableTimestampForCollection = Get-AzCosmosDBMongoDBCollectionBackupInformation -ResourceGroupName $resourceGroupName -AccountName $accountName -DatabaseName $database.Name -Name $collection.Name -Location $location

        Write-Debug "Latest Restorable Timestamp for collection $($collection.Name): $($latestRestorableTimestampForCollection.LatestRestorableTimestamp)"

        $latestRestorableTimestampForCollectionDateTime = [DateTime]$latestRestorableTimestampForCollection.LatestRestorableTimestamp

        If ($latestRestorableTimestampForCollectionDateTime -lt $latestRestorableTimestampForAccount) {
            Write-Debug "Latest Restorable Timestamp for collection $($collection.Name) is less than current database restorable timestamp: $latestRestorableTimestampForAccount"

            $latestRestorableTimestampForAccount = $latestRestorableTimestampForCollectionDateTime
        }

        Write-Debug "Latest Restorable Timestamp for database so far: $latestRestorableTimestampForAccount"
    }
}

if ($latestRestorableTimestampForAccount -eq [DateTime]::MaxValue) {
    throw "Error: Failed to retrieve latest backup timestamp for account: $accountName"
}

Write-Debug "Latest Restorable Timestamp in UTC for account $($accountName): $latestRestorableTimestampForAccount"

return $latestRestorableTimestampForAccount
}

Syntax:

Get-LatestRestorableTimestampForMongoDBAccount `
  -ResourceGroupName <resourceGroupName> `
  -AccountName <accountName> `
  -Location <location>

Sample request:

Import-Module .\LatestRestorableTimestampForMongoDBAccount.ps1
Get-LatestRestorableTimestampForMongoDBAccount `
  -ResourceGroupName rg `
  -AccountName mongopitracc `
  -Location chinaeast

Sample response (in UTC format):

Latest restorable timestamp for an account is minimum of restorable timestamps of all the underlying collections
Wednesday, November 3, 2021 8:33:49 PM

Gremlin graph backup information

PowerShell

Get-AzCosmosDBGremlinGraphBackupInformation  `
  -AccountName <System.String> `
  -GremlinDatabaseName  <System.String> `
  [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] `
  -Location <System.String> `
  -Name <System.String> `
  -ResourceGroupName <System.String> [<CommonParameters>]

Sample request:

Get-AzCosmosDBGremlinGraphBackupInformation  `
  -ResourceGroupName "rg" `
  -AccountName "amisigremlinpitracc1" `
  -GremlinDatabaseName  "db1" `
  -Name "graph1" `
  -Location "chinaeast"

Sample response (in UTC format):

LatestRestorableTimestamp
-------------------------
3/1/2022 2:19:14 AM

CLI

az cosmosdb gremlin retrieve-latest-backup-time \
  -g {resourcegroup} \
  -a {accountname} \
  -d {db_name} \
  -c {graph_name} \
  -l {location}

Sample request:

az cosmosdb gremlin retrieve-latest-backup-time \
  -g "rg" \
  -a "amisigremlinpitracc1" \
  -d "db1" \
  -c "graph1" \
  -l "chinaeast"

Sample response:

{
  "continuousBackupInformation": {
    "latestRestorableTimestamp": "3/2/2022 5:31:13 AM"
  }
}

Table backup information

PowerShell

Get-AzCosmosDBTableBackupInformation   `
  -AccountName <System.String> `
  [-DefaultProfile <Microsoft.Azure.Commands.Common.Authentication.Abstractions.Core.IAzureContextContainer>] `
  -Location <System.String> `
  -Name <System.String> `
  -ResourceGroupName <System.String> [<CommonParameters>]

Sample request:

Get-AzCosmosDBTableBackupInformation   `
  -ResourceGroupName "rg" `
  -AccountName "amisitablepitracc1" `
  -Name "table1" `
  -Location "chinaeast"

Sample response (in UTC format):

LatestRestorableTimestamp
-------------------------
3/2/2022 2:19:15 AM

CLI

az cosmosdb table retrieve-latest-backup-time \
  -g {resourcegroup} \
  -a {accountname} \
  -c {table_name} \
  -l {location}

Sample request:

az cosmosdb table retrieve-latest-backup-time \
  -g "rg" \
  -a "amisitablepitracc1" \
  -c "table1" \
  -l "chinaeast"

Sample response:

{
  "continuousBackupInformation": {
    "latestRestorableTimestamp": "3/2/2022 5:33:47 AM"
  }
}

Get the latest restorable timestamp for continuous backup accounts

SQL container

PowerShell

CLI

SQL database

SQL account

MongoDB collection

PowerShell

CLI

MongoDB database

MongoDB account

Gremlin graph backup information

PowerShell

CLI

Table backup information

PowerShell

CLI

Next steps

Additional resources