Priority-based execution in Azure Cosmos DB (preview)

APPLIES TO: NoSQL

Priority based execution allows users to specify priority of requests sent to Azure Cosmos DB. In cases where the number of requests exceeds the capacity that can be processed within the configured Request Units per second (RU/s), then Azure Cosmos DB throttles low priority requests to prioritize the execution of high priority requests.

This feature enables users to execute critical tasks while delaying less important tasks when the total consumption of container exceeds the configured RU/s in high load scenarios by implementing throttling measures for low priority requests first. Any client application using SDK retries low priority requests in accordance with the retry policy configured.

You can use priority-based execution when your application has different priorities for workloads running on the same container. For example,

• Prioritizing read, write, or query operations.
• Prioritizing user actions vs background operations like
  • Stored procedures
  • Data ingestion/migration

To get started using priority-based execution, navigate to the Features page in you're in Azure Cosmos DB account. Select and enable the Priority-based execution (preview) feature.

• .NET v3: v3.33.0-preview or later
• Java v4: v4.45.0 or later
• Spark 3.2: v4.19.0 or later
• JavaScript v4: v4.0.0 or later
• Python: v4.5.2b2 or later. Available only in preview version.

using Microsoft.Azure.Cosmos;

//update products catalog with low priority
RequestOptions catalogRequestOptions = new ItemRequestOptions{PriorityLevel = PriorityLevel.Low}; 

PartitionKey pk = new PartitionKey(“productId1”); 
ItemResponse<Product> catalogResponse = await this.container.CreateItemAsync<Product>(product1, pk, requestOptions); 

//Display product information to user with high priority
RequestOptions getProductRequestOptions = new ItemRequestOptions{PriorityLevel = PriorityLevel.High}; 

string id = “productId2”; 
PartitionKey pk = new PartitionKey(id); 

ItemResponse<Product> productResponse = await this.container.ReadItemAsync< Product>(id, pk, getProductRequestOptions); 

import com.azure.cosmos.ThroughputControlGroupConfig;
import com.azure.cosmos.ThroughputControlGroupConfigBuilder;
import com.azure.cosmos.models.CosmosItemRequestOptions;
import com.azure.cosmos.models.PriorityLevel;

class Family{
   String id;
   String lastName;
}

//define throughput control group with low priority
ThroughputControlGroupConfig groupConfig = new ThroughputControlGroupConfigBuilder()
                .groupName("low-priority-group")
                .priorityLevel(PriorityLevel.LOW)
                .build();
container.enableLocalThroughputControlGroup(groupConfig);

CosmosItemRequestOptions requestOptions = new CosmosItemRequestOptions();
        requestOptions.setThroughputControlGroupName(groupConfig.getGroupName());

Family family = new Family();
family.setLastName("Anderson");


// Insert this item with low priority in the container using request options.
container.createItem(family, new PartitionKey(family.getLastName()), requestOptions)
    .doOnSuccess((response) -> {
        logger.info("inserted doc with id: {}", response.getItem().getId());
    }).doOnError((exception) -> {
        logger.error("Exception. e: {}", exception.getLocalizedMessage(), exception);
    }).subscribe();
    

item1_read = container.read_item("item1", "pk1", priority="High")
item2_read = container.read_item("item2", "pk2", priority="Low")
query = list(container.query_items("Select * from c", partition_key="pk1", priority="High"))

You can monitor the behavior of requests with low and high priority using Azure Monitor metrics in the Azure portal. To learn more about metrics, see Azure Monitor metrics.

If Priority-based execution is enabled and priority level isn't specified for a request by the user, then all such requests are executed with high priority. You can change the default priority level of requests in a Cosmos DB account using Azure CLI.

# install preview Azure CLI version 0.26.0 or later
az extension add --name cosmosdb-preview --version 0.26.0

# set subscription context
az account set -s $SubscriptionId

# Enable priority-based execution
az cosmosdb update  --resource-group $ResourceGroup --name $AccountName --enable-priority-based-execution true

# change default priority level
az cosmosdb update  --resource-group $ResourceGroup --name $AccountName --default-priority-level low

• Priority-based execution is currently not supported for serverless database accounts.
• The behavior of priority-based execution feature is non-deterministic for shared throughput database containers.

• For strong and bounded staleness consistency levels, read request prioritization may not work effectively allowing low priority write requests to execute irrespective of high priority read traffic.

• See the FAQ on Priority-based execution