0
# Client Operations
1

2
Account-level operations for Azure Cosmos DB including authentication, database management, and client configuration. The CosmosClient serves as the entry point for all Azure Cosmos DB operations.
3

4
## Capabilities
5

6
### Client Initialization
7

8
Initialize the Cosmos client with account endpoint and authentication credentials.
9

10
```python { .api }
11
class CosmosClient:
12
    def __init__(self, url: str, credential: Union[str, Dict[str, Any], TokenCredential], consistency_level: str = None, **kwargs):
13
        """
14
        Initialize a new CosmosClient.
15
        
16
        Parameters:
17
        - url: Account endpoint URL
18
        - credential: Account key, resource token, token dictionary, or TokenCredential
19
        - consistency_level: Default consistency level for operations
20
        - connection_timeout: Connection timeout in seconds
21
        - request_timeout: Request timeout in seconds
22
        - connection_mode: Connection mode (Gateway or Direct)
23
        - proxy_config: Proxy configuration
24
        - ssl_config: SSL configuration
25
        - connection_verify: Enable SSL certificate verification
26
        - connection_cert: Client certificate file
27
        - retry_total: Total number of retries
28
        - retry_backoff_factor: Backoff factor for retries
29
        - retry_on_status_codes: HTTP status codes to retry on
30
        - enable_endpoint_discovery: Enable automatic endpoint discovery
31
        """
32
```
33

34
### Alternative Client Creation
35

36
Create client from connection string for simplified configuration.
37

38
```python { .api }
39
@classmethod
40
def from_connection_string(cls, conn_str: str, credential: str = None, consistency_level: str = None, **kwargs) -> CosmosClient:
41
    """
42
    Create a CosmosClient from connection string.
43
    
44
    Parameters:
45
    - conn_str: Azure Cosmos DB connection string
46
    - credential: Account key (if not in connection string)
47
    - consistency_level: Default consistency level
48
    - **kwargs: Additional client options
49
    
50
    Returns:
51
    CosmosClient instance
52
    """
53
```
54

55
Usage example:
56

57
```python
58
# From connection string
59
client = CosmosClient.from_connection_string(
60
    conn_str="AccountEndpoint=https://account.documents.azure.com:443/;AccountKey=key==",
61
    consistency_level=ConsistencyLevel.Session
62
)
63
```
64

65
### Database Management
66

67
Create, list, query, and delete databases within the account.
68

69
```python { .api }
70
def create_database(self, id: str, populate_query_metrics: bool = None, offer_throughput: Union[int, ThroughputProperties] = None, **kwargs):
71
    """
72
    Create a new database.
73
    
74
    Parameters:
75
    - id: Database ID
76
    - populate_query_metrics: Include query metrics in response
77
    - offer_throughput: Provisioned throughput in RU/s
78
    - session_token: Session token for consistency
79
    - initial_headers: Custom headers
80
    - etag: ETag for conditional operations
81
    - match_condition: Match condition for conditional operations
82
    
83
    Returns:
84
    DatabaseProxy for the created database
85
    
86
    Raises:
87
    CosmosResourceExistsError: If database already exists
88
    """
89

90
def create_database_if_not_exists(self, id: str, populate_query_metrics: bool = None, offer_throughput: Union[int, ThroughputProperties] = None, **kwargs):
91
    """
92
    Create database if it doesn't exist, otherwise return existing.
93
    
94
    Parameters: Same as create_database
95
    
96
    Returns:
97
    DatabaseProxy for the database
98
    """
99

100
def get_database_client(self, database: str) -> DatabaseProxy:
101
    """
102
    Get a database client for operations on a specific database.
103
    
104
    Parameters:
105
    - database: Database ID or DatabaseProxy instance
106
    
107
    Returns:
108
    DatabaseProxy instance
109
    """
110

111
def list_databases(self, max_item_count: int = None, populate_query_metrics: bool = None, **kwargs):
112
    """
113
    List all databases in the account.
114
    
115
    Parameters:
116
    - max_item_count: Maximum number of items to return
117
    - populate_query_metrics: Include query metrics
118
    - session_token: Session token for consistency
119
    
120
    Returns:
121
    Iterable of database items
122
    """
123

124
def query_databases(self, query: str = None, parameters: list = None, enable_cross_partition_query: bool = None, max_item_count: int = None, populate_query_metrics: bool = None, **kwargs):
125
    """
126
    Query databases using SQL-like syntax.
127
    
128
    Parameters:
129
    - query: SQL query string
130
    - parameters: Query parameters as [{"name": "@param", "value": value}]
131
    - enable_cross_partition_query: Enable cross-partition queries
132
    - max_item_count: Maximum items per page
133
    - populate_query_metrics: Include query metrics
134
    - partition_key: Partition key value
135
    - session_token: Session token for consistency
136
    
137
    Returns:
138
    Iterable of query results
139
    """
140

141
def delete_database(self, database: str, populate_query_metrics: bool = None, **kwargs):
142
    """
143
    Delete a database.
144
    
145
    Parameters:
146
    - database: Database ID or DatabaseProxy instance  
147
    - populate_query_metrics: Include query metrics
148
    - session_token: Session token for consistency
149
    - etag: ETag for conditional operations
150
    - match_condition: Match condition for conditional operations
151
    
152
    Raises:
153
    CosmosResourceNotFoundError: If database doesn't exist
154
    """
155
```
156

157
### Account Information
158

159
Retrieve account-level information and capabilities.
160

161
```python { .api }
162
def get_database_account(self, **kwargs) -> DatabaseAccount:
163
    """
164
    Get database account information.
165
    
166
    Parameters:
167
    - session_token: Session token for consistency
168
    
169
    Returns:
170
    DatabaseAccount with account properties and capabilities
171
    """
172
```
173

174
## Usage Examples
175

176
### Basic Client Setup
177

178
```python
179
from azure.cosmos import CosmosClient, ConsistencyLevel
180

181
# Initialize with explicit endpoint and key
182
client = CosmosClient(
183
    url="https://myaccount.documents.azure.com:443/",
184
    credential="myaccountkey==",
185
    consistency_level=ConsistencyLevel.Session
186
)
187

188
# Initialize with connection string
189
client = CosmosClient.from_connection_string(
190
    "AccountEndpoint=https://myaccount.documents.azure.com:443/;AccountKey=key=="
191
)
192
```
193

194
### Database Operations
195

196
```python
197
# Create a new database
198
try:
199
    database = client.create_database(
200
        id="ProductCatalog",
201
        offer_throughput=400
202
    )
203
    print(f"Created database: {database.id}")
204
except CosmosResourceExistsError:
205
    print("Database already exists")
206
    database = client.get_database_client("ProductCatalog")
207

208
# List all databases
209
databases = list(client.list_databases())
210
for db in databases:
211
    print(f"Database: {db['id']}")
212

213
# Query databases
214
results = list(client.query_databases(
215
    query="SELECT * FROM root r WHERE CONTAINS(r.id, @name)",
216
    parameters=[{"name": "@name", "value": "Product"}]
217
))
218

219
# Get account information
220
account_info = client.get_database_account()
221
print(f"Account consistency: {account_info.ConsistencyPolicy}")
222
print(f"Writable regions: {account_info.WritableLocations}")
223
```
224

225
### Error Handling
226

227
```python
228
from azure.cosmos.exceptions import (
229
    CosmosHttpResponseError,
230
    CosmosResourceExistsError,
231
    CosmosResourceNotFoundError
232
)
233

234
try:
235
    database = client.create_database("MyDatabase")
236
except CosmosResourceExistsError:
237
    print("Database already exists")
238
    database = client.get_database_client("MyDatabase")
239
except CosmosHttpResponseError as e:
240
    print(f"HTTP error occurred: {e.status_code} - {e.message}")
241
```