Configure your Azure Cosmos DB for MongoDB account capabilities

  • Article

APPLIES TO: MongoDB

Capabilities are features that can be added or removed to your API for MongoDB account. Many of these features affect account behavior, so it's important to be fully aware of the effect a capability has before you enable or disable it. Several capabilities are set on API for MongoDB accounts by default and can't be changed or removed. One example is the EnableMongo capability. This article demonstrates how to enable and disable a capability.

Prerequisites

Available capabilities

Capability Description Removable
DisableRateLimitingResponses Allows Mongo API to retry rate-limiting requests on the server side until the value that's set for max-request-timeout. Yes
EnableMongoRoleBasedAccessControl Enable support for creating users and roles for native MongoDB role-based access control. No
EnableMongoRetryableWrites Enables support for retryable writes on the account. Yes
EnableMongo16MBDocumentSupport Enables support for inserting documents up to 16 MB in size. 1 No
EnableUniqueCompoundNestedDocs Enables support for compound and unique indexes on nested fields if the nested field isn't an array. No
EnableTtlOnCustomPath Provides the ability to set a custom Time to Live (TTL) on any one field in a collection. Setting TTL on partial unique index property is not supported. 2 No
EnablePartialUniqueIndex Enables support for a unique partial index, so you have more flexibility to specify exactly which fields in documents you'd like to index. No

Note

1 This capability cannot be enabled on an Azure Cosmos DB for MongoDB accounts with Customer Managed Keys (CMK).

Note

2 This capability cannot be enabled on an Azure Cosmos DB for MongoDB accounts with continuous backup.

Important

Changing capabilities using Azure Resource Manager is not available for Azure Cosmos DB for MongoDB accounts.

Enable a capability

  1. Retrieve your existing account capabilities by using az cosmosdb show:

    az cosmosdb show \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name>

    You should see a capability section that's similar to this example output:

    "capabilities": [
  {
    "name": "EnableMongo"
  }
]

    Review the default capability. In this example, the only capability that's set is EnableMongo.

  2. Set the new capability on your database account. The list of capabilities should include the list of previously enabled capabilities that you want to keep.

    Only explicitly named capabilities are set on your account. For example, if you want to add the DisableRateLimitingResponses capability to the preceding example, use the az cosmosdb update command with the --capabilities parameter, and list all capabilities that you want to have in your account:

    az cosmosdb update \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name> \
    --capabilities EnableMongo DisableRateLimitingResponses

    Important

    The list of capabilities must always specify all capabilities that you want to enable, inclusively. This includes capabilities that are already enabled for the account that you want to keep. In this example, the EnableMongo capability was already enabled, so you must specify both the EnableMongo capability and the DisableRateLimitingResponses capability.

    Tip

    If you're using PowerShell and an error message appears when you use the preceding command, instead try using a PowerShell array to list the capabilities:

    az cosmosdb update \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name> \
    --capabilities @("EnableMongo","DisableRateLimitingResponses")

Disable a capability

  1. Retrieve your existing account capabilities by using az cosmosdb show:

    az cosmosdb show \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name>

    You should see a capability section that's similar to this example output:

    "capabilities": [
  {
    "name": "EnableMongo"
  },
  {
    "name": "DisableRateLimitingResponses"
  }
]

    Check for all capabilities that are currently set. In this example, two capabilities are set: EnableMongo and DisableRateLimitingResponses.

  2. Remove one of the capabilities from your database account. The list of capabilities should include the list of previously enabled capabilities that you want to keep.

    Only explicitly named capabilities are set on your account. For example, if you want to remove the DisableRateLimitingResponses capability, you would use the az cosmosdb update command, and list the capability that you want to keep:

    az cosmosdb update \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name> \
    --capabilities EnableMongo

    Tip

    If you're using PowerShell and an error message appears when you use this command, instead try using a PowerShell array to list the capabilities:

    az cosmosdb update \
    --resource-group <azure_resource_group> \
    --name <azure_cosmos_db_account_name> \
    --capabilities @("EnableMongo")

Next steps