CosmosAsyncContainer Class
- java.
lang. Object - com.
azure. cosmos. CosmosAsyncContainer
- com.
public class CosmosAsyncContainer
Provides 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 Mono
Creates an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single resource response with the created Cosmos item. In case of failure the Mono will error.
Parameters:
Returns:
createItem
public Mono
Creates a Cosmos item.
Parameters:
Returns:
createItem
public Mono
Creates an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single resource response with the created Cosmos item. In case of failure the Mono will error.
Parameters:
Returns:
deleteItem
public Mono
Deletes the item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response for the deleted item.
Parameters:
Returns:
patchItem
public Mono
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);
cosmosAsyncContainer.patchItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
cosmosPatchOperations,
Passenger.class)
.subscribe(response -> {
System.out.println(response);
}, throwable -> {
throwable.printStackTrace();
});
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response with the patched item.
Parameters:
Returns:
patchItem
public Mono
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);
cosmosAsyncContainer.patchItem(
passenger.getId(),
new PartitionKey(passenger.getId()),
cosmosPatchOperations,
Passenger.class)
.subscribe(response -> {
System.out.println(response);
}, throwable -> {
throwable.printStackTrace();
});
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response with the patched item.
Parameters:
Returns:
queryChangeFeed
public CosmosPagedFlux
Query for items in the change feed of the current container using the CosmosChangeFeedRequestOptions.
CosmosChangeFeedRequestOptions options = CosmosChangeFeedRequestOptions
.createForProcessingFromNow(FeedRange.forFullRange())
.allVersionsAndDeletes();
cosmosAsyncContainer.queryChangeFeed(options, Passenger.class)
.byPage()
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The Flux will contain one or several feed response of the obtained items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
queryItems
public CosmosPagedFlux
Query for items in the current container using a SqlQuerySpec and CosmosQueryRequestOptions.
After subscription the operation will be performed. The Flux will contain one or several feed response of the obtained items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
queryItems
public CosmosPagedFlux
Query for items in the current container using a SqlQuerySpec.
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);
cosmosAsyncContainer.queryItems(sqlQuerySpec, options, Passenger.class)
.byPage()
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The CosmosPagedFlux<T> will contain one or several feed response of the obtained items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
queryItems
public CosmosPagedFlux
Query for items in the current container using a string.
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
String query = "SELECT * FROM Passenger WHERE Passenger.departure IN ('SEA', 'IND')";
cosmosAsyncContainer.queryItems(query, options, Passenger.class)
.byPage()
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The CosmosPagedFlux<T> will contain one or several feed response of the obtained items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
queryItems
public CosmosPagedFlux
Query for items in the current container.
CosmosQueryRequestOptions options = new CosmosQueryRequestOptions();
String query = "SELECT * FROM Passenger WHERE Passenger.departure IN ('SEA', 'IND')";
cosmosAsyncContainer.queryItems(query, options, Passenger.class)
.byPage()
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The CosmosPagedFlux<T> will contain one or several feed response of the obtained items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
readAllItems
public CosmosPagedFlux
Reads all the items of a logical partition
cosmosAsyncContainer
.readAllItems(new PartitionKey(partitionKey), Passenger.class)
.byPage(100)
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The CosmosPagedFlux<T> will contain one or several feed responses of the read Cosmos items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
readAllItems
public CosmosPagedFlux
Reads all the items of a logical partition
cosmosAsyncContainer
.readAllItems(new PartitionKey(partitionKey), Passenger.class)
.byPage(100)
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Flux.empty();
})
.subscribe();
After subscription the operation will be performed. The CosmosPagedFlux<T> will contain one or several feed responses of the read Cosmos items. In case of failure the CosmosPagedFlux<T> will error.
Parameters:
Returns:
readItem
public Mono
Reads an item by itemId using a configured CosmosItemRequestOptions. 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.
After subscription the operation will be performed. The Mono upon successful completion will contain a Cosmos item response with the read item.
Parameters:
Returns:
readItem
public Mono
Reads an item by itemId. 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.
After subscription the operation will be performed. The Mono upon successful completion will contain an item response with the read item.
// Read an item
cosmosAsyncContainer.readItem(passenger.getId(), new PartitionKey(passenger.getId()), Passenger.class)
.flatMap(response -> Mono.just(response.getItem()))
.subscribe(passengerItem -> System.out.println(passengerItem), throwable -> {
CosmosException cosmosException = (CosmosException) throwable;
cosmosException.printStackTrace();
});
// ...
Parameters:
Returns:
readMany
public Mono
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));
cosmosAsyncContainer.readMany(itemIdentityList, Passenger.class)
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Mono.empty();
})
.subscribe();
Parameters:
Returns:
readMany
public Mono
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));
cosmosAsyncContainer.readMany(itemIdentityList, Passenger.class)
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Mono.empty();
})
.subscribe();
Parameters:
Returns:
readMany
public Mono
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));
cosmosAsyncContainer.readMany(itemIdentityList, Passenger.class)
.flatMap(passengerFeedResponse -> {
for (Passenger passenger : passengerFeedResponse.getResults()) {
System.out.println(passenger);
}
return Mono.empty();
})
.subscribe();
Parameters:
Returns:
replaceItem
public Mono
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
cosmosAsyncContainer.replaceItem(
newPassenger,
oldPassenger.getId(),
new PartitionKey(oldPassenger.getId()),
new CosmosItemRequestOptions())
.subscribe(response -> {
System.out.println(response);
}, throwable -> {
throwable.printStackTrace();
});
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response with the replaced item.
Parameters:
Returns:
replaceItem
public Mono
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
cosmosAsyncContainer.replaceItem(
newPassenger,
oldPassenger.getId(),
new PartitionKey(oldPassenger.getId()),
new CosmosItemRequestOptions())
.subscribe(response -> {
System.out.println(response);
}, throwable -> {
throwable.printStackTrace();
});
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response with the replaced item.
Parameters:
Returns:
upsertItem
public Mono
Upserts an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single resource response with the upserted item. In case of failure the Mono will error.
Parameters:
Returns:
upsertItem
public Mono
Upserts an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single resource response with the upserted item. In case of failure the Mono will error.
Parameters:
Returns:
upsertItem
public Mono
Upserts an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single resource response with the upserted item. In case of failure the Mono will error.
Parameters:
Returns:
executeBulkOperations
public Flux
Executes flux of operations in Bulk.
Parameters:
Returns:
executeBulkOperations
public Flux
Executes flux of operations in Bulk.
Parameters:
Returns:
delete
public Mono
Deletes the current container.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response for the deleted container. In case of failure the Mono will error.
Returns:
delete
public Mono
Deletes the container
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response for the deleted database. In case of failure the Mono will error.
Parameters:
Returns:
deleteAllItemsByPartitionKey
public Mono
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.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response for all the deleted items.
Parameters:
Returns:
deleteItem
public Mono
Deletes an item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response for the deleted item.
cosmosAsyncContainer.deleteItem(
passenger.getId(),
new PartitionKey(passenger.getId())
).subscribe(response -> {
System.out.println(response);
}, throwable -> {
CosmosException cosmosException = (CosmosException) throwable;
cosmosException.printStackTrace();
});
Parameters:
Returns:
deleteItem
public Mono
Deletes the item.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos item response for the deleted item.
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 Mono
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 the Mono will return error instead of CosmosBatchResponse.
Use CosmosBatchResponse#isSuccessStatusCode on the response returned to ensure that the transactional batch succeeded.
executeCosmosBatch
public Mono
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 the Mono will return error instead of CosmosBatchResponse.
Use CosmosBatchResponse#isSuccessStatusCode on the response returned to ensure that the transactional batch succeeded.
getConflict
public CosmosAsyncConflict getConflict(String id)
Gets a CosmosAsyncConflict object using current container for context.
Parameters:
Returns:
getDatabase
public CosmosAsyncDatabase getDatabase()
Gets the parent CosmosAsyncDatabase for the current container.
Returns:
getFeedRanges
public Mono
Obtains a list of FeedRange that can be used to parallelize Feed operations.
cosmosAsyncContainer.getFeedRanges()
.subscribe(feedRanges -> {
for (FeedRange feedRange : feedRanges) {
System.out.println("Feed range: " + feedRange);
}
});
Returns:
getId
public String getId()
Get the id of the CosmosAsyncContainer.
Returns:
getScripts
public CosmosAsyncScripts getScripts()
Gets a CosmosAsyncScripts using the current container as context.
This can be further used to perform various operations on Cosmos scripts.
Returns:
openConnectionsAndInitCaches
@Deprecated
public Mono
Deprecated
Best effort to initialize the container by warming up the caches and connections for the current read region.
Depending on how many partitions the container has, the total time needed will also change. But generally you can use the following formula to get an estimated time: If it took 200ms to establish a connection, and you have 100 partitions in your container then it will take around (100 * 4 / CPUCores) * 200ms to open all connections after get the address list
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.
Returns:
openConnectionsAndInitCaches
@Deprecated
public Mono
Deprecated
Best effort to initialize the container by warming up the caches and connections to a specified no. of regions from the preferred list of regions.
Depending on how many partitions the container has, the total time needed will also change. But generally you can use the following formula to get an estimated time: If it took 200ms to establish a connection, and you have 100 partitions in your container then it will take around (100 * 4 / (10 * CPUCores)) * 200ms * RegionsWithProactiveConnections to open all connections after get the address list
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.
In order to minimize latencies associated with warming up caches and opening connections the no. of proactive connection regions cannot be more than CosmosContainerProactiveInitConfigBuilder#MAX_NO_OF_PROACTIVE_CONNECTION_REGIONS.
Parameters:
Returns:
queryConflicts
public CosmosPagedFlux
Queries all the conflicts in the current container.
try {
cosmosAsyncContainer.queryConflicts(query).
byPage(100)
.subscribe(response -> {
for (CosmosConflictProperties conflictProperties : response.getResults()) {
System.out.println(conflictProperties);
}
}, throwable -> {
throwable.printStackTrace();
});
} catch (CosmosException ce) {
ce.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
Parameters:
Returns:
queryConflicts
public CosmosPagedFlux
Queries all the conflicts in the current container.
Parameters:
Returns:
read
public Mono
Reads the current container.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response with the read container. In case of failure the Mono will error.
Returns:
read
public Mono
Reads the current container while specifying additional options such as If-Match.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response with the read container. In case of failure the Mono will error.
Parameters:
Returns:
readAllConflicts
public CosmosPagedFlux
Lists all the conflicts in the current container.
try {
cosmosAsyncContainer.readAllConflicts(options).
byPage(100)
.subscribe(response -> {
for (CosmosConflictProperties conflictProperties : response.getResults()) {
System.out.println(conflictProperties);
}
}, throwable -> {
throwable.printStackTrace();
});
} catch (CosmosException ce) {
ce.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
Parameters:
Returns:
readThroughput
public Mono
Read the throughput provisioned for the current container.
Mono<ThroughputResponse> throughputResponseMono = cosmosAsyncContainer.readThroughput();
throughputResponseMono.subscribe(throughputResponse -> {
System.out.println(throughputResponse);
}, throwable -> {
throwable.printStackTrace();
});
Returns:
replace
public Mono
Replaces the current container's properties.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response with the replaced container properties. In case of failure the Mono will error.
Parameters:
Returns:
replace
public Mono
Replaces the current container properties while using non-default request options.
After subscription the operation will be performed. The Mono upon successful completion will contain a single Cosmos container response with the replaced container properties. In case of failure the Mono will error.
Parameters:
Returns:
replaceThroughput
public Mono
Replace the throughput.
ThroughputProperties throughputProperties =
ThroughputProperties.createAutoscaledThroughput(1000);
cosmosAsyncContainer.replaceThroughput(throughputProperties)
.subscribe(throughputResponse -> {
System.out.println(throughputResponse);
},
throwable -> {
throwable.printStackTrace();
});
Parameters:
Returns:
