Share via

CosmosContainer Class

  • Reference
Package:
com.azure.cosmos
Maven Artifact:
com.azure:azure-cosmos:4.63.4
  • java.lang.Object
    • com.azure.cosmos.CosmosContainer

public class CosmosContainer

Provides synchronous methods for reading, deleting, and replacing existing Containers Provides methods for interacting with child resources (Items, Scripts, Conflicts)

Method Summary

Modifier and Type Method and Description
CosmosItemResponse<T> createItem(T item)

Creates a new item synchronously and returns its respective Cosmos item response.
CosmosItemResponse<T> createItem(T item, CosmosItemRequestOptions options)

Creates a new item synchronously and returns its respective Cosmos item response while specifying additional options.
CosmosItemResponse<T> createItem(T item, PartitionKey partitionKey, CosmosItemRequestOptions options)

Creates a new item synchronously and returns its respective Cosmos item response while specifying additional options.
CosmosItemResponse<Object> deleteItem(T item, CosmosItemRequestOptions options)

Deletes an item in the current container.
CosmosItemResponse<T> patchItem(String itemId, PartitionKey partitionKey, CosmosPatchOperations cosmosPatchOperations, CosmosPatchItemRequestOptions options, Class<T> itemType)

Run partial update that modifies specific properties or fields of the item without replacing the entire item.
CosmosItemResponse<T> patchItem(String itemId, PartitionKey partitionKey, CosmosPatchOperations cosmosPatchOperations, Class<T> itemType)

Run partial update that modifies specific properties or fields of the item without replacing the entire item.
CosmosPagedIterable<T> queryChangeFeed(CosmosChangeFeedRequestOptions options, Class<T> classType)

Query for items in the change feed of the current container using the CosmosChangeFeedRequestOptions.
CosmosPagedIterable<T> queryItems(SqlQuerySpec querySpec, CosmosQueryRequestOptions options, Class<T> classType)

Query items in the current container returning the results as CosmosPagedIterable<T>.
CosmosPagedIterable<T> queryItems(String query, CosmosQueryRequestOptions options, Class<T> classType)

Query items in the current container returning the results as CosmosPagedIterable<T>.
CosmosPagedIterable<T> readAllItems(PartitionKey partitionKey, CosmosQueryRequestOptions options, Class<T> classType)

Reads all the items of a logical partition returning the results as CosmosPagedIterable<T>.
CosmosPagedIterable<T> readAllItems(PartitionKey partitionKey, Class<T> classType)

Reads all the items of a logical partition returning the results as CosmosPagedIterable<T>.
CosmosItemResponse<T> readItem(String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options, Class<T> itemType)

Reads an item in the current container while specifying additional options.
CosmosItemResponse<T> readItem(String itemId, PartitionKey partitionKey, Class<T> itemType)

Reads an item in the current container.
FeedResponse<T> readMany(List<CosmosItemIdentity> itemIdentityList, CosmosReadManyRequestOptions options, Class<T> classType)

Reads many documents.
FeedResponse<T> readMany(List<CosmosItemIdentity> itemIdentityList, Class<T> classType)

Reads many documents.
FeedResponse<T> readMany(List<CosmosItemIdentity> itemIdentityList, String sessionToken, Class<T> classType)

Reads many documents.
CosmosItemResponse<T> replaceItem(T item, String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options)

Replaces an existing item in a container with a new item.
CosmosItemResponse<T> upsertItem(T item)

Upserts an Cosmos item in the current container.
CosmosItemResponse<T> upsertItem(T item, CosmosItemRequestOptions options)

Upserts a item Cosmos sync item while specifying additional options.
CosmosItemResponse<T> upsertItem(T item, PartitionKey partitionKey, CosmosItemRequestOptions options)

Upserts an item Cosmos sync item while specifying additional options.
Iterable<CosmosBulkOperationResponse<TContext>> executeBulkOperations(Iterable<CosmosItemOperation> operations)

Executes list of operations in Bulk.
Iterable<CosmosBulkOperationResponse<TContext>> executeBulkOperations(Iterable<CosmosItemOperation> operations, CosmosBulkExecutionOptions bulkOptions)

Executes list of operations in Bulk.
CosmosContainerResponse delete()

Deletes the current cosmos container.
CosmosContainerResponse delete(CosmosContainerRequestOptions options)

Deletes the current Cosmos container while specifying additional options such as If-Match.
CosmosItemResponse<Object> deleteAllItemsByPartitionKey(PartitionKey partitionKey, CosmosItemRequestOptions options)

Deletes all items in the Container with the specified partitionKey value.
CosmosItemResponse<Object> deleteItem(String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options)

Deletes an item in the current container.
void enableGlobalThroughputControlGroup(ThroughputControlGroupConfig groupConfig, GlobalThroughputControlConfig globalControlConfig)

Enable the throughput control group with global control mode.
void enableLocalThroughputControlGroup(ThroughputControlGroupConfig groupConfig)

Enable the throughput control group with local control mode.
CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch)

Executes the transactional batch.
CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch, CosmosBatchRequestOptions requestOptions)

Executes the transactional batch.
List<FeedRange> getFeedRanges()

Obtains a list of FeedRange that can be used to parallelize Feed operations.
String getId()

Gets the current container id.
CosmosScripts getScripts()

Gets the Cosmos scripts using the current container as context.
void openConnectionsAndInitCaches()

Deprecated

Initializes the container by warming up the caches and connections for the current read region.
void openConnectionsAndInitCaches(int numProactiveConnectionRegions)

Deprecated

Initializes the container by warming up the caches and connections to a specified no.
CosmosContainerResponse read()

Reads the current container.
CosmosContainerResponse read(CosmosContainerRequestOptions options)

Reads the current container while specifying additional options such as If-Match.
ThroughputResponse readThroughput()

Gets the throughput for the current container.
CosmosContainerResponse replace(CosmosContainerProperties containerProperties)

Replaces the current container properties.
CosmosContainerResponse replace(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options)

Replaces the current container properties while specifying additional options such as If-Match.
ThroughputResponse replaceThroughput(ThroughputProperties throughputProperties)

Sets the throughput for the current container.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Method Details

createItem

public CosmosItemResponse createItem(T item)

Creates a new item synchronously and returns its respective Cosmos item response.

Parameters:

item - the item

Returns:

the Cosmos item response

createItem

public CosmosItemResponse createItem(T item, CosmosItemRequestOptions options)

Creates a new item synchronously and returns its respective Cosmos item response while specifying additional options.

The partition key value will be automatically extracted from the item's content.

Parameters:

item - the item.
options - the options.

Returns:

the cosmos item response.

createItem

public CosmosItemResponse createItem(T item, PartitionKey partitionKey, CosmosItemRequestOptions options)

Creates a new item synchronously and returns its respective Cosmos item response while specifying additional options.

Parameters:

item - the item.
partitionKey - the partition key.
options - the options.

Returns:

the Cosmos item response.

deleteItem

public CosmosItemResponse deleteItem(T item, CosmosItemRequestOptions options)

Deletes an item in the current container.

Parameters:

item - the item to be deleted.
options - the options.

Returns:

the Cosmos item response.

patchItem

public CosmosItemResponse patchItem(String itemId, PartitionKey partitionKey, CosmosPatchOperations cosmosPatchOperations, CosmosPatchItemRequestOptions options, Class itemType)

Run partial update that modifies specific properties or fields of the item without replacing the entire item.

CosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();

 cosmosPatchOperations
     .add("/departure", "SEA")
     .increment("/trips", 1);

 CosmosItemResponse<Passenger> response = cosmosContainer.patchItem(
     passenger.getId(),
     new PartitionKey(passenger.getId()),
     cosmosPatchOperations,
     Passenger.class);

Parameters:

itemId - the item id.
partitionKey - the partition key.
cosmosPatchOperations - Represents a container having list of operations to be sequentially applied to the referred Cosmos item.
options - the request options.
itemType - the item type.

Returns:

the Cosmos item resource response with the patched item or an exception.

patchItem

public CosmosItemResponse patchItem(String itemId, PartitionKey partitionKey, CosmosPatchOperations cosmosPatchOperations, Class itemType)

Run partial update that modifies specific properties or fields of the item without replacing the entire item.

CosmosPatchOperations cosmosPatchOperations = CosmosPatchOperations.create();

 cosmosPatchOperations
     .add("/departure", "SEA")
     .increment("/trips", 1);

 CosmosItemResponse<Passenger> response = cosmosContainer.patchItem(
     passenger.getId(),
     new PartitionKey(passenger.getId()),
     cosmosPatchOperations,
     Passenger.class);

Parameters:

itemId - the item id.
partitionKey - the partition key.
cosmosPatchOperations - Represents a container having list of operations to be sequentially applied to the referred Cosmos item.
itemType - the item type.

Returns:

the Cosmos item resource response with the patched item or an exception.

queryChangeFeed

public CosmosPagedIterable queryChangeFeed(CosmosChangeFeedRequestOptions options, Class classType)

Query for items in the change feed of the current container using the CosmosChangeFeedRequestOptions.

CosmosChangeFeedRequestOptions options = CosmosChangeFeedRequestOptions
     .createForProcessingFromNow(FeedRange.forFullRange())
     .allVersionsAndDeletes();

 Iterable<FeedResponse<Passenger>> feedResponses = cosmosContainer.queryChangeFeed(options, Passenger.class)
     .iterableByPage();
 for (FeedResponse<Passenger> feedResponse : feedResponses) {
     List<Passenger> results = feedResponse.getResults();
     System.out.println(results);
 }

The next page can be retrieved by calling queryChangeFeed again with a new instance of CosmosChangeFeedRequestOptions created from the continuation token of the previously returned FeedResponse<T> instance.

Parameters:

options - the change feed request options.
classType - the class type.

Returns:

a CosmosPagedFlux<T> containing one feed response page

queryItems

public CosmosPagedIterable queryItems(SqlQuerySpec querySpec, CosmosQueryRequestOptions options, Class classType)

Query items in the current container returning the results as CosmosPagedIterable<T>.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
 String query = "SELECT * FROM Passenger p WHERE (p.departure = @departure)";
 List<SqlParameter> parameters = Collections.singletonList(new SqlParameter("@departure", "SEA"));
 SqlQuerySpec sqlQuerySpec = new SqlQuerySpec(query, parameters);

 Iterable<FeedResponse<Passenger>> queryResponses = cosmosContainer.queryItems(sqlQuerySpec, options, Passenger.class)
     .iterableByPage();

 for (FeedResponse<Passenger> feedResponse : queryResponses) {
     List<Passenger> results = feedResponse.getResults();
     System.out.println(results);
 }

Parameters:

querySpec - the query spec.
options - the options.
classType - the class type.

Returns:

queryItems

public CosmosPagedIterable queryItems(String query, CosmosQueryRequestOptions options, Class classType)

Query items in the current container returning the results as CosmosPagedIterable<T>.

CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
 String query = "SELECT * FROM Passenger WHERE Passenger.departure IN ('SEA', 'IND')";
 Iterable<FeedResponse<Passenger>> queryResponses = cosmosContainer.queryItems(query, options, Passenger.class)
     .iterableByPage();

 for (FeedResponse<Passenger> feedResponse : queryResponses) {
     List<Passenger> results = feedResponse.getResults();
     System.out.println(results);
 }

Parameters:

query - the query.
options - the options.
classType - the class type.

Returns:

readAllItems

public CosmosPagedIterable readAllItems(PartitionKey partitionKey, CosmosQueryRequestOptions options, Class classType)

Reads all the items of a logical partition returning the results as CosmosPagedIterable<T>.

CosmosPagedIterable<Passenger> passengers = cosmosContainer
     .readAllItems(new PartitionKey(partitionKey), Passenger.class);

 passengers.forEach(passenger -> {
     System.out.println(passenger);
 });

Parameters:

partitionKey - the partition key value of the documents that need to be read
options - the feed options.
classType - the class type.

Returns:

readAllItems

public CosmosPagedIterable readAllItems(PartitionKey partitionKey, Class classType)

Reads all the items of a logical partition returning the results as CosmosPagedIterable<T>.

CosmosPagedIterable<Passenger> passengers = cosmosContainer
     .readAllItems(new PartitionKey(partitionKey), Passenger.class);

 passengers.forEach(passenger -> {
     System.out.println(passenger);
 });

Parameters:

partitionKey - the partition key value of the documents that need to be read
classType - the class type.

Returns:

readItem

public CosmosItemResponse readItem(String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options, Class itemType)

Reads an item in the current container while specifying additional options. This operation is used to retrieve a single item from a container based on its unique identifier (ID) and partition key. The readItem operation provides direct access to a specific item using its unique identifier, which consists of the item's ID and the partition key value. This operation is efficient for retrieving a known item by its ID and partition key without the need for complex querying.

Parameters:

itemId - the item id.
partitionKey - the partition key.
options - the options (Optional).
itemType - the class type of item.

Returns:

the Cosmos item response.

readItem

public CosmosItemResponse readItem(String itemId, PartitionKey partitionKey, Class itemType)

Reads an item in the current container. This operation is used to retrieve a single item from a container based on its unique identifier (ID) and partition key. The readItem operation provides direct access to a specific item using its unique identifier, which consists of the item's ID and the partition key value. This operation is efficient for retrieving a known item by its ID and partition key without the need for complex querying.

// Read an item
 try {
     CosmosItemResponse<Passenger> response = cosmosContainer.readItem(
         passenger.getId(),
         new PartitionKey(passenger.getId()),
         Passenger.class
     );
     Passenger passengerItem = response.getItem();
 } catch (NotFoundException e) {
     // catch exception if item not found
     System.out.printf("Passenger with item id %s not found\n",
         passenger.getId());
 } catch (Exception e) {
     System.out.println(e.getMessage());
 }

 // ...

Parameters:

itemId - the item id.
partitionKey - the partition key.
itemType - the class type of item.

Returns:

the Cosmos item response.

readMany

public FeedResponse readMany(List itemIdentityList, CosmosReadManyRequestOptions options, Class classType)

Reads many documents. Useful for reading many documents with a particular id and partition key in a single request. If any document from the list is missing, no exception will be thrown.

List<CosmosItemIdentity> itemIdentityList = new ArrayList<>();
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger1Id), passenger1Id));
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger2Id), passenger2Id));

 FeedResponse<Passenger> passengerFeedResponse = cosmosContainer.readMany(itemIdentityList, Passenger.class);
 for (Passenger passenger : passengerFeedResponse.getResults()) {
     System.out.println(passenger);
 }

Parameters:

itemIdentityList - CosmosItem id and partition key tuple of items that that needs to be read
options - the optional request options
classType - class type

Returns:

a Mono with feed response of cosmos items

readMany

public FeedResponse readMany(List itemIdentityList, Class classType)

Reads many documents. Useful for reading many documents with a particular id and partition key in a single request. If any document from the list is missing, no exception will be thrown.

List<CosmosItemIdentity> itemIdentityList = new ArrayList<>();
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger1Id), passenger1Id));
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger2Id), passenger2Id));

 FeedResponse<Passenger> passengerFeedResponse = cosmosContainer.readMany(itemIdentityList, Passenger.class);
 for (Passenger passenger : passengerFeedResponse.getResults()) {
     System.out.println(passenger);
 }

Parameters:

itemIdentityList - CosmosItem id and partition key tuple of items that that needs to be read
classType - class type

Returns:

a Mono with feed response of cosmos items

readMany

public FeedResponse readMany(List itemIdentityList, String sessionToken, Class classType)

Reads many documents. Useful for reading many documents with a particular id and partition key in a single request. If any document from the list is missing, no exception will be thrown.

List<CosmosItemIdentity> itemIdentityList = new ArrayList<>();
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger1Id), passenger1Id));
 itemIdentityList.add(new CosmosItemIdentity(new PartitionKey(passenger2Id), passenger2Id));

 FeedResponse<Passenger> passengerFeedResponse = cosmosContainer.readMany(itemIdentityList, Passenger.class);
 for (Passenger passenger : passengerFeedResponse.getResults()) {
     System.out.println(passenger);
 }

Parameters:

itemIdentityList - CosmosItem id and partition key tuple of items that that needs to be read
sessionToken - the optional Session token - null if the read can be made without specific session token
classType - class type

Returns:

a Mono with feed response of cosmos items

replaceItem

public CosmosItemResponse replaceItem(T item, String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options)

Replaces an existing item in a container with a new item. It performs a complete replacement of the item, replacing all its properties with the properties of the new item

CosmosItemResponse<Passenger> response = cosmosContainer.replaceItem(
     newPassenger,
     oldPassenger.getId(),
     new PartitionKey(oldPassenger.getId()),
     new CosmosItemRequestOptions());

Parameters:

item - the item.
itemId - the item id.
partitionKey - the partition key.
options - the options.

Returns:

the Cosmos item response.

upsertItem

public CosmosItemResponse upsertItem(T item)

Upserts an Cosmos item in the current container.

Parameters:

item - the item.

Returns:

the Cosmos item response.

upsertItem

public CosmosItemResponse upsertItem(T item, CosmosItemRequestOptions options)

Upserts a item Cosmos sync item while specifying additional options.

Parameters:

item - the item.
options - the options.

Returns:

the Cosmos item response.

upsertItem

public CosmosItemResponse upsertItem(T item, PartitionKey partitionKey, CosmosItemRequestOptions options)

Upserts an item Cosmos sync item while specifying additional options.

Parameters:

item - the item.
partitionKey - the partitionKey.
options - the options.

Returns:

the Cosmos item response.

executeBulkOperations

public Iterable> executeBulkOperations(Iterable operations)

Executes list of operations in Bulk.

Parameters:

operations - list of operation which will be executed by this container.

Returns:

An Iterable of CosmosBulkOperationResponse<TContext> which contains operation and it's response or exception. To create a operation which can be executed here, use CosmosBulkOperations. For eg. for a upsert operation use com.azure.cosmos.models.CosmosBulkOperations#getUpsertItemOperation(Object, PartitionKey) We can get the corresponding operation using getOperation() and it's response using getResponse(). If the operation was executed successfully, the value returned by isSuccessStatusCode() will be true. To get actual status use getStatusCode(). To check if the operation had any exception, use getException() to get the exception.

executeBulkOperations

public Iterable> executeBulkOperations(Iterable operations, CosmosBulkExecutionOptions bulkOptions)

Executes list of operations in Bulk.

Parameters:

operations - list of operation which will be executed by this container.
bulkOptions - Options that apply for this Bulk request which specifies options regarding execution like concurrency, batching size, interval and context.

Returns:

An Iterable of CosmosBulkOperationResponse<TContext> which contains operation and it's response or exception. To create a operation which can be executed here, use CosmosBulkOperations. For eg. for a upsert operation use com.azure.cosmos.models.CosmosBulkOperations#getUpsertItemOperation(Object, PartitionKey) We can get the corresponding operation using getOperation() and it's response using getResponse(). If the operation was executed successfully, the value returned by isSuccessStatusCode() will be true. To get actual status use getStatusCode(). To check if the operation had any exception, use getException() to get the exception.

delete

public CosmosContainerResponse delete()

Deletes the current cosmos container.

Returns:

the cosmos container response.

delete

public CosmosContainerResponse delete(CosmosContainerRequestOptions options)

Deletes the current Cosmos container while specifying additional options such as If-Match.

Parameters:

options - the options.

Returns:

the cosmos container response.

deleteAllItemsByPartitionKey

public CosmosItemResponse deleteAllItemsByPartitionKey(PartitionKey partitionKey, CosmosItemRequestOptions options)

Deletes all items in the Container with the specified partitionKey value. Starts an asynchronous Cosmos DB background operation which deletes all items in the Container with the specified value. The asynchronous Cosmos DB background operation runs using a percentage of user RUs.

Parameters:

partitionKey - the partition key.
options - the options.

Returns:

the Cosmos item response

deleteItem

public CosmosItemResponse deleteItem(String itemId, PartitionKey partitionKey, CosmosItemRequestOptions options)

Deletes an item in the current container.

try {
     CosmosItemRequestOptions options = new CosmosItemRequestOptions();
     CosmosItemResponse<Object> deleteItemResponse = cosmosContainer.deleteItem(
         passenger.getId(),
         new PartitionKey(passenger.getId()),
         options
     );
     System.out.println(deleteItemResponse);
 } catch (NotFoundException e) {
     // catch exception if item not found
     System.out.printf("Passenger with item id %s not found\n",
         passenger.getId());
 } catch (Exception e) {
     System.out.println(e.getMessage());
 }

Parameters:

itemId - the item id.
partitionKey - the partition key.
options - the options.

Returns:

the Cosmos item response.

enableGlobalThroughputControlGroup

public void enableGlobalThroughputControlGroup(ThroughputControlGroupConfig groupConfig, GlobalThroughputControlConfig globalControlConfig)

Enable the throughput control group with global control mode. The defined throughput limit will be shared across different clients.

ThroughputControlGroupConfig groupConfig =
     new ThroughputControlGroupConfigBuilder()
         .groupName("localControlGroup")
         .targetThroughputThreshold(0.1)
         .build();

 GlobalThroughputControlConfig globalControlConfig =
     this.client.createGlobalThroughputControlConfigBuilder(database.getId(), container.getId())
         .setControlItemRenewInterval(Duration.ofSeconds(5))
         .setControlItemExpireInterval(Duration.ofSeconds(10))
         .build();

 container.enableGlobalThroughputControlGroup(groupConfig, globalControlConfig);

Parameters:

groupConfig - The throughput control group configuration, see GlobalThroughputControlGroup.
globalControlConfig - The global throughput control configuration, see GlobalThroughputControlConfig.

enableLocalThroughputControlGroup

public void enableLocalThroughputControlGroup(ThroughputControlGroupConfig groupConfig)

Enable the throughput control group with local control mode.

ThroughputControlGroupConfig groupConfig =
     new ThroughputControlGroupConfigBuilder()
         .groupName("localControlGroup")
         .targetThroughputThreshold(0.1)
         .build();

 container.enableLocalThroughputControlGroup(groupConfig);

Parameters:

executeCosmosBatch

public CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch)

Executes the transactional batch.

Parameters:

cosmosBatch - Batch having list of operation and partition key which will be executed by this container.

Returns:

A TransactionalBatchResponse which contains details of execution of the transactional batch.

If the transactional batch executes successfully, the value returned by CosmosBatchResponse#getStatusCode on the response returned will be set to 200}.

If an operation within the transactional batch fails during execution, no changes from the batch will be committed and the status of the failing operation is made available by CosmosBatchResponse#getStatusCode or by the exception. To obtain information about the operations that failed in case of some user error like conflict, not found etc, the response can be enumerated. This returns CosmosBatchOperationResult instances corresponding to each operation in the transactional batch in the order they were added to the transactional batch. For a result corresponding to an operation within the transactional batch, use CosmosBatchOperationResult#getStatusCode to access the status of the operation. If the operation was not executed or it was aborted due to the failure of another operation within the transactional batch, the value of this field will be 424; for the operation that caused the batch to abort, the value of this field will indicate the cause of failure.

If there are issues such as request timeouts, Gone, session not available, network failure or if the service somehow returns 5xx then this will throw an exception instead of returning a CosmosBatchResponse.

Use CosmosBatchResponse#isSuccessStatusCode on the response returned to ensure that the transactional batch succeeded.

executeCosmosBatch

public CosmosBatchResponse executeCosmosBatch(CosmosBatch cosmosBatch, CosmosBatchRequestOptions requestOptions)

Executes the transactional batch.

Parameters:

cosmosBatch - Batch having list of operation and partition key which will be executed by this container.
requestOptions - Options that apply specifically to batch request.

Returns:

A CosmosBatchResponse which contains details of execution of the transactional batch.

If the transactional batch executes successfully, the value returned by CosmosBatchResponse#getStatusCode on the response returned will be set to 200}.

If an operation within the transactional batch fails during execution, no changes from the batch will be committed and the status of the failing operation is made available by CosmosBatchResponse#getStatusCode or by the exception. To obtain information about the operations that failed in case of some user error like conflict, not found etc, the response can be enumerated. This returns CosmosBatchOperationResult instances corresponding to each operation in the transactional batch in the order they were added to the transactional batch. For a result corresponding to an operation within the transactional batch, use CosmosBatchOperationResult#getStatusCode to access the status of the operation. If the operation was not executed or it was aborted due to the failure of another operation within the transactional batch, the value of this field will be 424; for the operation that caused the batch to abort, the value of this field will indicate the cause of failure.

If there are issues such as request timeouts, Gone, session not available, network failure or if the service somehow returns 5xx then this will throw an exception instead of returning a CosmosBatchResponse.

Use CosmosBatchResponse#isSuccessStatusCode on the response returned to ensure that the transactional batch succeeded.

getFeedRanges

public List getFeedRanges()

Obtains a list of FeedRange that can be used to parallelize Feed operations.

List<FeedRange> feedRanges = cosmosContainer.getFeedRanges();
 for (FeedRange feedRange : feedRanges) {
     System.out.println("Feed range: " + feedRange);
 }

Returns:

An unmodifiable list of FeedRange

getId

public String getId()

Gets the current container id.

Returns:

the container id.

getScripts

public CosmosScripts getScripts()

Gets the Cosmos scripts using the current container as context.

Returns:

the Cosmos sync scripts.

openConnectionsAndInitCaches

@Deprecated
public void openConnectionsAndInitCaches()

Deprecated

Initializes the container by warming up the caches and connections for the current read region.

NOTE: This API ideally should be called only once during application initialization before any workload. In case of any transient error, caller should consume the error and continue the regular workload.

openConnectionsAndInitCaches

@Deprecated
public void openConnectionsAndInitCaches(int numProactiveConnectionRegions)

Deprecated

Initializes the container by warming up the caches and connections to a specified no. of proactive connection regions. For more information about proactive connection regions, see getProactiveConnectionRegionsCount()

NOTE: This API ideally should be called only once during application initialization before any workload. In case of any transient error, caller should consume the error and continue the regular workload.

Parameters:

numProactiveConnectionRegions - the no of regions to proactively connect to from the preferred list of regions

read

public CosmosContainerResponse read()

Reads the current container.

Returns:

the Cosmos container response with the read container.

read

public CosmosContainerResponse read(CosmosContainerRequestOptions options)

Reads the current container while specifying additional options such as If-Match.

Parameters:

options - the options.

Returns:

the Cosmos container response.

readThroughput

public ThroughputResponse readThroughput()

Gets the throughput for the current container.

try {
     ThroughputResponse throughputResponse = cosmosContainer.readThroughput();
     System.out.println(throughputResponse);
 } catch (CosmosException ce) {
     ce.printStackTrace();
 } catch (Exception e) {
     e.printStackTrace();
 }

Returns:

the throughput response.

replace

public CosmosContainerResponse replace(CosmosContainerProperties containerProperties)

Replaces the current container properties.

Parameters:

containerProperties - the container properties.

Returns:

the cosmos container response.

replace

public CosmosContainerResponse replace(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options)

Replaces the current container properties while specifying additional options such as If-Match.

Parameters:

containerProperties - the container properties.
options - the options.

Returns:

the cosmos container response.

replaceThroughput

public ThroughputResponse replaceThroughput(ThroughputProperties throughputProperties)

Sets the throughput for the current container.

ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(1000);
 try {
     ThroughputResponse throughputResponse =
         cosmosContainer.replaceThroughput(throughputProperties);
     System.out.println(throughputResponse);
 } catch (CosmosException ce) {
     ce.printStackTrace();
 } catch (Exception e) {
     e.printStackTrace();
 }

Parameters:

throughputProperties - the throughput properties (Optional).

Returns:

the throughput response.

Applies to