CosmosDatabase.CreateContainerIfNotExistsAsync Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
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.
(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:
| StatusCode | Reason for exception |
|---|---|
| 400 | BadRequest - This means something was wrong with the request supplied. It is likely that an id was not supplied for the new container. |
| 403 | Forbidden - This means you attempted to exceed your quota for containers. Contact support to have this quota increased. |
| 409 | Conflict - 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
(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:
| StatusCode | Reason for exception |
|---|---|
| 400 | BadRequest - This means something was wrong with the request supplied. It is likely that an id was not supplied for the new container. |
| 403 | Forbidden - This means you attempted to exceed your quota for containers. Contact support to have this quota increased. |
| 409 | Conflict - 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
Azure SDK for .NET