0
# SQL API Resource Management
1

2
Comprehensive management of SQL (Core) API resources including databases, containers, stored procedures, triggers, user-defined functions, client encryption keys, and RBAC role definitions. The SQL API is Cosmos DB's native API providing the richest feature set and maximum flexibility.
3

4
## Capabilities
5

6
### SQL Database Management
7

8
Create, configure, and manage SQL databases within Cosmos DB accounts.
9

10
```python { .api }
11
def list_sql_databases(
12
    self,
13
    resource_group_name: str,
14
    account_name: str
15
) -> ItemPaged[SqlDatabaseGetResults]:
16
    """
17
    List SQL databases in a Cosmos DB account.
18
    
19
    Parameters:
20
    - resource_group_name: Name of the resource group
21
    - account_name: Name of the Cosmos DB account
22
    
23
    Returns:
24
    ItemPaged[SqlDatabaseGetResults]: Paginated list of SQL databases
25
    """
26

27
def get_sql_database(
28
    self,
29
    resource_group_name: str,
30
    account_name: str,
31
    database_name: str
32
) -> SqlDatabaseGetResults:
33
    """
34
    Get properties of a SQL database.
35
    
36
    Parameters:
37
    - resource_group_name: Name of the resource group
38
    - account_name: Name of the Cosmos DB account
39
    - database_name: Name of the SQL database
40
    
41
    Returns:
42
    SqlDatabaseGetResults: SQL database properties and configuration
43
    """
44

45
def begin_create_update_sql_database(
46
    self,
47
    resource_group_name: str,
48
    account_name: str,
49
    database_name: str,
50
    create_update_sql_database_parameters: SqlDatabaseCreateUpdateParameters
51
) -> LROPoller[SqlDatabaseGetResults]:
52
    """
53
    Create or update a SQL database (Long Running Operation).
54
    
55
    Parameters:
56
    - resource_group_name: Name of the resource group
57
    - account_name: Name of the Cosmos DB account
58
    - database_name: Name of the SQL database to create/update
59
    - create_update_sql_database_parameters: Database configuration parameters
60
    
61
    Returns:
62
    LROPoller[SqlDatabaseGetResults]: Poller for monitoring operation progress
63
    """
64

65
def begin_delete_sql_database(
66
    self,
67
    resource_group_name: str,
68
    account_name: str,
69
    database_name: str
70
) -> LROPoller[None]:
71
    """
72
    Delete a SQL database (Long Running Operation).
73
    
74
    Parameters:
75
    - resource_group_name: Name of the resource group
76
    - account_name: Name of the Cosmos DB account
77
    - database_name: Name of the SQL database to delete
78
    
79
    Returns:
80
    LROPoller[None]: Poller for monitoring operation progress
81
    """
82
```
83

84
### SQL Container Management
85

86
Manage SQL containers (collections) with advanced features like partitioning, indexing, and conflict resolution.
87

88
```python { .api }
89
def list_sql_containers(
90
    self,
91
    resource_group_name: str,
92
    account_name: str,
93
    database_name: str
94
) -> ItemPaged[SqlContainerGetResults]:
95
    """
96
    List SQL containers in a database.
97
    
98
    Parameters:
99
    - resource_group_name: Name of the resource group
100
    - account_name: Name of the Cosmos DB account
101
    - database_name: Name of the SQL database
102
    
103
    Returns:
104
    ItemPaged[SqlContainerGetResults]: Paginated list of SQL containers
105
    """
106

107
def get_sql_container(
108
    self,
109
    resource_group_name: str,
110
    account_name: str,
111
    database_name: str,
112
    container_name: str
113
) -> SqlContainerGetResults:
114
    """
115
    Get properties of a SQL container.
116
    
117
    Parameters:
118
    - resource_group_name: Name of the resource group
119
    - account_name: Name of the Cosmos DB account
120
    - database_name: Name of the SQL database
121
    - container_name: Name of the SQL container
122
    
123
    Returns:
124
    SqlContainerGetResults: SQL container properties and configuration
125
    """
126

127
def begin_create_update_sql_container(
128
    self,
129
    resource_group_name: str,
130
    account_name: str,
131
    database_name: str,
132
    container_name: str,
133
    create_update_sql_container_parameters: SqlContainerCreateUpdateParameters
134
) -> LROPoller[SqlContainerGetResults]:
135
    """
136
    Create or update a SQL container (Long Running Operation).
137
    
138
    Parameters:
139
    - resource_group_name: Name of the resource group
140
    - account_name: Name of the Cosmos DB account
141
    - database_name: Name of the SQL database
142
    - container_name: Name of the SQL container to create/update
143
    - create_update_sql_container_parameters: Container configuration parameters
144
    
145
    Returns:
146
    LROPoller[SqlContainerGetResults]: Poller for monitoring operation progress
147
    """
148

149
def begin_delete_sql_container(
150
    self,
151
    resource_group_name: str,
152
    account_name: str,
153
    database_name: str,
154
    container_name: str
155
) -> LROPoller[None]:
156
    """
157
    Delete a SQL container (Long Running Operation).
158
    
159
    Parameters:
160
    - resource_group_name: Name of the resource group
161
    - account_name: Name of the Cosmos DB account
162
    - database_name: Name of the SQL database
163
    - container_name: Name of the SQL container to delete
164
    
165
    Returns:
166
    LROPoller[None]: Poller for monitoring operation progress
167
    """
168
```
169

170
### Throughput Management
171

172
Manage dedicated and shared throughput settings with support for autoscale and manual modes.
173

174
```python { .api }
175
def get_sql_database_throughput(
176
    self,
177
    resource_group_name: str,
178
    account_name: str,
179
    database_name: str
180
) -> ThroughputSettingsGetResults:
181
    """
182
    Get throughput settings for a SQL database.
183
    
184
    Parameters:
185
    - resource_group_name: Name of the resource group
186
    - account_name: Name of the Cosmos DB account
187
    - database_name: Name of the SQL database
188
    
189
    Returns:
190
    ThroughputSettingsGetResults: Current throughput configuration
191
    """
192

193
def begin_update_sql_database_throughput(
194
    self,
195
    resource_group_name: str,
196
    account_name: str,
197
    database_name: str,
198
    update_throughput_parameters: ThroughputSettingsUpdateParameters
199
) -> LROPoller[ThroughputSettingsGetResults]:
200
    """
201
    Update throughput settings for a SQL database (Long Running Operation).
202
    
203
    Parameters:
204
    - resource_group_name: Name of the resource group
205
    - account_name: Name of the Cosmos DB account
206
    - database_name: Name of the SQL database
207
    - update_throughput_parameters: New throughput configuration
208
    
209
    Returns:
210
    LROPoller[ThroughputSettingsGetResults]: Poller for monitoring operation progress
211
    """
212

213
def get_sql_container_throughput(
214
    self,
215
    resource_group_name: str,
216
    account_name: str,
217
    database_name: str,
218
    container_name: str
219
) -> ThroughputSettingsGetResults:
220
    """
221
    Get throughput settings for a SQL container.
222
    
223
    Parameters:
224
    - resource_group_name: Name of the resource group
225
    - account_name: Name of the Cosmos DB account
226
    - database_name: Name of the SQL database
227
    - container_name: Name of the SQL container
228
    
229
    Returns:
230
    ThroughputSettingsGetResults: Current throughput configuration
231
    """
232

233
def begin_migrate_sql_database_to_autoscale(
234
    self,
235
    resource_group_name: str,
236
    account_name: str,
237
    database_name: str
238
) -> LROPoller[ThroughputSettingsGetResults]:
239
    """
240
    Migrate SQL database from manual to autoscale throughput (Long Running Operation).
241
    
242
    Parameters:
243
    - resource_group_name: Name of the resource group
244
    - account_name: Name of the Cosmos DB account
245
    - database_name: Name of the SQL database
246
    
247
    Returns:
248
    LROPoller[ThroughputSettingsGetResults]: Poller for monitoring operation progress
249
    """
250

251
def begin_migrate_sql_database_to_manual_throughput(
252
    self,
253
    resource_group_name: str,
254
    account_name: str,
255
    database_name: str
256
) -> LROPoller[ThroughputSettingsGetResults]:
257
    """
258
    Migrate SQL database from autoscale to manual throughput (Long Running Operation).
259
    
260
    Parameters:
261
    - resource_group_name: Name of the resource group
262
    - account_name: Name of the Cosmos DB account
263
    - database_name: Name of the SQL database
264
    
265
    Returns:
266
    LROPoller[ThroughputSettingsGetResults]: Poller for monitoring operation progress
267
    """
268
```
269

270
### Stored Procedures Management
271

272
Manage server-side logic execution with stored procedures.
273

274
```python { .api }
275
def list_sql_stored_procedures(
276
    self,
277
    resource_group_name: str,
278
    account_name: str,
279
    database_name: str,
280
    container_name: str
281
) -> ItemPaged[SqlStoredProcedureGetResults]:
282
    """
283
    List SQL stored procedures in a container.
284
    
285
    Parameters:
286
    - resource_group_name: Name of the resource group
287
    - account_name: Name of the Cosmos DB account
288
    - database_name: Name of the SQL database
289
    - container_name: Name of the SQL container
290
    
291
    Returns:
292
    ItemPaged[SqlStoredProcedureGetResults]: Paginated list of stored procedures
293
    """
294

295
def get_sql_stored_procedure(
296
    self,
297
    resource_group_name: str,
298
    account_name: str,
299
    database_name: str,
300
    container_name: str,
301
    stored_procedure_name: str
302
) -> SqlStoredProcedureGetResults:
303
    """
304
    Get properties of a SQL stored procedure.
305
    
306
    Parameters:
307
    - resource_group_name: Name of the resource group
308
    - account_name: Name of the Cosmos DB account
309
    - database_name: Name of the SQL database
310
    - container_name: Name of the SQL container
311
    - stored_procedure_name: Name of the stored procedure
312
    
313
    Returns:
314
    SqlStoredProcedureGetResults: Stored procedure properties and body
315
    """
316

317
def begin_create_update_sql_stored_procedure(
318
    self,
319
    resource_group_name: str,
320
    account_name: str,
321
    database_name: str,
322
    container_name: str,
323
    stored_procedure_name: str,
324
    create_update_sql_stored_procedure_parameters: SqlStoredProcedureCreateUpdateParameters
325
) -> LROPoller[SqlStoredProcedureGetResults]:
326
    """
327
    Create or update a SQL stored procedure (Long Running Operation).
328
    
329
    Parameters:
330
    - resource_group_name: Name of the resource group
331
    - account_name: Name of the Cosmos DB account
332
    - database_name: Name of the SQL database
333
    - container_name: Name of the SQL container
334
    - stored_procedure_name: Name of the stored procedure to create/update
335
    - create_update_sql_stored_procedure_parameters: Stored procedure configuration
336
    
337
    Returns:
338
    LROPoller[SqlStoredProcedureGetResults]: Poller for monitoring operation progress
339
    """
340
```
341

342
### Triggers and User-Defined Functions
343

344
Manage triggers and user-defined functions for advanced data processing scenarios.
345

346
```python { .api }
347
def list_sql_triggers(
348
    self,
349
    resource_group_name: str,
350
    account_name: str,
351
    database_name: str,
352
    container_name: str
353
) -> ItemPaged[SqlTriggerGetResults]:
354
    """
355
    List SQL triggers in a container.
356
    
357
    Parameters:
358
    - resource_group_name: Name of the resource group
359
    - account_name: Name of the Cosmos DB account
360
    - database_name: Name of the SQL database
361
    - container_name: Name of the SQL container
362
    
363
    Returns:
364
    ItemPaged[SqlTriggerGetResults]: Paginated list of triggers
365
    """
366

367
def list_sql_user_defined_functions(
368
    self,
369
    resource_group_name: str,
370
    account_name: str,
371
    database_name: str,
372
    container_name: str
373
) -> ItemPaged[SqlUserDefinedFunctionGetResults]:
374
    """
375
    List SQL user-defined functions in a container.
376
    
377
    Parameters:
378
    - resource_group_name: Name of the resource group
379
    - account_name: Name of the Cosmos DB account
380
    - database_name: Name of the SQL database
381
    - container_name: Name of the SQL container
382
    
383
    Returns:
384
    ItemPaged[SqlUserDefinedFunctionGetResults]: Paginated list of UDFs
385
    """
386

387
def begin_create_update_sql_trigger(
388
    self,
389
    resource_group_name: str,
390
    account_name: str,
391
    database_name: str,
392
    container_name: str,
393
    trigger_name: str,
394
    create_update_sql_trigger_parameters: SqlTriggerCreateUpdateParameters
395
) -> LROPoller[SqlTriggerGetResults]:
396
    """
397
    Create or update a SQL trigger (Long Running Operation).
398
    
399
    Parameters:
400
    - resource_group_name: Name of the resource group
401
    - account_name: Name of the Cosmos DB account
402
    - database_name: Name of the SQL database
403
    - container_name: Name of the SQL container
404
    - trigger_name: Name of the trigger to create/update
405
    - create_update_sql_trigger_parameters: Trigger configuration
406
    
407
    Returns:
408
    LROPoller[SqlTriggerGetResults]: Poller for monitoring operation progress
409
    """
410
```
411

412
### Security and RBAC
413

414
Manage role-based access control and client encryption keys for advanced security scenarios.
415

416
```python { .api }
417
def list_sql_role_definitions(
418
    self,
419
    resource_group_name: str,
420
    account_name: str
421
) -> ItemPaged[SqlRoleDefinitionGetResults]:
422
    """
423
    List SQL role definitions for RBAC.
424
    
425
    Parameters:
426
    - resource_group_name: Name of the resource group
427
    - account_name: Name of the Cosmos DB account
428
    
429
    Returns:
430
    ItemPaged[SqlRoleDefinitionGetResults]: Paginated list of role definitions
431
    """
432

433
def get_sql_role_definition(
434
    self,
435
    resource_group_name: str,
436
    account_name: str,
437
    role_definition_id: str
438
) -> SqlRoleDefinitionGetResults:
439
    """
440
    Get properties of a SQL role definition.
441
    
442
    Parameters:
443
    - resource_group_name: Name of the resource group
444
    - account_name: Name of the Cosmos DB account
445
    - role_definition_id: Unique identifier of the role definition
446
    
447
    Returns:
448
    SqlRoleDefinitionGetResults: Role definition properties and permissions
449
    """
450

451
def begin_create_update_sql_role_definition(
452
    self,
453
    resource_group_name: str,
454
    account_name: str,
455
    role_definition_id: str,
456
    create_update_sql_role_definition_parameters: SqlRoleDefinitionCreateUpdateParameters
457
) -> LROPoller[SqlRoleDefinitionGetResults]:
458
    """
459
    Create or update a SQL role definition (Long Running Operation).
460
    
461
    Parameters:
462
    - resource_group_name: Name of the resource group
463
    - account_name: Name of the Cosmos DB account
464
    - role_definition_id: Unique identifier of the role definition
465
    - create_update_sql_role_definition_parameters: Role definition configuration
466
    
467
    Returns:
468
    LROPoller[SqlRoleDefinitionGetResults]: Poller for monitoring operation progress
469
    """
470

471
def list_client_encryption_keys(
472
    self,
473
    resource_group_name: str,
474
    account_name: str,
475
    database_name: str
476
) -> ItemPaged[ClientEncryptionKeyGetResults]:
477
    """
478
    List client encryption keys in a database.
479
    
480
    Parameters:
481
    - resource_group_name: Name of the resource group
482
    - account_name: Name of the Cosmos DB account
483
    - database_name: Name of the SQL database
484
    
485
    Returns:
486
    ItemPaged[ClientEncryptionKeyGetResults]: Paginated list of encryption keys
487
    """
488
```
489

490
## Usage Examples
491

492
### Creating a SQL Database with Shared Throughput
493

494
```python
495
from azure.mgmt.cosmosdb import CosmosDBManagementClient
496
from azure.mgmt.cosmosdb.models import SqlDatabaseCreateUpdateParameters, SqlDatabaseResource, CreateUpdateOptions
497
from azure.identity import DefaultAzureCredential
498

499
client = CosmosDBManagementClient(DefaultAzureCredential(), "subscription-id")
500

501
# Define database configuration with shared throughput
502
database_params = SqlDatabaseCreateUpdateParameters(
503
    resource=SqlDatabaseResource(id="products-db"),
504
    options=CreateUpdateOptions(throughput=800)  # Shared throughput
505
)
506

507
# Create database
508
poller = client.sql_resources.begin_create_update_sql_database(
509
    "my-resource-group",
510
    "my-cosmos-account",
511
    "products-db",
512
    database_params
513
)
514

515
database = poller.result()
516
print(f"Created database: {database.name}")
517
```
518

519
### Creating a SQL Container with Partitioning and Indexing
520

521
```python
522
from azure.mgmt.cosmosdb.models import (
523
    SqlContainerCreateUpdateParameters,
524
    SqlContainerResource,
525
    ContainerPartitionKey,
526
    IndexingPolicy,
527
    IncludedPath,
528
    ExcludedPath
529
)
530

531
# Define container configuration
532
container_resource = SqlContainerResource(
533
    id="products",
534
    partition_key=ContainerPartitionKey(
535
        paths=["/category"],
536
        kind="Hash"
537
    ),
538
    indexing_policy=IndexingPolicy(
539
        indexing_mode="Consistent",
540
        automatic=True,
541
        included_paths=[
542
            IncludedPath(path="/*")
543
        ],
544
        excluded_paths=[
545
            ExcludedPath(path="/description/*")
546
        ]
547
    )
548
)
549

550
container_params = SqlContainerCreateUpdateParameters(
551
    resource=container_resource,
552
    options=CreateUpdateOptions(throughput=400)  # Dedicated throughput
553
)
554

555
# Create container
556
poller = client.sql_resources.begin_create_update_sql_container(
557
    "my-resource-group",
558
    "my-cosmos-account",
559
    "products-db",
560
    "products",
561
    container_params
562
)
563

564
container = poller.result()
565
print(f"Created container: {container.name} with partition key: {container.resource.partition_key.paths}")
566
```
567

568
### Managing Throughput Settings
569

570
```python
571
from azure.mgmt.cosmosdb.models import ThroughputSettingsUpdateParameters, ThroughputSettingsResource, AutoscaleSettings
572

573
# Update to autoscale throughput
574
autoscale_params = ThroughputSettingsUpdateParameters(
575
    resource=ThroughputSettingsResource(
576
        autoscale_settings=AutoscaleSettings(max_throughput=4000)
577
    )
578
)
579

580
poller = client.sql_resources.begin_update_sql_database_throughput(
581
    "my-resource-group",
582
    "my-cosmos-account",
583
    "products-db",
584
    autoscale_params
585
)
586

587
throughput = poller.result()
588
print(f"Updated to autoscale with max RU/s: {throughput.resource.autoscale_settings.max_throughput}")
589

590
# Migrate to manual throughput
591
poller = client.sql_resources.begin_migrate_sql_database_to_manual_throughput(
592
    "my-resource-group",
593
    "my-cosmos-account",
594
    "products-db"
595
)
596
throughput = poller.result()
597
print(f"Migrated to manual throughput: {throughput.resource.throughput} RU/s")
598
```
599

600
## Key Types
601

602
```python { .api }
603
class SqlDatabaseGetResults:
604
    """SQL database properties and configuration."""
605
    id: str
606
    name: str
607
    type: str
608
    resource: SqlDatabaseGetPropertiesResource
609
    options: SqlDatabaseGetPropertiesOptions
610

611
class SqlDatabaseResource:
612
    """SQL database resource definition."""
613
    id: str  # Database name
614

615
class SqlContainerGetResults:
616
    """SQL container properties and configuration."""
617
    id: str
618
    name: str
619
    type: str
620
    resource: SqlContainerGetPropertiesResource
621
    options: SqlContainerGetPropertiesOptions
622

623
class SqlContainerResource:
624
    """SQL container resource definition."""
625
    id: str  # Container name
626
    partition_key: ContainerPartitionKey
627
    indexing_policy: IndexingPolicy
628
    unique_key_policy: UniqueKeyPolicy
629
    conflict_resolution_policy: ConflictResolutionPolicy
630
    default_ttl: int
631
    analytical_storage_ttl: int
632

633
class ContainerPartitionKey:
634
    """Partition key configuration for containers."""
635
    paths: List[str]  # Partition key paths (e.g., ["/category"])
636
    kind: str  # "Hash" or "Range"
637
    version: int  # Partition key version (1 or 2)
638

639
class IndexingPolicy:
640
    """Indexing policy configuration for containers."""
641
    indexing_mode: str  # "Consistent", "Lazy", "None"
642
    automatic: bool
643
    included_paths: List[IncludedPath]
644
    excluded_paths: List[ExcludedPath]
645
    composite_indexes: List[List[CompositePath]]
646
    spatial_indexes: List[SpatialSpec]
647

648
class ThroughputSettingsGetResults:
649
    """Throughput settings and configuration."""
650
    id: str
651
    name: str
652
    type: str
653
    resource: ThroughputSettingsGetPropertiesResource
654
    
655
class ThroughputSettingsResource:
656
    """Throughput resource definition."""
657
    throughput: int  # Manual throughput in RU/s
658
    autoscale_settings: AutoscaleSettings  # Autoscale configuration
659
    minimum_throughput: int  # Minimum allowed throughput
660

661
class AutoscaleSettings:
662
    """Autoscale throughput configuration."""
663
    max_throughput: int  # Maximum RU/s for autoscale
664

665
class SqlStoredProcedureGetResults:
666
    """SQL stored procedure properties and body."""
667
    id: str
668
    name: str
669
    type: str
670
    resource: SqlStoredProcedureGetPropertiesResource
671

672
class SqlStoredProcedureResource:
673
    """SQL stored procedure resource definition."""
674
    id: str  # Stored procedure name
675
    body: str  # JavaScript code body
676

677
class SqlRoleDefinitionGetResults:
678
    """SQL role definition for RBAC."""
679
    id: str
680
    name: str
681
    type: str
682
    role_name: str
683
    type_value: str  # "BuiltInRole" or "CustomRole"
684
    assignable_scopes: List[str]
685
    permissions: List[Permission]
686

687
class Permission:
688
    """Permission definition for RBAC roles."""
689
    data_actions: List[str]  # Allowed data plane actions
690
    not_data_actions: List[str]  # Denied data plane actions
691
```