Share via

CosmosDatabase Class

  • Reference
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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

readAllContainers

public CosmosPagedIterable readAllContainers()

Read all containers in the current database.

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

Returns:

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:

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.

Applies to