CosmosContainer Class
- java.
lang. Object - com.
azure. cosmos. CosmosContainer
- com.
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
Methods inherited from java.lang.Object
Method Details
createItem
public CosmosItemResponse
Creates a new item synchronously and returns its respective Cosmos item response.
Parameters:
Returns:
createItem
public CosmosItemResponse
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:
Returns:
createItem
public CosmosItemResponse
Creates a new item synchronously and returns its respective Cosmos item response while specifying additional options.
Parameters:
Returns:
deleteItem
public CosmosItemResponse
Deletes an item in the current container.
Parameters:
Returns:
patchItem
public CosmosItemResponse
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:
Returns:
patchItem
public CosmosItemResponse
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:
Returns:
queryChangeFeed
public CosmosPagedIterable
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:
Returns:
queryItems
public CosmosPagedIterable
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:
Returns:
queryItems
public CosmosPagedIterable
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:
Returns:
readAllItems
public CosmosPagedIterable
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:
Returns:
readAllItems
public CosmosPagedIterable
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:
Returns:
readItem
public CosmosItemResponse
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:
Returns:
readItem
public CosmosItemResponse
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:
Returns:
readMany
public FeedResponse
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:
Returns:
readMany
public FeedResponse
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:
Returns:
readMany
public FeedResponse
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:
Returns:
replaceItem
public CosmosItemResponse
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:
Returns:
upsertItem
public CosmosItemResponse
Upserts an Cosmos item in the current container.
Parameters:
Returns:
upsertItem
public CosmosItemResponse
Upserts a item Cosmos sync item while specifying additional options.
Parameters:
Returns:
upsertItem
public CosmosItemResponse
Upserts an item Cosmos sync item while specifying additional options.
Parameters:
Returns:
executeBulkOperations
public Iterable<>
Executes list of operations in Bulk.
Parameters:
Returns:
executeBulkOperations
public Iterable<>
Executes list of operations in Bulk.
Parameters:
Returns:
delete
public CosmosContainerResponse delete()
Deletes the current cosmos container.
Returns:
delete
public CosmosContainerResponse delete(CosmosContainerRequestOptions options)
Deletes the current Cosmos container while specifying additional options such as If-Match.
Parameters:
Returns:
deleteAllItemsByPartitionKey
public CosmosItemResponse
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:
Returns:
deleteItem
public CosmosItemResponse
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:
Returns:
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:
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:
Returns:
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:
Returns:
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
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:
getId
public String getId()
Gets the current container id.
Returns:
getScripts
public CosmosScripts getScripts()
Gets the Cosmos scripts using the current container as context.
Returns:
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:
read
public CosmosContainerResponse read()
Reads the current container.
Returns:
read
public CosmosContainerResponse read(CosmosContainerRequestOptions options)
Reads the current container while specifying additional options such as If-Match.
Parameters:
Returns:
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:
replace
public CosmosContainerResponse replace(CosmosContainerProperties containerProperties)
Replaces the current container properties.
Parameters:
Returns:
replace
public CosmosContainerResponse replace(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options)
Replaces the current container properties while specifying additional options such as If-Match.
Parameters:
Returns:
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:
Returns:
Applies to
Azure SDK for Java
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for