What is Database.ReadAsync() for?

user_1527 0
Viewed 106

In the samples for the Cosmos DB SQL API, there are a couple of uses of Database.ReadAsync() which don't seem to be doing anything useful. The remarks second in the method's documentation doesn't really indicate what it might be used for either.

What is the reason for using it in these cases? When would you typically use it?

ChangeFeed/Program.cs#L475 shows getting a database then calling ReadAsync to get another reference to the database

            database = await client.GetDatabase(databaseId).ReadAsync();
            await database.DeleteAsync();

which seems to be functionally the same as

            database = client.GetDatabase(databaseId);
            await database.DeleteAsync();

throwing the same exception if the database is not found.

and DatabaseManagement/Program.cs#L80-L83

        DatabaseResponse readResponse = await database.ReadAsync();
        Console.WriteLine($"\n3. Read a database: {readResponse.Resource.Id}");

        await readResponse.Database.CreateContainerAsync("testContainer", "/pk");

which seems to be equivalent to:

        Console.WriteLine($"\n3. Read a database: {database.Id}");

        await database.CreateContainerAsync("testContainer", "/pk");

producing the same output and creating the container as before.

azure-cosmosdb-sqlapi azure-cosmosdb
2 Answers

You are correct that those samples might need polishing, the main difference is:

  • GetDatabase just gets a proxy object, it does not mean the database actually exists. If you attempt an operation on a database that does not exist, for example, CreateContainer, it can fail with a 404.
  • ReadAsync will read the DatabaseProperties and allow you obtain any information from there and also would succeed if the database actually exists. Does that guarantee that if I call CreateContainer right away it will succeed? No, because the database could have been deleted right in the middle.

So in summary, ReadAsync is good if you want to get any of the DatabaseProperties or if you want to for some reason verify the database exists.

Most common scenarios would just use GetDatabase because you are probably attempting operations down the chain (like creating a container or executing item level operations in some container in that database).

user_56415980

Short Answer

Database.ReadAsync(...) is useful for reading database properties.

The Database object is useful for performing operations on the database, such as creating a container via Database.CreateContainerIfNotExistsAsync(...).

A bit more detail

The Microsoft Docs page for Database.ReadAsync is kind of confusing and not well written in my opinion:

The definition says:

Reads a DatabaseProperties from the Azure Cosmos service as an asynchronous operation.

However, the example shows ReadAsync returning a DatabaseResponse object, not a DatabaseProperties object:

// Reads a Database resource where database_id is the ID property of the Database resource you wish to read.
Database database = this.cosmosClient.GetDatabase(database_id);
DatabaseResponse response = await database.ReadAsync();

It's only after a bit more digging that things become clearer. When you look at the documentation page for the DatabaseResponse Class it says the inheritance chain for DatabaseResponse is:

Inheritance: Object -> Response<DatabaseProperties> -> DatabaseResponse

If you then have a look at the Docs page for the Response<T> Class you'll see there is an implicit operator that converts Response<T> to T:

public static implicit operator T (Microsoft.Azure.Cosmos.Response<T> response);

So that means that even though the ReadAsync method returns a DatabaseResponse object, that is implicitly converted to a DatabaseProperties object (since DatabaseResponse inherits Response<DatabaseProperties>).

So Database.ReadAsync is useful for reading database properties.

The Docs page for Database.ReadAsync could have clearer about the implicit link between the DatabaseResponse object returned by the method and the DatabaseProperties object that it wraps.

user_2164400
Related