az cosmosdb sql container

  • Reference

Note

This command group has commands that are defined in both Azure CLI and at least one extension. Install each extension to benefit from its extended capabilities. Learn more about extensions.

Manage Azure Cosmos DB SQL containers.

Commands

Name Description Type Status
az cosmosdb sql container create

Create an SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container create (cosmosdb-preview extension)

Create an SQL container under an Azure Cosmos DB SQL database.

 Extension GA
az cosmosdb sql container delete

Delete the SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container exists

Checks if an Azure Cosmos DB SQL container exists.

 Core GA
az cosmosdb sql container list

List the SQL containers under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container merge

Merges the partitions of a sql container.

 Extension Preview
az cosmosdb sql container redistribute-partition-throughput

Redistributes the partition throughput of a sql container.

 Extension Preview
az cosmosdb sql container restore

Restore a deleted sql container within the same account.

 Core GA
az cosmosdb sql container restore (cosmosdb-preview extension)

Restore a deleted sql container within the same account.

 Extension Preview
az cosmosdb sql container retrieve-partition-throughput

Retrieve the partition throughput of a sql container.

 Extension Preview
az cosmosdb sql container show

Show the details of a SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container throughput

Manage throughput of SQL container under an Azure Cosmos DB account.

 Core GA
az cosmosdb sql container throughput migrate

Migrate the throughput of the SQL container between autoscale and manually provisioned.

 Core GA
az cosmosdb sql container throughput show

Get the throughput of the SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container throughput update

Update the throughput of the SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container update

Update an SQL container under an Azure Cosmos DB SQL database.

 Core GA
az cosmosdb sql container update (cosmosdb-preview extension)

Update an SQL container under an Azure Cosmos DB SQL database.

 Extension GA

az cosmosdb sql container create

Edit

Create an SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container create --account-name
                                 --database-name
                                 --name
                                 --partition-key-path
                                 --resource-group
                                 [--analytical-storage-ttl]
                                 [--cep]
                                 [--conflict-resolution-policy]
                                 [--idx]
                                 [--max-throughput]
                                 [--partition-key-version]
                                 [--throughput]
                                 [--ttl]
                                 [--unique-key-policy]

Examples

Create an Azure Cosmos DB SQL container.

az cosmosdb sql container create -g MyResourceGroup -a MyAccount -d MyDatabase -n MyContainer --partition-key-path "/my/path" --idx @policy-file.json --ttl 1000 --throughput "700"

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--partition-key-path -p

Partition Key Path, e.g., '/address/zipcode'.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--analytical-storage-ttl -t

Analytical TTL, when analytical storage is enabled.

--cep

Client Encryption Policy, you can enter it as a string or as a file, e.g., --cep @policy-file.json or --cep "{"includedPaths": [{"path": "/path1","clientEncryptionKeyId": "key1","encryptionAlgorithm": "AEAD_AES_256_CBC_HMAC_SHA256","encryptionType": "Deterministic"}],"policyFormatVersion": 2}".

--conflict-resolution-policy -c

Conflict Resolution Policy, you can enter it as a string or as a file, e.g., --conflict-resolution-policy @policy-file.json or --conflict-resolution-policy "{"mode": "lastWriterWins", "conflictResolutionPath": "/path"}".

--idx

Indexing Policy, you can enter it as a string or as a file, e.g., --idx @policy-file.json or --idx "{"indexingMode": "consistent", "automatic": true, "includedPaths": [{"path": "/*"}], "excludedPaths": [{ "path": "/headquarters/employees/?"}, { "path": "/\"_etag\"/?"}]}".

Default value: { "indexingMode": "consistent", "automatic": true, "includedPaths": [ { "path": "/*" } ], "excludedPaths": [ { "path": "/\"_etag\"/?" } ] }
--max-throughput

The maximum throughput resource can scale to (RU/s). Provided when the resource is autoscale enabled. The minimum value can be 4000 (RU/s).

--partition-key-version

The version of partition key.

--throughput

The throughput of SQL container (RU/s). Default value is 400. Omit this parameter if the database has shared throughput unless the container should have dedicated throughput.

--ttl

Default TTL. If the value is missing or set to "-1", items don’t expire. If the value is set to "n", items will expire "n" seconds after last modified time.

--unique-key-policy -u

Unique Key Policy, you can enter it as a string or as a file, e.g., --unique-key-policy @policy-file.json or --unique-key-policy "{"uniqueKeys": [{"paths": ["/path/to/key1"]}, {"paths": ["/path/to/key2"]}]}".

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container create (cosmosdb-preview extension)

Create an SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container create --account-name
                                 --database-name
                                 --name
                                 --partition-key-path
                                 --resource-group
                                 [--analytical-storage-ttl]
                                 [--cep]
                                 [--conflict-resolution-policy]
                                 [--idx]
                                 [--materialized-view-definition]
                                 [--max-throughput]
                                 [--partition-key-version]
                                 [--throughput]
                                 [--ttl]
                                 [--unique-key-policy]

Examples

Create an Azure Cosmos DB SQL container.

az cosmosdb sql container create -g MyResourceGroup -a MyAccount -d MyDatabase -n MyContainer --partition-key-path "/my/path" --idx @policy-file.json --ttl 1000 --throughput "700"

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--partition-key-path -p

Partition Key Path, e.g., '/address/zipcode'.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--analytical-storage-ttl -t

Analytical TTL, when analytical storage is enabled.

--cep

Client Encryption Policy, you can enter it as a string or as a file, e.g., --cep @policy-file.json or --cep "{ "includedPaths": [{"path": "/path1","clientEncryptionKeyId": "key1","encryptionAlgorithm": "AEAD_AES_256_CBC_HMAC_SHA256","encryptionType": "Deterministic"}], "policyFormatVersion": 2}".

--conflict-resolution-policy -c

Conflict Resolution Policy, you can enter it as a string or as a file, e.g., --conflict-resolution-policy @policy-file.json or --conflict-resolution-policy "{ "mode": "lastWriterWins", "conflictResolutionPath": "/path" }".

--idx

Indexing Policy, you can enter it as a string or as a file, e.g., --idx @policy-file.json or --idx "{ "indexingMode": "consistent", "automatic": true, "includedPaths": [{"path": "/*"}], "excludedPaths": [{ "path": "/headquarters/employees/?"}, { "path": "/\"_etag\"/?"}] }".

Default value: { "indexingMode": "consistent", "automatic": true, "includedPaths": [ { "path": "/*" } ], "excludedPaths": [ { "path": "/\"_etag\"/?" } ] }
--materialized-view-definition -m

Materialized View Definition, you can enter it as a string or as a file, e.g., --materialized-view-definition @materializedview-definition-file.json or --materialized-view-definition -m '{ "sourceCollectionId": "MySourceCollectionName", "definition": "SELECT * FROM root r"}'.

--max-throughput

The maximum throughput resource can scale to (RU/s). Provided when the resource is autoscale enabled. The minimum value can be 4000 (RU/s).

--partition-key-version

The version of partition key.

--throughput

The throughput of SQL container (RU/s). Default value is 400. Omit this parameter if the database has shared throughput unless the container should have dedicated throughput.

--ttl

Default TTL. If the value is missing or set to "-1", items don’t expire. If the value is set to "n", items will expire "n" seconds after last modified time.

--unique-key-policy -u

Unique Key Policy, you can enter it as a string or as a file, e.g., --unique-key-policy @policy-file.json or --unique-key-policy "{ "uniqueKeys": [{"paths": ["/path/to/key1"]}, {"paths": ["/path/to/key2"]}] }".

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container delete

Edit

Delete the SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container delete --account-name
                                 --database-name
                                 --name
                                 --resource-group
                                 [--yes]

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--yes -y

Do not prompt for confirmation.

Default value: False
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container exists

Edit

Checks if an Azure Cosmos DB SQL container exists.

az cosmosdb sql container exists --account-name
                                 --database-name
                                 --name
                                 --resource-group

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container list

Edit

List the SQL containers under an Azure Cosmos DB SQL database.

az cosmosdb sql container list --account-name
                               --database-name
                               --resource-group

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container merge

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Merges the partitions of a sql container.

az cosmosdb sql container merge --account-name
                                --database-name
                                --name
                                --resource-group

Examples

merge partitions of container my-container

az cosmosdb sql container merge -g my-resource-group -a my-account -d my-db --name my-container

Required Parameters

--account-name -a

Name of the CosmosDB database account.

--database-name -d

Name of the CosmosDB database name.

--name -n

Name of the CosmosDB collection.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container redistribute-partition-throughput

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Redistributes the partition throughput of a sql container.

az cosmosdb sql container redistribute-partition-throughput --account-name
                                                            --database-name
                                                            --name
                                                            --resource-group
                                                            [--evenly-distribute {false, true}]
                                                            [--source-partition-info]
                                                            [--target-partition-info]

Examples

Evenly distributes the partition throughput for a sql container among all physical partitions

az cosmosdb sql container redistribute-partition-throughput --account-name account_name --database-name db_name --name container_name  --resource-group rg_name --evenly-distribute

Redistributes the partition throughput for a sql container from source partitions to target partitions

az cosmosdb sql container redistribute-partition-throughput --account-name account_name --database-name db_name --name container_name  --resource-group rg_name --target-partition-info 8=1200 6=1200]' --source-partition-info 9]'

Required Parameters

--account-name -a

Name of the CosmosDB database account.

--database-name -d

Name of the CosmosDB database name.

--name -n

Name of the CosmosDB collection.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--evenly-distribute

Switch to distribute throughput equally among all physical partitions.

Accepted values: false, true
Default value: False
--source-partition-info

Space separated source physical partition ids eg: 1 2.

Default value: []
--target-partition-info

Information about desired target physical partition throughput eg: 0=1200 1=1200.

Default value: []
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container restore

Edit

Restore a deleted sql container within the same account.

az cosmosdb sql container restore --account-name
                                  --database-name
                                  --name
                                  --resource-group
                                  [--disable-ttl]
                                  [--restore-timestamp]

Examples

Restore a deleted sql container within the same account.

az cosmosdb sql container restore --resource-group resource_group --account-name database_account_name --database-name parent_database_name --name name_of_container_needs_to_be_restored --restore-timestamp 2020-07-13T16:03:41+0000

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--disable-ttl

Flag to restore with TTL disabled.

Usage: --disable-ttl True Default: false.

--restore-timestamp -t

The timestamp to which the container needs to be restored to.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container restore (cosmosdb-preview extension)

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Restore a deleted sql container within the same account.

az cosmosdb sql container restore --account-name
                                  --database-name
                                  --name
                                  --resource-group
                                  [--disable-ttl {false, true}]
                                  [--restore-timestamp]

Examples

Restore a deleted sql container within the same account.

az cosmosdb sql container restore --resource-group resource_group --account-name database_account_name --database-name parent_database_name --name name_of_container_needs_to_be_restored --restore-timestamp 2020-07-13T16:03:41+0000

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--disable-ttl
Preview

Enable or disable restoring with ttl disabled.

Accepted values: false, true
--restore-timestamp -t

The timestamp to which the container needs to be restored to.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container retrieve-partition-throughput

Preview

This command is in preview and under development. Reference and support levels: https://aka.ms/CLI_refstatus

Retrieve the partition throughput of a sql container.

az cosmosdb sql container retrieve-partition-throughput --account-name
                                                        --database-name
                                                        --name
                                                        --resource-group
                                                        [--all-partitions {false, true}]
                                                        [--physical-partition-ids]

Examples

Retrieve container container_name's throughput for specific physical partitions

az cosmosdb sql container retrieve-partition-throughput --account-name account_name --database-name db_name --name container_name  --resource-group rg_name --physical-partition-ids 8 9

Retrieve container container_name's throughput for all physical partitions

az cosmosdb sql container retrieve-partition-throughput --account-name account_name --database-name db_name --name container_name  --resource-group rg_name --all-partitions

Required Parameters

--account-name -a

Name of the CosmosDB database account.

--database-name -d

Name of the CosmosDB database name.

--name -n

Name of the CosmosDB container.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--all-partitions

Switch to retrieve throughput for all physical partitions.

Accepted values: false, true
Default value: False
--physical-partition-ids -p

Space separated list of physical partition ids.

Default value: []
Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container show

Edit

Show the details of a SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container show --account-name
                               --database-name
                               --name
                               --resource-group

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container update

Edit

Update an SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container update --account-name
                                 --database-name
                                 --name
                                 --resource-group
                                 [--analytical-storage-ttl]
                                 [--idx]
                                 [--ttl]

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--analytical-storage-ttl -t

Analytical TTL, when analytical storage is enabled.

--idx

Indexing Policy, you can enter it as a string or as a file, e.g., --idx @policy-file.json or --idx "{"indexingMode": "consistent", "automatic": true, "includedPaths": [{"path": "/*"}], "excludedPaths": [{ "path": "/headquarters/employees/?"}, { "path": "/\"_etag\"/?"}]}".

--ttl

Default TTL. If the value is missing or set to "-1", items don’t expire. If the value is set to "n", items will expire "n" seconds after last modified time.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.

az cosmosdb sql container update (cosmosdb-preview extension)

Update an SQL container under an Azure Cosmos DB SQL database.

az cosmosdb sql container update --account-name
                                 --database-name
                                 --name
                                 --resource-group
                                 [--analytical-storage-ttl]
                                 [--idx]
                                 [--materialized-view-definition]
                                 [--ttl]

Required Parameters

--account-name -a

Cosmosdb account name.

--database-name -d

Database name.

--name -n

Container name.

--resource-group -g

Name of resource group. You can configure the default group using az configure --defaults group=<name>.

Optional Parameters

--analytical-storage-ttl -t

Analytical TTL, when analytical storage is enabled.

--idx

Indexing Policy, you can enter it as a string or as a file, e.g., --idx @policy-file.json or --idx "{ "indexingMode": "consistent", "automatic": true, "includedPaths": [{"path": "/*"}], "excludedPaths": [{ "path": "/headquarters/employees/?"}, { "path": "/\"_etag\"/?"}] }".

--materialized-view-definition -m

Materialized View Definition, you can enter it as a string or as a file, e.g., --materialized-view-definition @materializedview-definition-file.json or --materialized-view-definition -m '{ "sourceCollectionId": "MySourceCollectionName", "definition": "SELECT * FROM root r"}'.

--ttl

Default TTL. If the value is missing or set to "-1", items don’t expire. If the value is set to "n", items will expire "n" seconds after last modified time.

Global Parameters
--debug

Increase logging verbosity to show all debug logs.

--help -h

Show this help message and exit.

--only-show-errors

Only show errors, suppressing warnings.

--output -o

Output format.

Accepted values: json, jsonc, none, table, tsv, yaml, yamlc
Default value: json
--query

JMESPath query string. See http://jmespath.org/ for more information and examples.

--subscription

Name or ID of subscription. You can configure the default subscription using az account set -s NAME_OR_ID.

--verbose

Increase logging verbosity. Use --debug for full debug logs.