diff --git a/sdk/cosmos/README.md b/sdk/cosmos/README.md index f870630f0abe..f6cd10f7be07 100644 --- a/sdk/cosmos/README.md +++ b/sdk/cosmos/README.md @@ -6,7 +6,7 @@ Use the Azure Cosmos DB SQL API SDKs for application development and database ma ## Contents of this folder -### azure-cosmos +### [azure-cosmos](./azure-cosmos) This is the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON documents they contain in this NoSQL database service. High level capabilities are: @@ -17,7 +17,7 @@ This is the Azure Cosmos DB SQL API SDK for Python to manage databases and the J Use this package if you are creating an application or exploring data. -### azure-mgmt-cosmosdb +### [azure-mgmt-cosmosdb](./azure-mgmt-cosmosdb) This is the Microsoft Azure Cosmos DB Management Client Library. High level capabilities are: @@ -34,7 +34,7 @@ This is the Microsoft Azure Cosmos DB Management Client Library. High level capa Use this package if you are creating an account level management application. -### azure-mgmt-documentdb +### [azure-mgmt-documentdb](./azure-mgmt-documentdb) Legacy DocumentDB SDK. diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 82506d3112e5..9792a2977a9e 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -11,14 +11,16 @@ Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON [SDK source code][source_code] | [Package (PyPI)][cosmos_pypi] | [API reference documentation][ref_cosmos_sdk] | [Product documentation][cosmos_docs] | [Samples][cosmos_samples] +> This SDK is used for the [SQL API](https://docs.microsoft.com/en-us/azure/cosmos-db/sql-query-getting-started). For all other APIs, please check the [Azure Cosmos DB documentation](https://docs.microsoft.com/en-us/azure/cosmos-db/introduction) to evaluate the best SDK for your project. ## Getting started + ### Prerequisites + * Azure subscription - [Create a free account][azure_sub] * Azure [Cosmos DB account][cosmos_account] - SQL API * [Python 2.7 or 3.5.3+][python] - If you need a Cosmos DB SQL API account, you can create one with this [Azure CLI][azure_cli] command: ```Bash @@ -39,6 +41,7 @@ Although not required, you can keep your base system and Azure SDK environments python3 -m venv azure-cosmosdb-sdk-environment source azure-cosmosdb-sdk-environment/bin/activate ``` + ### Authenticate the client Interaction with Cosmos DB starts with an instance of the [CosmosClient][ref_cosmosclient] class. You need an **account**, its **URI**, and one of its **account keys** to instantiate the client object. @@ -52,6 +55,7 @@ ACCT_NAME= export ACCOUNT_URI=$(az cosmosdb show --resource-group $RES_GROUP --name $ACCT_NAME --query documentEndpoint --output tsv) export ACCOUNT_KEY=$(az cosmosdb list-keys --resource-group $RES_GROUP --name $ACCT_NAME --query primaryMasterKey --output tsv) ``` + ### Create the client Once you've populated the `ACCOUNT_URI` and `ACCOUNT_KEY` environment variables, you can create the [CosmosClient][ref_cosmosclient]. @@ -77,12 +81,26 @@ Once you've initialized a [CosmosClient][ref_cosmosclient], you can interact wit For more information about these resources, see [Working with Azure Cosmos databases, containers and items][cosmos_resources]. +## Limitations + +As of August 2020 the features below are not yet supported. + +* Bulk/Batch processing +* Group By queries +* Direct TCP Mode access +* Language Native async i/o + +## Limitations Workaround + +If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alternative is to use [stored procedures](https://docs.microsoft.com/en-us/azure/cosmos-db/how-to-write-stored-procedures-triggers-udfs) to write multiple items with the same partition key. + ## Examples The following sections provide several code snippets covering some of the most common Cosmos DB tasks, including: * [Create a database](#create-a-database "Create a database") * [Create a container](#create-a-container "Create a container") +* [Create an Analytical Store Enabled container](#create-an-analytical-store-enabled-container "Create a container") * [Get an existing container](#get-an-existing-container "Get an existing container") * [Insert data](#insert-data "Insert data") * [Delete data](#delete-data "Delete data") @@ -131,6 +149,28 @@ except exceptions.CosmosHttpResponseError: raise ``` +### Create an Analytical Store enabled container + +This example creates a container with [Analytical Store](https://docs.microsoft.com/en-us/azure/cosmos-db/analytical-store-introduction) enabled, for reporting, BI, AI, and Advanced Analytics with [Azure Synapse Link](https://docs.microsoft.com/en-us/azure/cosmos-db/synapse-link). + +Options: + ++ 0 or Null = Not enabled. ++ -1 = The data will be stored infinitely. ++ Any other number is the actual ttl, in seconds. + +```Python +container_name = 'products' +try: + container = database.create_container(id=container_name, partition_key=PartitionKey(path="/productName"),analytical_storage_ttl=-1) +except exceptions.CosmosResourceExistsError: + container = database.get_container_client(container_name) +except exceptions.CosmosHttpResponseError: + raise +``` + +The preceding snippet also handles the [CosmosHttpResponseError][ref_httpfailure] exception if the container creation failed. For more information on error handling and troubleshooting, see the [Troubleshooting](#troubleshooting "Troubleshooting") section. + The preceding snippet also handles the [CosmosHttpResponseError][ref_httpfailure] exception if the container creation failed. For more information on error handling and troubleshooting, see the [Troubleshooting](#troubleshooting "Troubleshooting") section. ### Get an existing container diff --git a/sdk/cosmos/azure-cosmos/samples/container_management.py b/sdk/cosmos/azure-cosmos/samples/container_management.py index 9f0177f82b14..482715b92ce8 100644 --- a/sdk/cosmos/azure-cosmos/samples/container_management.py +++ b/sdk/cosmos/azure-cosmos/samples/container_management.py @@ -24,6 +24,7 @@ # 2.4 - Create container with unique key # 2.5 - Create Container with partition key V2 # 2.6 - Create Container with partition key V1 +# 2.7 - Create Container with analytical store enabled # # 3. Manage Container Provisioned Throughput # 3.1 - Get Container provisioned throughput (RU/s) @@ -67,8 +68,8 @@ def find_container(db, id): def create_container(db, id): - """ Execute the most basic Create of container. - This will create a container with 400 RUs throughput and default indexing policy """ + """ Execute basic container creation. + This will create containers with 400 RUs with different indexing, partitioning, and storage options """ partition_key = PartitionKey(path='/id', kind='Hash') print("\n2.1 Create Container - Basic") @@ -84,9 +85,8 @@ def create_container(db, id): try: coll = { - "id": "container_custom_index_policy", + "id": id+"_container_custom_index_policy", "indexingPolicy": { - "indexingMode": "lazy", "automatic": False } } @@ -107,9 +107,8 @@ def create_container(db, id): print("\n2.3 Create Container - With custom provisioned throughput") try: - coll = {"id": "container_custom_throughput"} container = db.create_container( - id=coll['id'], + id=id+"_container_custom_throughput", partition_key=partition_key, offer_throughput=400 ) @@ -122,7 +121,7 @@ def create_container(db, id): try: container = db.create_container( - id="container_unique_keys", + id= id+"_container_unique_keys", partition_key=partition_key, unique_key_policy={'uniqueKeys': [{'paths': ['/field1/field2', '/field3']}]} ) @@ -138,7 +137,7 @@ def create_container(db, id): try: container = db.create_container( - id="container_partition_key_v2", + id=id+"_container_partition_key_v2", partition_key=PartitionKey(path='/id', kind='Hash') ) properties = container.read() @@ -152,7 +151,7 @@ def create_container(db, id): try: container = db.create_container( - id="container_partition_key_v1", + id=id+"_container_partition_key_v1", partition_key=PartitionKey(path='/id', kind='Hash', version=1) ) properties = container.read() @@ -162,6 +161,21 @@ def create_container(db, id): except exceptions.CosmosResourceExistsError: print('A container with id \'container_partition_key_v1\' already exists') + print("\n2.7 Create Container - With analytical store enabled") + + try: + container = db.create_container( + id=id+"_container_analytical_store", + partition_key=PartitionKey(path='/id', kind='Hash',analytical_storage_ttl=-1) + ) + properties = container.read() + print('Container with id \'{0}\' created'.format(container.id)) + print('Partition Key - \'{0}\''.format(properties['partitionKey'])) + + except exceptions.CosmosResourceExistsError: + print('A container with id \'_container_analytical_store\' already exists') + + def manage_provisioned_throughput(db, id): print("\n3.1 Get Container provisioned throughput (RU/s)") diff --git a/sdk/cosmos/azure-cosmos/samples/index_management.py b/sdk/cosmos/azure-cosmos/samples/index_management.py index 169b2410d7f1..810c312beecb 100644 --- a/sdk/cosmos/azure-cosmos/samples/index_management.py +++ b/sdk/cosmos/azure-cosmos/samples/index_management.py @@ -22,7 +22,6 @@ # excludedPaths # # We can toggle 'automatic' to eiher be True or False depending upon whether we want to have indexing over all columns by default or not. -# indexingMode can be either of consistent, lazy or none # # We can provide options while creating documents. indexingDirective is one such, # by which we can tell whether it should be included or excluded in the index of the parent container.