Choose when to use declarative versus imperative operations

When working with Microsoft Azure Cosmos DB in the context of designing and implementing native applications, you have the flexibility to choose between declarative and imperative operations. Declarative operations focus on specifying what you want to achieve, while imperative operations focus on how to achieve it. Understanding when to use each type is crucial for efficient and effective application development.

Declarative Operations

Declarative operations involve interacting with Cosmos DB through SQL API queries and operations. These operations define the desired outcome without explicitly specifying the implementation details. Declarative programming allows for a more abstract and high-level approach to data access and manipulation.

One common use case for declarative operations is querying data. For example, you can use the SQL API to issue SELECT statements to extract specific documents or retrieve data that matches certain conditions. Here’s an example of a SQL query that retrieves all documents from a collection:

SELECT * FROM c

By using declarative operations, you can focus on defining the data you need, rather than worrying about the underlying implementation logic.

Imperative Operations

On the other hand, imperative operations involve using SDKs and APIs to interact with Cosmos DB programmatically. Imperative operations give you fine-grained control over the application flow and let you explicitly define the steps to perform specific actions.

Imperative operations are often useful for scenarios such as data manipulation, updating documents, or executing complex operations that cannot be achieved through simple SQL queries alone. Let’s take a look at an example of an imperative operation using the .NET SDK to create a new document:

using Microsoft.Azure.Cosmos;

// Create a new document
dynamic document = new { id = "documentId", name = "John Doe" };
ItemResponse response = await container.CreateItemAsync(document);


In this code snippet, we first initialize the Cosmos Client and obtain a reference to the desired container. Then, we create a new document using an anonymous type and issue an imperative operation to insert it into the container.

Imperative operations provide more control and allow you to incorporate business logic and application-specific requirements.

Choosing the Right Approach

Choosing between declarative and imperative operations depends on the specific requirements of your native application. If your application primarily involves simple queries and data retrieval, declarative operations using SQL API queries are sufficient and provide an easier and more expressive way to interact with Cosmos DB.

On the other hand, if you need more control over the application flow, complex data manipulation, or integration with other services, imperative operations using SDKs and APIs are the way to go.

Remember that declarative and imperative operations are not mutually exclusive. In many cases, you might find yourself using a combination of both approaches within your application, depending on the task at hand.

By understanding the distinction between declarative and imperative operations and considering the specific needs of your native application, you can effectively leverage Microsoft Azure Cosmos DB to build robust and efficient applications.