Share via


CosmosDatabase.CreateContainerIfNotExistsAsync Method

Definition

Overloads

CreateContainerIfNotExistsAsync(ContainerProperties, Nullable<Int32>, RequestOptions, CancellationToken)

Check if a container exists, and if it doesn't, create it. Only the container id is used to verify if there is an existing container. Other container properties such as throughput are not validated and can be different then the passed properties.

CreateContainerIfNotExistsAsync(String, String, Nullable<Int32>, RequestOptions, CancellationToken)

Check if a container exists, and if it doesn't, create it. This will make a read operation, and if the container is not found it will do a create operation.

CreateContainerIfNotExistsAsync(ContainerProperties, Nullable<Int32>, RequestOptions, CancellationToken)

Check if a container exists, and if it doesn't, create it. Only the container id is used to verify if there is an existing container. Other container properties such as throughput are not validated and can be different then the passed properties.

public abstract System.Threading.Tasks.Task<Azure.Cosmos.ContainerResponse> CreateContainerIfNotExistsAsync (Azure.Cosmos.ContainerProperties containerProperties, int? throughput = default, Azure.Cosmos.RequestOptions requestOptions = default, System.Threading.CancellationToken cancellationToken = default);
abstract member CreateContainerIfNotExistsAsync : Azure.Cosmos.ContainerProperties * Nullable<int> * Azure.Cosmos.RequestOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Cosmos.ContainerResponse>
Public MustOverride Function CreateContainerIfNotExistsAsync (containerProperties As ContainerProperties, Optional throughput As Nullable(Of Integer) = Nothing, Optional requestOptions As RequestOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ContainerResponse)

Parameters

containerProperties
ContainerProperties

The ContainerProperties object.

throughput
Nullable<Int32>

(Optional) The throughput provisioned for a container in measurement of Requests Units per second in the Azure Cosmos DB service.

requestOptions
RequestOptions

(Optional) The options for the container request RequestOptions

cancellationToken
CancellationToken

(Optional) CancellationToken representing request cancellation.

Returns

A Task containing a Response which wraps a ContainerProperties containing the read resource record.

Exceptions

If either containerProperties is not set.

Represents a consolidation of failures that occurred during async processing. Look within InnerExceptions to find the actual exception(s).

This exception can encapsulate many different types of errors. To determine the specific error always look at the StatusCode property. Some common codes you may get when creating a container are:

StatusCodeReason for exception
400BadRequest - This means something was wrong with the request supplied. It is likely that an id was not supplied for the new container.
403Forbidden - This means you attempted to exceed your quota for containers. Contact support to have this quota increased.
409Conflict - This means a ContainerProperties with an id matching the id you supplied already existed.

Examples

ContainerProperties containerProperties = new ContainerProperties()
{
    Id = Guid.NewGuid().ToString(),
    PartitionKeyPath = "/pk",
    IndexingPolicy = new IndexingPolicy()
   {
        Automatic = false,
        IndexingMode = IndexingMode.Lazy,
   };
};

ContainerResponse response = await this.cosmosDatabase.CreateContainerIfNotExistsAsync(containerProperties);

Remarks

https://docs.microsoft.com/azure/cosmos-db/request-units for details on provision throughput.

Applies to

CreateContainerIfNotExistsAsync(String, String, Nullable<Int32>, RequestOptions, CancellationToken)

Check if a container exists, and if it doesn't, create it. This will make a read operation, and if the container is not found it will do a create operation.

public abstract System.Threading.Tasks.Task<Azure.Cosmos.ContainerResponse> CreateContainerIfNotExistsAsync (string id, string partitionKeyPath, int? throughput = default, Azure.Cosmos.RequestOptions requestOptions = default, System.Threading.CancellationToken cancellationToken = default);
abstract member CreateContainerIfNotExistsAsync : string * string * Nullable<int> * Azure.Cosmos.RequestOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Azure.Cosmos.ContainerResponse>
Public MustOverride Function CreateContainerIfNotExistsAsync (id As String, partitionKeyPath As String, Optional throughput As Nullable(Of Integer) = Nothing, Optional requestOptions As RequestOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of ContainerResponse)

Parameters

id
String

The cosmos container id

partitionKeyPath
String

The path to the partition key. Example: /location

throughput
Nullable<Int32>

(Optional) The throughput provisioned for a container in measurement of Request Units per second in the Azure Cosmos DB service.

requestOptions
RequestOptions

(Optional) The options for the container request RequestOptions

cancellationToken
CancellationToken

(Optional) CancellationToken representing request cancellation.

Returns

A Task containing a Response which wraps a ContainerProperties containing the read resource record.

Exceptions

If id is not set.

Represents a consolidation of failures that occurred during async processing. Look within InnerExceptions to find the actual exception(s).

This exception can encapsulate many different types of errors. To determine the specific error always look at the StatusCode property. Some common codes you may get when creating a container are:

StatusCodeReason for exception
400BadRequest - This means something was wrong with the request supplied. It is likely that an id was not supplied for the new container.
403Forbidden - This means you attempted to exceed your quota for containers. Contact support to have this quota increased.
409Conflict - This means a ContainerProperties with an id matching the id you supplied already existed.

Examples

ContainerResponse response = await this.cosmosDatabase.CreateContainerIfNotExistsAsync(Guid.NewGuid().ToString(), "/pk");

Remarks

https://docs.microsoft.com/azure/cosmos-db/request-units for details on provision throughput.

Applies to