0
# Azure Cosmos DB Management Client
1

2
A comprehensive Python client library for managing Azure Cosmos DB resources through the Azure Resource Manager APIs. This library enables developers to programmatically create, configure, and manage Cosmos DB accounts, databases, containers, and other related resources in Azure across all supported APIs (SQL, MongoDB, Cassandra, Gremlin, and Table).
3

4
## Package Information
5

6
- **Package Name**: azure-mgmt-cosmosdb
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Version**: 9.8.0
10
- **Installation**: `pip install azure-mgmt-cosmosdb`
11

12
## Core Imports
13

14
```python
15
from azure.mgmt.cosmosdb import CosmosDBManagementClient
16
from azure.identity import DefaultAzureCredential
17
```
18

19
For async operations:
20

21
```python
22
from azure.mgmt.cosmosdb.aio import CosmosDBManagementClient
23
from azure.identity.aio import DefaultAzureCredential
24
```
25

26
## Basic Usage
27

28
```python
29
from azure.mgmt.cosmosdb import CosmosDBManagementClient
30
from azure.identity import DefaultAzureCredential
31

32
# Initialize client
33
credential = DefaultAzureCredential()
34
subscription_id = "your-subscription-id"
35
client = CosmosDBManagementClient(credential, subscription_id)
36

37
# List all Cosmos DB accounts in subscription
38
for account in client.database_accounts.list():
39
    print(f"Account: {account.name}, Location: {account.location}")
40

41
# Get specific account
42
account = client.database_accounts.get("resource-group", "account-name")
43
print(f"Account Kind: {account.kind}, API: {account.capabilities}")
44

45
# Create SQL database (Long Running Operation)
46
database_params = {
47
    "resource": {"id": "database-name"},
48
    "options": {"throughput": 400}
49
}
50
poller = client.sql_resources.begin_create_update_sql_database(
51
    "resource-group", "account-name", "database-name", database_params
52
)
53
result = poller.result()  # Wait for completion
54
```
55

56
## Architecture
57

58
The Azure Cosmos DB Management Client follows the Azure SDK design patterns:
59

60
- **Client**: `CosmosDBManagementClient` serves as the main entry point, managing authentication and providing access to operation groups
61
- **Operations**: Specialized operation classes for different resource types (database accounts, SQL resources, MongoDB resources, etc.)
62
- **Models**: Complete data classes representing Azure resources, configurations, and responses
63
- **Long Running Operations (LRO)**: Async operations return `LROPoller` objects for monitoring progress
64
- **Pagination**: List operations return `ItemPaged` iterators for automatic result pagination
65

66
This design provides comprehensive coverage of the Azure Cosmos DB management plane while maintaining consistency with the broader Azure SDK ecosystem.
67

68
## Capabilities
69

70
### Database Account Management
71

72
Core database account lifecycle operations including creation, configuration, scaling, failover management, and key rotation. These operations manage the top-level Cosmos DB account resource that hosts all databases and containers.
73

74
```python { .api }
75
class DatabaseAccountsOperations:
76
    def get(self, resource_group_name: str, account_name: str) -> DatabaseAccountGetResults: ...
77
    def begin_create_or_update(self, resource_group_name: str, account_name: str, create_update_parameters: DatabaseAccountCreateUpdateParameters) -> LROPoller[DatabaseAccountGetResults]: ...
78
    def begin_delete(self, resource_group_name: str, account_name: str) -> LROPoller[None]: ...
79
    def list(self) -> ItemPaged[DatabaseAccountGetResults]: ...
80
    def list_by_resource_group(self, resource_group_name: str) -> ItemPaged[DatabaseAccountGetResults]: ...
81
    def list_keys(self, resource_group_name: str, account_name: str) -> DatabaseAccountListKeysResult: ...
82
    def begin_regenerate_key(self, resource_group_name: str, account_name: str, key_to_regenerate: DatabaseAccountRegenerateKeyParameters) -> LROPoller[None]: ...
83
    def begin_failover_priority_change(self, resource_group_name: str, account_name: str, failover_parameters: FailoverPolicies) -> LROPoller[None]: ...
84
```
85

86
[Database Account Management](./database-accounts.md)
87

88
### SQL API Resource Management
89

90
Comprehensive management of SQL (Core) API resources including databases, containers, stored procedures, triggers, user-defined functions, client encryption keys, and RBAC role definitions.
91

92
```python { .api }
93
class SqlResourcesOperations:
94
    def list_sql_databases(self, resource_group_name: str, account_name: str) -> ItemPaged[SqlDatabaseGetResults]: ...
95
    def get_sql_database(self, resource_group_name: str, account_name: str, database_name: str) -> SqlDatabaseGetResults: ...
96
    def begin_create_update_sql_database(self, resource_group_name: str, account_name: str, database_name: str, create_update_sql_database_parameters: SqlDatabaseCreateUpdateParameters) -> LROPoller[SqlDatabaseGetResults]: ...
97
    def list_sql_containers(self, resource_group_name: str, account_name: str, database_name: str) -> ItemPaged[SqlContainerGetResults]: ...
98
    def get_sql_container(self, resource_group_name: str, account_name: str, database_name: str, container_name: str) -> SqlContainerGetResults: ...
99
    def begin_create_update_sql_container(self, resource_group_name: str, account_name: str, database_name: str, container_name: str, create_update_sql_container_parameters: SqlContainerCreateUpdateParameters) -> LROPoller[SqlContainerGetResults]: ...
100
    def get_sql_database_throughput(self, resource_group_name: str, account_name: str, database_name: str) -> ThroughputSettingsGetResults: ...
101
    def begin_update_sql_database_throughput(self, resource_group_name: str, account_name: str, database_name: str, update_throughput_parameters: ThroughputSettingsUpdateParameters) -> LROPoller[ThroughputSettingsGetResults]: ...
102
```
103

104
[SQL API Resources](./sql-resources.md)
105

106
### MongoDB API Resource Management
107

108
Full management of MongoDB API resources including databases, collections, role definitions, and user definitions with support for MongoDB-specific features like sharding and indexing.
109

110
```python { .api }
111
class MongoDBResourcesOperations:
112
    def list_mongo_db_databases(self, resource_group_name: str, account_name: str) -> ItemPaged[MongoDBDatabaseGetResults]: ...
113
    def get_mongo_db_database(self, resource_group_name: str, account_name: str, database_name: str) -> MongoDBDatabaseGetResults: ...
114
    def begin_create_update_mongo_db_database(self, resource_group_name: str, account_name: str, database_name: str, create_update_mongo_db_database_parameters: MongoDBDatabaseCreateUpdateParameters) -> LROPoller[MongoDBDatabaseGetResults]: ...
115
    def list_mongo_db_collections(self, resource_group_name: str, account_name: str, database_name: str) -> ItemPaged[MongoDBCollectionGetResults]: ...
116
    def get_mongo_db_collection(self, resource_group_name: str, account_name: str, database_name: str, collection_name: str) -> MongoDBCollectionGetResults: ...
117
    def begin_create_update_mongo_db_collection(self, resource_group_name: str, account_name: str, database_name: str, collection_name: str, create_update_mongo_db_collection_parameters: MongoDBCollectionCreateUpdateParameters) -> LROPoller[MongoDBCollectionGetResults]: ...
118
```
119

120
[MongoDB API Resources](./mongodb-resources.md)
121

122
### Multi-API Resource Management
123

124
Management operations for Table API, Cassandra API, and Gremlin API resources, providing consistent CRUD operations and throughput management across all Cosmos DB APIs.
125

126
```python { .api }
127
class TableResourcesOperations:
128
    def list_tables(self, resource_group_name: str, account_name: str) -> ItemPaged[TableGetResults]: ...
129
    def get_table(self, resource_group_name: str, account_name: str, table_name: str) -> TableGetResults: ...
130
    def begin_create_update_table(self, resource_group_name: str, account_name: str, table_name: str, create_update_table_parameters: TableCreateUpdateParameters) -> LROPoller[TableGetResults]: ...
131

132
class CassandraResourcesOperations:
133
    def list_cassandra_keyspaces(self, resource_group_name: str, account_name: str) -> ItemPaged[CassandraKeyspaceGetResults]: ...
134
    def list_cassandra_tables(self, resource_group_name: str, account_name: str, keyspace_name: str) -> ItemPaged[CassandraTableGetResults]: ...
135

136
class GremlinResourcesOperations:
137
    def list_gremlin_databases(self, resource_group_name: str, account_name: str) -> ItemPaged[GremlinDatabaseGetResults]: ...
138
    def list_gremlin_graphs(self, resource_group_name: str, account_name: str, database_name: str) -> ItemPaged[GremlinGraphGetResults]: ...
139
```
140

141
[Multi-API Resources](./multi-api-resources.md)
142

143
### Point-in-Time Restore Operations
144

145
Comprehensive point-in-time restore capabilities for discovering restorable resources across all APIs and time ranges, enabling precise backup and recovery scenarios.
146

147
```python { .api }
148
class RestorableDatabaseAccountsOperations:
149
    def list(self) -> ItemPaged[RestorableDatabaseAccountGetResult]: ...
150
    def list_by_location(self, location: str) -> ItemPaged[RestorableDatabaseAccountGetResult]: ...
151

152
class RestorableSqlResourcesOperations:
153
    def list(self, location: str, instance_id: str) -> ItemPaged[RestorableSqlResourcesGetResult]: ...
154

155
class RestorableMongodbResourcesOperations:
156
    def list(self, location: str, instance_id: str) -> ItemPaged[RestorableMongodbResourcesGetResult]: ...
157
```
158

159
[Point-in-Time Restore](./restore-operations.md)
160

161
### Monitoring and Metrics
162

163
Comprehensive monitoring capabilities including percentile metrics, usage statistics, and performance monitoring across regions, databases, containers, and partitions.
164

165
```python { .api }
166
class PercentileOperations:
167
    def list_metrics(self, resource_group_name: str, account_name: str, filter: str) -> ItemPaged[PercentileMetric]: ...
168

169
class DatabaseOperations:
170
    def list_metrics(self, resource_group_name: str, account_name: str, database_rid: str, filter: str) -> ItemPaged[Metric]: ...
171
    def list_usages(self, resource_group_name: str, account_name: str, database_rid: str, filter: str = None) -> ItemPaged[Usage]: ...
172

173
class CollectionOperations:
174
    def list_metrics(self, resource_group_name: str, account_name: str, database_rid: str, collection_rid: str, filter: str) -> ItemPaged[Metric]: ...
175
```
176

177
[Monitoring and Metrics](./monitoring-metrics.md)
178

179
### Networking and Security
180

181
Private endpoint connections, private link resources, and security configuration for secure network access to Cosmos DB accounts.
182

183
```python { .api }
184
class PrivateEndpointConnectionsOperations:
185
    def list_by_database_account(self, resource_group_name: str, account_name: str) -> ItemPaged[PrivateEndpointConnection]: ...
186
    def get(self, resource_group_name: str, account_name: str, private_endpoint_connection_name: str) -> PrivateEndpointConnection: ...
187
    def begin_create_or_update(self, resource_group_name: str, account_name: str, private_endpoint_connection_name: str, parameters: PrivateEndpointConnection) -> LROPoller[PrivateEndpointConnection]: ...
188

189
class PrivateLinkResourcesOperations:
190
    def list_by_database_account(self, resource_group_name: str, account_name: str) -> ItemPaged[PrivateLinkResource]: ...
191
    def get(self, resource_group_name: str, account_name: str, group_name: str) -> PrivateLinkResource: ...
192
```
193

194
[Networking and Security](./networking-security.md)
195

196
### Provider Operations
197

198
Core Azure resource provider operations for listing available Cosmos DB management operations and discovering API capabilities.
199

200
```python { .api }
201
class Operations:
202
    def list(self) -> ItemPaged[Operation]: ...
203
```
204

205
### Location Management
206

207
Azure region and location operations for discovering available Cosmos DB regions and their capabilities.
208

209
```python { .api }
210
class LocationsOperations:
211
    def list(self) -> ItemPaged[LocationGetResult]: ...
212
```
213

214
### Service Management
215

216
Management of Cosmos DB services, Cassandra clusters, data centers, and notebook workspaces for advanced scenarios and specialized deployments.
217

218
```python { .api }
219
class ServiceOperations:
220
    def list(self, resource_group_name: str, account_name: str) -> ItemPaged[ServiceResource]: ...
221
    def get(self, resource_group_name: str, account_name: str, service_name: str) -> ServiceResource: ...
222
    def begin_create(self, resource_group_name: str, account_name: str, service_name: str, create_service_parameters: ServiceResourceCreateUpdateParameters) -> LROPoller[ServiceResource]: ...
223

224
class CassandraClustersOperations:
225
    def list_by_subscription(self) -> ItemPaged[ClusterResource]: ...
226
    def list_by_resource_group(self, resource_group_name: str) -> ItemPaged[ClusterResource]: ...
227
    def get(self, resource_group_name: str, cluster_name: str) -> ClusterResource: ...
228
    def begin_create_update(self, resource_group_name: str, cluster_name: str, body: ClusterResource) -> LROPoller[ClusterResource]: ...
229

230
class NotebookWorkspacesOperations:
231
    def list_by_database_account(self, resource_group_name: str, account_name: str) -> ItemPaged[NotebookWorkspace]: ...
232
    def get(self, resource_group_name: str, account_name: str, notebook_workspace_name: str) -> NotebookWorkspace: ...
233
    def begin_create_or_update(self, resource_group_name: str, account_name: str, notebook_workspace_name: str, notebook_create_update_parameters: NotebookWorkspaceCreateUpdateParameters) -> LROPoller[NotebookWorkspace]: ...
234
```
235

236
[Service Management](./service-management.md)
237

238
## Core Types
239

240
```python { .api }
241
class CosmosDBManagementClient:
242
    def __init__(
243
        self,
244
        credential: TokenCredential,
245
        subscription_id: str,
246
        base_url: Optional[str] = None,
247
        **kwargs: Any
248
    ) -> None: ...
249
    
250
    def close(self) -> None: ...
251
    def __enter__(self) -> Self: ...
252
    def __exit__(self, *exc_details: Any) -> None: ...
253

254
# Long Running Operation Poller
255
class LROPoller[T]:
256
    def result(self, timeout: Optional[float] = None) -> T: ...
257
    def status(self) -> str: ...
258
    def done(self) -> bool: ...
259
    def wait(self, timeout: Optional[float] = None) -> None: ...
260

261
# Pagination Iterator
262
class ItemPaged[T]:
263
    def __iter__(self) -> Iterator[T]: ...
264
    def by_page(self, continuation_token: Optional[str] = None) -> Iterator[Iterator[T]]: ...
265
```