From d565a5ae36588583ff39f19f95a6169716a5e597 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Wed, 31 Mar 2021 20:16:25 -0700 Subject: [PATCH 01/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index af82608930e5..81355792bf50 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -2,7 +2,7 @@ Azure Cosmos DB is a globally distributed, multi-model database service that supports document, key-value, wide-column, and graph databases. -Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON documents they contain in this NoSQL database service. +Use 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: * Create Cosmos DB **databases** and modify their settings * Create and modify **containers** to store collections of JSON documents @@ -19,7 +19,7 @@ Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON * Azure subscription - [Create a free account][azure_sub] * Azure [Cosmos DB account][cosmos_account] - SQL API -* [Python 2.7 or 3.5.3+][python] +* [Python 2.7 or 3.6+][python] If you need a Cosmos DB SQL API account, you can create one with this [Azure CLI][azure_cli] command: @@ -103,7 +103,6 @@ Currently the features below are **not supported**. **Control Plane Limitations:** * Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metrics -* Create User * Create Geospatial Index * Provision Autoscale DBs or containers * Update Autoscale throughput @@ -214,9 +213,7 @@ 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. +The preceding snippets also handle 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 @@ -370,7 +367,7 @@ print('Found Offer \'{0}\' for Database \'{1}\' and its throughput is \'{2}\''.f # Container with dedicated throughput only. Will return error "offer not found" for containers without dedicated throughput container_name = 'testContainer' container = database.get_container_client(container_name) -container_offer = database.read_offer() +container_offer = container.read_offer() print('Found Offer \'{0}\' for Container \'{1}\' and its throughput is \'{2}\''.format(container_offer.properties['id'], container.id, container_offer.properties['content']['offerThroughput'])) ``` From 6269e947d3684e8db4dd8985edd5c2cbc59a8ad1 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 25 May 2021 15:17:32 -0700 Subject: [PATCH 02/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 57 +++++++++++++++++++------------ 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 81355792bf50..710edbfbdb16 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -87,37 +87,52 @@ Currently the features below are **not supported**. **Data Plane Limitations:** -* Group By queries (in roadmap for 2021) -* Language Native async i/o (in roadmap for 2021) -* Queries with COUNT from a DISTINCT subquery: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C) -* Bulk/Transactional batch processing -* Direct TCP Mode access -* Continuation token for cross partitions queries -* Change Feed: Processor -* Change Feed: Read multiple partitions key values -* Change Feed: Read specific time -* Change Feed: Read from the beggining -* Change Feed: Pull model -* Cross-partition ORDER BY for mixed types +* Group By queries (in roadmap for 2021). +* Language Native async i/o (in roadmap for 2021). +* Queries with COUNT from a DISTINCT subquery: SELECT COUNT (1) FROM (SELECT DISTINCT C.ID FROM C). +* Bulk/Transactional batch processing. +* Direct TCP Mode access. +* Continuation token for cross partitions queries. +* Change Feed: Processor. +* Change Feed: Read multiple partitions key values. +* Change Feed: Read specific time. +* Change Feed: Read from the beggining. +* Change Feed: Pull model. +* Cross-partition ORDER BY for mixed types. +* Integrated Cache using the default consistency level, that is "Session". To take advantage of the new [Cosmos DB Integrated Cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache), it is required to explicitly set CosmosClient consistency level to "Eventual": `consistency_level= Eventual`. **Control Plane Limitations:** -* Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metrics -* Create Geospatial Index -* Provision Autoscale DBs or containers -* Update Autoscale throughput -* Update analytical store ttl (time to live) -* Get the connection string -* Get the minimum RU/s of a container. +* Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metrics. +* Create Geospatial Index. +* Provision Autoscale DBs or containers. +* Update Autoscale throughput. +* Update analytical store ttl (time to live). +* Get the connection string. +* Get the minimum RU/s of a container. -## Bulk processing Limitation Workaround +**Security Limitations:** + +* AAD support. + +## Workarounds + +### Bulk processing Limitation 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/azure/cosmos-db/how-to-write-stored-procedures-triggers-udfs) to write multiple items with the same partition key. -## Control Plane Limitations Workaround +### Control Plane Limitations Workaround Typically you can use [Azure Portal](https://portal.azure.com/), [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. +### AAD Support + +A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) grab the keys. + + +## Consistency Level + +Please be aware that this SDK has "Session" as the default consistency level, and it **overrides** your Cosmos DB database account default option. Click [here](https://docs.microsoft.com/azure/cosmos-db/consistency-levels#eventual-consistency) to learn more about Cosmos DB consistency levels. ## Boolean Data Type From 9324c3a137eb784405438a930c7fefc9ca39e48d Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 18:08:36 -0700 Subject: [PATCH 03/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 710edbfbdb16..ad091b9095f3 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -83,9 +83,9 @@ For more information about these resources, see [Working with Azure Cosmos datab ## Limitations -Currently the features below are **not supported**. +Currently the features below are **not supported**. -**Data Plane Limitations:** +### Data Plane Limitations: * Group By queries (in roadmap for 2021). * Language Native async i/o (in roadmap for 2021). @@ -101,7 +101,7 @@ Currently the features below are **not supported**. * Cross-partition ORDER BY for mixed types. * Integrated Cache using the default consistency level, that is "Session". To take advantage of the new [Cosmos DB Integrated Cache](https://docs.microsoft.com/azure/cosmos-db/integrated-cache), it is required to explicitly set CosmosClient consistency level to "Eventual": `consistency_level= Eventual`. -**Control Plane Limitations:** +### Control Plane Limitations: * Get CollectionSizeUsage, DatabaseUsage, and DocumentUsage metrics. * Create Geospatial Index. @@ -111,7 +111,7 @@ Currently the features below are **not supported**. * Get the connection string. * Get the minimum RU/s of a container. -**Security Limitations:** +### Security Limitations: * AAD support. @@ -123,11 +123,11 @@ If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alt ### Control Plane Limitations Workaround -Typically you can use [Azure Portal](https://portal.azure.com/), [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. +Typically you can use [Azure Portal](https://portal.azure.com/),[Azure Cosmos DB Resource Provider REST API[https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/],[Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. ### AAD Support -A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) grab the keys. +A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) get the keys. ## Consistency Level From 84d2e3ded5a01bca5f008dd2234b8618f792a00a Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 18:14:46 -0700 Subject: [PATCH 04/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index ad091b9095f3..9a93a07e972c 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -83,7 +83,7 @@ For more information about these resources, see [Working with Azure Cosmos datab ## Limitations -Currently the features below are **not supported**. +Currently the features below are **not supported**. For some options, check the [Workarounds](#Workarounds) section. ### Data Plane Limitations: @@ -123,7 +123,7 @@ If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alt ### Control Plane Limitations Workaround -Typically you can use [Azure Portal](https://portal.azure.com/),[Azure Cosmos DB Resource Provider REST API[https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/],[Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. +Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/], [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. ### AAD Support From 6306e4fabb8979266248ac16be67b964b571ca8b Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 18:36:51 -0700 Subject: [PATCH 05/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 9a93a07e972c..2122b65be4df 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -129,7 +129,6 @@ Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos D A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) get the keys. - ## Consistency Level Please be aware that this SDK has "Session" as the default consistency level, and it **overrides** your Cosmos DB database account default option. Click [here](https://docs.microsoft.com/azure/cosmos-db/consistency-levels#eventual-consistency) to learn more about Cosmos DB consistency levels. @@ -151,6 +150,12 @@ Cosmos DB SQL language allows you to [get subitems by using the FROM clause](htt * For SQL queries using the `query_items` method, this SDK demands that you specify the `partition_key` or use the `enable_cross_partition_query` flag. * If you are getting subitems and specifying the `partition_key`, please make sure that your partition key is included in the subitems, which is not true for most of the cases. +## Max Item Count + +This is a parameter of the `query_items` method, an integer indicating the maximum number of items to be returned per page. In other SDKs, the `-1` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior in cases when it is not informed. + +However, in this version of this SDK, 4.x, if you want to force default behavior, you should use `None` instead of `-1`. Please be aware that previous versions of this SDK had different behavior. We may change this situation in future versions. + ## Examples The following sections provide several code snippets covering some of the most common Cosmos DB tasks, including: From 0ab620a56f77310fcf19d7d95793548b3684d551 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 18:40:33 -0700 Subject: [PATCH 06/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 2122b65be4df..0e09a0a6499e 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -152,9 +152,9 @@ Cosmos DB SQL language allows you to [get subitems by using the FROM clause](htt ## Max Item Count -This is a parameter of the `query_items` method, an integer indicating the maximum number of items to be returned per page. In other SDKs, the `-1` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior in cases when it is not informed. +This is a parameter of the `query_items` method, an integer indicating the maximum number of items to be returned per page. The `-1` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not informed. -However, in this version of this SDK, 4.x, if you want to force default behavior, you should use `None` instead of `-1`. Please be aware that previous versions of this SDK had different behavior. We may change this situation in future versions. +However, in this version of the Python SDK, 4.x, if you want to force default behavior, you should use `None` instead of `-1`. Please be aware that previous versions of this SDK have a different behavior. We may change this situation in future versions. ## Examples From f847d4df5b301874ca27981739e5129b2967c8b0 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 19:19:35 -0700 Subject: [PATCH 07/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 0e09a0a6499e..6f1c26c0cd00 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -83,7 +83,7 @@ For more information about these resources, see [Working with Azure Cosmos datab ## Limitations -Currently the features below are **not supported**. For some options, check the [Workarounds](#Workarounds) section. +Currently the features below are **not supported**. For some options, check the [Workarounds](#Workarounds "Workarounds") section. ### Data Plane Limitations: From 0a30cef11b6536a911f6b96afce7dfd1c7632b10 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 19:57:28 -0700 Subject: [PATCH 08/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 6f1c26c0cd00..6189a1a1615c 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -83,7 +83,7 @@ For more information about these resources, see [Working with Azure Cosmos datab ## Limitations -Currently the features below are **not supported**. For some options, check the [Workarounds](#Workarounds "Workarounds") section. +Currently the features below are **not supported**. For some options, check the [Workarounds](#workarounds "Workarounds") section. ### Data Plane Limitations: From 969afc529b27fbdf9ffc75a1872dde2ca43f4c01 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 20:17:59 -0700 Subject: [PATCH 09/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 6189a1a1615c..c9f78d7d9114 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -83,7 +83,7 @@ For more information about these resources, see [Working with Azure Cosmos datab ## Limitations -Currently the features below are **not supported**. For some options, check the [Workarounds](#workarounds "Workarounds") section. +Currently the features below are **not supported**. For alternatives options, check the **Workarounds** section below. ### Data Plane Limitations: From 9e970f19b545000c344ebd3f1b47b4535cee6e08 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 20:44:42 -0700 Subject: [PATCH 10/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index c9f78d7d9114..1a31d01d1963 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -123,9 +123,9 @@ If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alt ### Control Plane Limitations Workaround -Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider/], [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. +Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider], [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. -### AAD Support +### AAD Support Workaround A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) get the keys. From c72c57e7964545ba1009da8cb658a92ffe20cb41 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Tue, 1 Jun 2021 21:33:44 -0700 Subject: [PATCH 11/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 1a31d01d1963..8f442734a938 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -123,7 +123,7 @@ If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alt ### Control Plane Limitations Workaround -Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider], [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. +Typically you can use [Azure Portal](https://portal.azure.com/), [Azure Cosmos DB Resource Provider REST API](https://docs.microsoft.com/rest/api/cosmos-db-resource-provider), [Azure CLI](https://docs.microsoft.com/azure/cosmos-db/manage-with-cli) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations. ### AAD Support Workaround From b00081df2d328ed08452f6194fbd9c574c469532 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Mon, 7 Jun 2021 13:16:43 -0700 Subject: [PATCH 12/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index 8f442734a938..b7846220f5f7 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -152,7 +152,7 @@ Cosmos DB SQL language allows you to [get subitems by using the FROM clause](htt ## Max Item Count -This is a parameter of the `query_items` method, an integer indicating the maximum number of items to be returned per page. The `-1` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not informed. +This is a parameter of the query_items method, an integer indicating the maximum number of items to be returned per page. The `None` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not set. However, in this version of the Python SDK, 4.x, if you want to force default behavior, you should use `None` instead of `-1`. Please be aware that previous versions of this SDK have a different behavior. We may change this situation in future versions. From f2255fddc4aed15e6386780711ce2a8453ceed76 Mon Sep 17 00:00:00 2001 From: Rodrigo Souza Date: Mon, 7 Jun 2021 15:15:57 -0700 Subject: [PATCH 13/13] Update README.md --- sdk/cosmos/azure-cosmos/README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/sdk/cosmos/azure-cosmos/README.md b/sdk/cosmos/azure-cosmos/README.md index b7846220f5f7..ac6ad527ab21 100644 --- a/sdk/cosmos/azure-cosmos/README.md +++ b/sdk/cosmos/azure-cosmos/README.md @@ -154,8 +154,6 @@ Cosmos DB SQL language allows you to [get subitems by using the FROM clause](htt This is a parameter of the query_items method, an integer indicating the maximum number of items to be returned per page. The `None` value can be specified to let the service determine the optimal item count. This is the recommended configuration value, and the default behavior of this SDK when it is not set. -However, in this version of the Python SDK, 4.x, if you want to force default behavior, you should use `None` instead of `-1`. Please be aware that previous versions of this SDK have a different behavior. We may change this situation in future versions. - ## Examples The following sections provide several code snippets covering some of the most common Cosmos DB tasks, including: