CosmosDatabase Class

Package:

com.azure.cosmos

Maven Artifact:

com.azure:azure-cosmos:4.63.4

• java.lang.Object
• • com.azure.cosmos.CosmosDatabase

public class CosmosDatabase

Perform read and delete databases, update database throughput, and perform operations on child resources in a synchronous way

Method Summary

Modifier and Type	Method and Description
CosmosContainerResponse	createContainer(CosmosContainerProperties containerProperties) Creates a Cosmos container.
CosmosContainerResponse	createContainer(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options) Creates a Cosmos container while passing additional request options.
CosmosContainerResponse	createContainer(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties) Creates a Cosmos container with custom throughput setting.
CosmosContainerResponse	createContainer(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties, CosmosContainerRequestOptions options) Creates a Cosmos container.
CosmosContainerResponse	createContainer(String id, String partitionKeyPath) Create a Cosmos container.
CosmosContainerResponse	createContainer(String id, String partitionKeyPath, ThroughputProperties throughputProperties) Create a Cosmos container.
CosmosContainerResponse	createContainerIfNotExists(CosmosContainerProperties containerProperties) Create container if one matching the id in the properties object does not exist.
CosmosContainerResponse	createContainerIfNotExists(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties) Creates a Cosmos container if one matching the id in the properties object does not exist.
CosmosContainerResponse	createContainerIfNotExists(String id, String partitionKeyPath) Creates a Cosmos container if one matching the id does not exist.
CosmosContainerResponse	createContainerIfNotExists(String id, String partitionKeyPath, ThroughputProperties throughputProperties) Creates a Cosmos container if one matching the id does not exist.
CosmosUserResponse	createUser(CosmosUserProperties userProperties) Create Cosmos user.
CosmosDatabaseResponse	delete() Deletes the current Cosmos database.
CosmosDatabaseResponse	delete(CosmosDatabaseRequestOptions options) Delete the current Cosmos database while specifying additional request options.
CosmosClientEncryptionKey	getClientEncryptionKey(String id) Gets a CosmosClientEncryptionKey object without making a service call
CosmosContainer	getContainer(String id) Gets a Cosmos container instance without making a service call.
String	getId() Get the id of the Cosmos database.
CosmosUser	getUser(String id) Gets a Cosmos user instance without making a service call.
CosmosPagedIterable<CosmosContainerProperties>	queryContainers(SqlQuerySpec querySpec) Query containers in the current database.
CosmosPagedIterable<CosmosContainerProperties>	queryContainers(SqlQuerySpec querySpec, CosmosQueryRequestOptions options) Query containers in the current database.
CosmosPagedIterable<CosmosContainerProperties>	queryContainers(String query) Query containers in the current database.
CosmosPagedIterable<CosmosContainerProperties>	queryContainers(String query, CosmosQueryRequestOptions options) Query containers iterator.
CosmosPagedIterable<CosmosUserProperties>	queryUsers(SqlQuerySpec querySpec) Query all Cosmos users for the current database.
CosmosPagedIterable<CosmosUserProperties>	queryUsers(SqlQuerySpec querySpec, CosmosQueryRequestOptions options) Query all Cosmos users for the current database.
CosmosPagedIterable<CosmosUserProperties>	queryUsers(String query) Query all Cosmos users for the current database.
CosmosPagedIterable<CosmosUserProperties>	queryUsers(String query, CosmosQueryRequestOptions options) Query all Cosmos users for the current database.
CosmosDatabaseResponse	read() Reads the current Cosmos database.
CosmosDatabaseResponse	read(CosmosDatabaseRequestOptions options) Reads the current Cosmos database while specifying additional request options.
CosmosPagedIterable<CosmosClientEncryptionKeyProperties>	readAllClientEncryptionKeys() Reads all cosmos client encryption keys in a database.
CosmosPagedIterable<CosmosContainerProperties>	readAllContainers() Read all containers in the current database.
CosmosPagedIterable<CosmosUserProperties>	readAllUsers() Read all Cosmos users for the current database.
ThroughputResponse	readThroughput() Gets the throughput of the current database.
ThroughputResponse	replaceThroughput(ThroughputProperties throughputProperties) Sets the throughput of the current database.
CosmosUserResponse	upsertUser(CosmosUserProperties userProperties) Upserts a Cosmos user.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Method Details

createContainer

public CosmosContainerResponse createContainer(CosmosContainerProperties containerProperties)

Creates a Cosmos container.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(containerProperties);
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

containerProperties - the CosmosContainerProperties.

Returns:

the CosmosContainerResponse with the created container.

createContainer

public CosmosContainerResponse createContainer(CosmosContainerProperties containerProperties, CosmosContainerRequestOptions options)

Creates a Cosmos container while passing additional request options.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(containerProperties);
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

containerProperties - the CosmosContainerProperties.

options - the CosmosContainerProperties.

Returns:

the CosmosContainerResponse with the created container.

createContainer

public CosmosContainerResponse createContainer(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties)

Creates a Cosmos container with custom throughput setting.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoScaleMaxThroughput);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(
         containerProperties,
         throughputProperties
     );
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

containerProperties - the CosmosContainerProperties.

throughputProperties - the throughput properties.

Returns:

the CosmosContainerResponse with the created container.

createContainer

public CosmosContainerResponse createContainer(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties, CosmosContainerRequestOptions options)

Creates a Cosmos container.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoScaleMaxThroughput);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(
         containerProperties,
         throughputProperties
     );
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

containerProperties - the container properties.

throughputProperties - the throughput properties.

options - the options.

Returns:

the cosmos container response.

createContainer

public CosmosContainerResponse createContainer(String id, String partitionKeyPath)

Create a Cosmos container.

ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoscaledThroughput);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(
         containerId,
         partitionKeyPath,
         throughputProperties
     );
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

id - the container id.

partitionKeyPath - the partition key path.

Returns:

the cosmos container response.

createContainer

public CosmosContainerResponse createContainer(String id, String partitionKeyPath, ThroughputProperties throughputProperties)

Create a Cosmos container.

ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoscaledThroughput);
 try {
     CosmosContainerResponse container = cosmosDatabase.createContainer(
         containerId,
         partitionKeyPath,
         throughputProperties
     );
 } catch (CosmosException ce) {
     System.out.println("Failed to create container: " + ce);
 }

Parameters:

id - the id.

partitionKeyPath - the partition key path.

throughputProperties - the throughput properties.

Returns:

the cosmos container response.

createContainerIfNotExists

public CosmosContainerResponse createContainerIfNotExists(CosmosContainerProperties containerProperties)

Create container if one matching the id in the properties object does not exist.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 CosmosContainerResponse container = cosmosDatabase.createContainerIfNotExists(containerProperties);

Parameters:

containerProperties - the container properties.

Returns:

the cosmos container response.

createContainerIfNotExists

public CosmosContainerResponse createContainerIfNotExists(CosmosContainerProperties containerProperties, ThroughputProperties throughputProperties)

Creates a Cosmos container if one matching the id in the properties object does not exist.

CosmosContainerProperties containerProperties =
     new CosmosContainerProperties(containerId, partitionKeyDefinition);
 ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoScaleMaxThroughput);
 CosmosContainerResponse container = cosmosDatabase.createContainerIfNotExists(
     containerProperties,
     throughputProperties
 );

The throughput properties will only be used if the specified container does not exist and therefor a new container will be created.

Parameters:

containerProperties - the container properties.

throughputProperties - the throughput properties for the container.

Returns:

the cosmos container response.

createContainerIfNotExists

public CosmosContainerResponse createContainerIfNotExists(String id, String partitionKeyPath)

Creates a Cosmos container if one matching the id does not exist.

ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoscaledThroughput);
 CosmosContainerResponse container = cosmosDatabase.createContainerIfNotExists(
     containerId,
     partitionKeyPath,
     throughputProperties
 );

Parameters:

id - the id.

partitionKeyPath - the partition key path.

Returns:

the cosmos container response.

createContainerIfNotExists

public CosmosContainerResponse createContainerIfNotExists(String id, String partitionKeyPath, ThroughputProperties throughputProperties)

Creates a Cosmos container if one matching the id does not exist.

ThroughputProperties throughputProperties =
     ThroughputProperties.createAutoscaledThroughput(autoscaledThroughput);
 CosmosContainerResponse container = cosmosDatabase.createContainerIfNotExists(
     containerId,
     partitionKeyPath,
     throughputProperties
 );

The throughput properties will only be used if the specified container does not exist and therefor a new container will be created.

Parameters:

id - the id.

partitionKeyPath - the partition key path.

throughputProperties - the throughput properties for the container.

Returns:

the cosmos container response.

createUser

public CosmosUserResponse createUser(CosmosUserProperties userProperties)

Create Cosmos user.

CosmosUserProperties userProperties = new CosmosUserProperties();
 userProperties.setId(userId);
 cosmosDatabase.createUser(userProperties);

Parameters:

userProperties - the settings.

Returns:

the cosmos user response.

delete

public CosmosDatabaseResponse delete()

Deletes the current Cosmos database.

CosmosDatabase cosmosDatabase = cosmosClient
     .getDatabase("<YOUR DATABASE NAME>");
 CosmosDatabaseResponse deleteResponse = cosmosDatabase.delete();

Returns:

the CosmosDatabaseResponse.

delete

public CosmosDatabaseResponse delete(CosmosDatabaseRequestOptions options)

Delete the current Cosmos database while specifying additional request options.

CosmosDatabase cosmosDatabase = cosmosClient
     .getDatabase("<YOUR DATABASE NAME>");
 CosmosDatabaseResponse deleteResponse = cosmosDatabase.delete();

Parameters:

options - the CosmosDatabaseRequestOptions request options.

Returns:

the CosmosDatabaseResponse.

getClientEncryptionKey

public CosmosClientEncryptionKey getClientEncryptionKey(String id)

Gets a CosmosClientEncryptionKey object without making a service call

Parameters:

id - id of the clientEncryptionKey

Returns:

Cosmos ClientEncryptionKey

getContainer

public CosmosContainer getContainer(String id)

Gets a Cosmos container instance without making a service call.

To get the actual object a read operation must be performed first.

Parameters:

id - id of the container.

Returns:

Cosmos Container.

getId

public String getId()

Get the id of the Cosmos database.

Returns:

the id of the database.

getUser

public CosmosUser getUser(String id)

Gets a Cosmos user instance without making a service call.

To get the actual object a read operation must be performed first.

Parameters:

id - the id.

Returns:

the user.

queryContainers

public CosmosPagedIterable queryContainers(SqlQuerySpec querySpec)

Query containers in the current database.

CosmosPagedIterable<CosmosContainerProperties> cosmosContainersList =
     cosmosDatabase.queryContainers("SELECT * FROM DB_NAME");
 cosmosContainersList.forEach(cosmosContainerProperties -> {
     System.out.println(cosmosContainerProperties);
 });

Parameters:

querySpec - the query spec.

Returns:

the CosmosPagedIterable<T>.

queryContainers

public CosmosPagedIterable queryContainers(SqlQuerySpec querySpec, CosmosQueryRequestOptions options)

Query containers in the current database.

CosmosPagedIterable<CosmosContainerProperties> cosmosContainersList =
     cosmosDatabase.queryContainers("SELECT * FROM DB_NAME");
 cosmosContainersList.forEach(cosmosContainerProperties -> {
     System.out.println(cosmosContainerProperties);
 });

Parameters:

querySpec - the query spec.

options - the options.

Returns:

the CosmosPagedIterable<T>.

queryContainers

public CosmosPagedIterable queryContainers(String query)

Query containers in the current database.

CosmosPagedIterable<CosmosContainerProperties> cosmosContainersList =
     cosmosDatabase.queryContainers("SELECT * FROM DB_NAME");
 cosmosContainersList.forEach(cosmosContainerProperties -> {
     System.out.println(cosmosContainerProperties);
 });

Parameters:

query - the query.

Returns:

the CosmosPagedIterable<T>.

queryContainers

public CosmosPagedIterable queryContainers(String query, CosmosQueryRequestOptions options)

Query containers iterator.

CosmosPagedIterable<CosmosContainerProperties> cosmosContainersList =
     cosmosDatabase.queryContainers("SELECT * FROM DB_NAME");
 cosmosContainersList.forEach(cosmosContainerProperties -> {
     System.out.println(cosmosContainerProperties);
 });

Parameters:

query - the query.

options - the options.

Returns:

the CosmosPagedIterable<T>.

queryUsers

public CosmosPagedIterable queryUsers(SqlQuerySpec querySpec)

Query all Cosmos users for the current database.

CosmosPagedIterable<CosmosUserProperties> userPropertiesList =
     cosmosDatabase.queryUsers("SELECT * FROM DB_NAME");
 userPropertiesList.forEach(userProperties -> {
     System.out.println(userProperties);
 });

Parameters:

querySpec - the query spec.

Returns:

the CosmosPagedIterable<T>.

queryUsers

public CosmosPagedIterable queryUsers(SqlQuerySpec querySpec, CosmosQueryRequestOptions options)

Query all Cosmos users for the current database.

CosmosPagedIterable<CosmosUserProperties> userPropertiesList =
     cosmosDatabase.queryUsers("SELECT * FROM DB_NAME");
 userPropertiesList.forEach(userProperties -> {
     System.out.println(userProperties);
 });

Parameters:

querySpec - the query spec.

options - the options.

Returns:

the CosmosPagedIterable<T>.

queryUsers

public CosmosPagedIterable queryUsers(String query)

Query all Cosmos users for the current database.

CosmosPagedIterable<CosmosUserProperties> userPropertiesList =
     cosmosDatabase.queryUsers("SELECT * FROM DB_NAME");
 userPropertiesList.forEach(userProperties -> {
     System.out.println(userProperties);
 });

Parameters:

query - the query.

Returns:

the CosmosPagedIterable<T>.

queryUsers

public CosmosPagedIterable queryUsers(String query, CosmosQueryRequestOptions options)

Query all Cosmos users for the current database.

CosmosPagedIterable<CosmosUserProperties> userPropertiesList =
     cosmosDatabase.queryUsers("SELECT * FROM DB_NAME");
 userPropertiesList.forEach(userProperties -> {
     System.out.println(userProperties);
 });

Parameters:

query - the query.

options - the options.

Returns:

the CosmosPagedIterable<T>.

read

public CosmosDatabaseResponse read()

Reads the current Cosmos database. Fetch the details and properties of a database based on its unique identifier.

CosmosDatabase cosmosDatabase = cosmosClient
     .getDatabase("<YOUR DATABASE NAME>");
 CosmosDatabaseResponse readResponse = cosmosDatabase.read();

Returns:

the CosmosDatabaseResponse.

read

public CosmosDatabaseResponse read(CosmosDatabaseRequestOptions options)

Reads the current Cosmos database while specifying additional request options. Fetch the details and properties of a database based on its unique identifier.

CosmosDatabase cosmosDatabase = cosmosClient
     .getDatabase("<YOUR DATABASE NAME>");
 CosmosDatabaseResponse readResponse = cosmosDatabase.read();

Parameters:

options - the CosmosDatabaseRequestOptions request options.

Returns:

the CosmosDatabaseResponse

readAllClientEncryptionKeys

public CosmosPagedIterable readAllClientEncryptionKeys()

Reads all cosmos client encryption keys in a database.

CosmosPagedIterable<CosmosClientEncryptionKeyProperties> clientEncryptionKeys =
     cosmosDatabase.readAllClientEncryptionKeys();
 clientEncryptionKeys.forEach(encryptionKeyProperties ->
     System.out.println(clientEncryptionKeys)
 );

Returns:

a CosmosPagedIterable<T>.

readAllContainers

public CosmosPagedIterable readAllContainers()

Read all containers in the current database.

CosmosPagedIterable<CosmosContainerProperties> cosmosContainersList =
     cosmosDatabase.readAllContainers();
 cosmosContainersList.forEach(cosmosContainerProperties -> {
     System.out.println(cosmosContainerProperties);
 });

Returns:

the CosmosPagedIterable<T>.

readAllUsers

public CosmosPagedIterable readAllUsers()

Read all Cosmos users for the current database.

CosmosPagedIterable<CosmosUserProperties> cosmosUserProperties = cosmosDatabase.readAllUsers();
 cosmosUserProperties.forEach(userProperties -> {
     System.out.println(userProperties);
 });

Returns:

the CosmosPagedIterable<T>.

readThroughput

public ThroughputResponse readThroughput()

Gets the throughput of the current database.

ThroughputResponse throughputResponse = cosmosDatabase.readThroughput();
 System.out.println(throughputResponse);

Returns:

the throughput response.

replaceThroughput

public ThroughputResponse replaceThroughput(ThroughputProperties throughputProperties)

Sets the throughput of the current database.

ThroughputProperties throughputProperties = ThroughputProperties
     .createAutoscaledThroughput(autoScaleMaxThroughput);

 ThroughputResponse throughputResponse = cosmosDatabase.replaceThroughput(throughputProperties);
 System.out.println(throughputResponse);

Parameters:

throughputProperties - the throughput properties.

Returns:

the throughput response.

upsertUser

public CosmosUserResponse upsertUser(CosmosUserProperties userProperties)

Upserts a Cosmos user.

CosmosUserProperties userProperties = new CosmosUserProperties();
 userProperties.setId(userId);
 cosmosDatabase.upsertUser(userProperties);

Parameters:

userProperties - the settings.

Returns:

the cosmos user response.