Skip to content

Commit 17c1287

Browse files
committed
Update docs metadata
1 parent 025d9f1 commit 17c1287

File tree

2 files changed

+45
-34
lines changed

2 files changed

+45
-34
lines changed

docs-ref-services/preview/cosmos-readme.md

Lines changed: 43 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
title: Azure Cosmos DB SQL API client library for Python
33
keywords: Azure, python, SDK, API, azure-cosmos, cosmosdb
44
author: kushagraThapar
5-
ms.author: kushagraThapar
6-
ms.date: 01/25/2022
5+
ms.author: kuthapar
6+
ms.date: 03/10/2022
77
ms.topic: reference
88
ms.prod: azure
99
ms.technology: azure
@@ -13,7 +13,7 @@ ms.service: cosmosdb
1313
## _Disclaimer_
1414
_Azure SDK Python packages support for Python 2.7 has ended 01 January 2022. For more information and questions, please refer to https://github.com/Azure/azure-sdk-for-python/issues/20691_
1515

16-
# Azure Cosmos DB SQL API client library for Python - Version 4.3.0b2
16+
# Azure Cosmos DB SQL API client library for Python - Version 4.3.0b3
1717

1818

1919
Azure Cosmos DB is a globally distributed, multi-model database service that supports document, key-value, wide-column, and graph databases.
@@ -33,7 +33,7 @@ Use the Azure Cosmos DB SQL API SDK for Python to manage databases and the JSON
3333

3434
### Important update on Python 2.x Support
3535

36-
New releases of this SDK won't support Python 2.x starting January 1st, 2022. Please check the [CHANGELOG](https://github.com/Azure/azure-sdk-for-python/blob/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos/CHANGELOG.md) for more information.
36+
New releases of this SDK won't support Python 2.x starting January 1st, 2022. Please check the [CHANGELOG](https://github.com/Azure/azure-sdk-for-python/blob/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos/CHANGELOG.md) for more information.
3737

3838
### Prerequisites
3939

@@ -110,6 +110,20 @@ The keyword-argument `enable_cross_partition_query` accepts 2 options: `None` (d
110110

111111
When using queries that try to find items based on an **id** value, always make sure you are passing in a string type variable. Azure Cosmos DB only allows string id values and if you use any other datatype, this SDK will return no results and no error messages.
112112

113+
## Note on client consistency levels
114+
115+
As of release version 4.3.0b3, if a user does not pass in an explicit consistency level to their client initialization,
116+
their client will use their database account's default level. Previously, the default was being set to `Session` consistency.
117+
If for some reason you'd like to keep doing this, you can change your client initialization to include the explicit parameter for this like shown:
118+
```Python
119+
from azure.cosmos import CosmosClient
120+
121+
import os
122+
URL = os.environ['ACCOUNT_URI']
123+
KEY = os.environ['ACCOUNT_KEY']
124+
client = CosmosClient(URL, credential=KEY, consistency_level='Session')
125+
```
126+
113127
## Limitations
114128

115129
Currently the features below are **not supported**. For alternatives options, check the **Workarounds** section below.
@@ -127,8 +141,6 @@ Currently the features below are **not supported**. For alternatives options, ch
127141
* Change Feed: Read from the beggining
128142
* Change Feed: Pull model
129143
* Cross-partition ORDER BY for mixed types
130-
* 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`.
131-
* Cross partition queries do not handle partition splits (410 Gone errors)
132144

133145
### Control Plane Limitations:
134146

@@ -152,16 +164,12 @@ If you want to use Python SDK to perform bulk inserts to Cosmos DB, the best alt
152164

153165
### Control Plane Limitations Workaround
154166

155-
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/cli/azure/azure-cli-reference-for-cosmos-db) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations.
167+
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/cli/azure/azure-cli-reference-for-cosmos-db) or [PowerShell](https://docs.microsoft.com/azure/cosmos-db/manage-with-powershell) for the control plane unsupported limitations.
156168

157169
### AAD Support Workaround
158170

159171
A possible workaround is to use managed identities to [programmatically](https://docs.microsoft.com/azure/cosmos-db/managed-identity-based-authentication) get the keys.
160172

161-
## Consistency Level
162-
163-
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.
164-
165173
## Boolean Data Type
166174

167175
While the Python language [uses](https://docs.python.org/3/library/stdtypes.html?highlight=boolean#truth-value-testing) "True" and "False" for boolean types, Cosmos DB [accepts](https://docs.microsoft.com/azure/cosmos-db/sql-query-is-bool) "true" and "false" only. In other words, the Python language uses Boolean values with the first uppercase letter and all other lowercase letters, while Cosmos DB and its SQL language use only lowercase letters for those same Boolean values. How to deal with this challenge?
@@ -452,20 +460,22 @@ For more information on TTL, see [Time to Live for Azure Cosmos DB data][cosmos_
452460
### Using the asynchronous client (Preview)
453461

454462
The asynchronous cosmos client is a separate client that looks and works in a similar fashion to the existing synchronous client. However, the async client needs to be imported separately and its methods need to be used with the async/await keywords.
463+
The Async client needs to be initialized and closed after usage. The example below shows how to do so by using the client's __aenter__() and close() methods.
455464

456465
```Python
457466
from azure.cosmos.aio import CosmosClient
458467
import os
459468

460469
URL = os.environ['ACCOUNT_URI']
461470
KEY = os.environ['ACCOUNT_KEY']
462-
client = CosmosClient(URL, credential=KEY)
463471
DATABASE_NAME = 'testDatabase'
464-
database = client.get_database_client(DATABASE_NAME)
465-
CONTAINER_NAME = 'products'
466-
container = database.get_container_client(CONTAINER_NAME)
472+
CONTAINER_NAME = 'products'
467473

468-
async def create_items():
474+
async def create_products():
475+
client = CosmosClient(URL, credential=KEY)
476+
await client.__aenter__()
477+
database = client.get_database_client(DATABASE_NAME)
478+
container = database.get_container_client(CONTAINER_NAME)
469479
for i in range(10):
470480
await container.upsert_item({
471481
'id': 'item{0}'.format(i),
@@ -476,7 +486,7 @@ async def create_items():
476486
await client.close() # the async client must be closed manually if it's not initialized in a with statement
477487
```
478488

479-
It is also worth pointing out that the asynchronous client has to be closed manually after its use, either by initializing it using async with or calling the close() method directly like shown above.
489+
Instead of manually opening and closing the client, it is highly recommended to use the `async with` keywords. This creates a context manager that will initialize and later close the client once you're out of the statement. The example below shows how to do so.
480490

481491
```Python
482492
from azure.cosmos.aio import CosmosClient
@@ -487,16 +497,17 @@ KEY = os.environ['ACCOUNT_KEY']
487497
DATABASE_NAME = 'testDatabase'
488498
CONTAINER_NAME = 'products'
489499

490-
async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically close the async client
491-
database = client.get_database_client(DATABASE_NAME)
492-
container = database.get_container_client(CONTAINER_NAME)
493-
for i in range(10):
494-
await container.upsert_item({
495-
'id': 'item{0}'.format(i),
496-
'productName': 'Widget',
497-
'productModel': 'Model {0}'.format(i)
498-
}
499-
)
500+
async def create_products():
501+
async with CosmosClient(URL, credential=KEY) as client: # the with statement will automatically initialize and close the async client
502+
database = client.get_database_client(DATABASE_NAME)
503+
container = database.get_container_client(CONTAINER_NAME)
504+
for i in range(10):
505+
await container.upsert_item({
506+
'id': 'item{0}'.format(i),
507+
'productName': 'Widget',
508+
'productModel': 'Model {0}'.format(i)
509+
}
510+
)
500511
```
501512

502513
### Queries with the asynchronous client (Preview)
@@ -598,7 +609,7 @@ For more extensive documentation on the Cosmos DB service, see the [Azure Cosmos
598609
[cosmos_container]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-containers
599610
[cosmos_database]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-databases
600611
[cosmos_docs]: https://docs.microsoft.com/azure/cosmos-db/
601-
[cosmos_samples]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos/samples
612+
[cosmos_samples]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos/samples
602613
[cosmos_pypi]: https://pypi.org/project/azure-cosmos/
603614
[cosmos_http_status_codes]: https://docs.microsoft.com/rest/api/cosmos-db/http-status-codes-for-cosmosdb
604615
[cosmos_item]: https://docs.microsoft.com/azure/cosmos-db/databases-containers-items#azure-cosmos-items
@@ -616,10 +627,10 @@ For more extensive documentation on the Cosmos DB service, see the [Azure Cosmos
616627
[ref_cosmosclient]: https://aka.ms/azsdk-python-cosmos-ref-cosmos-client
617628
[ref_database]: https://aka.ms/azsdk-python-cosmos-ref-database
618629
[ref_httpfailure]: https://aka.ms/azsdk-python-cosmos-ref-http-failure
619-
[sample_database_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos/samples/database_management.py
620-
[sample_document_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos/samples/document_management.py
621-
[sample_examples_misc]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos/samples/examples.py
622-
[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b2/sdk/cosmos/azure-cosmos
630+
[sample_database_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos/samples/database_management.py
631+
[sample_document_mgmt]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos/samples/document_management.py
632+
[sample_examples_misc]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos/samples/examples.py
633+
[source_code]: https://github.com/Azure/azure-sdk-for-python/tree/azure-cosmos_4.3.0b3/sdk/cosmos/azure-cosmos
623634
[venv]: https://docs.python.org/3/library/venv.html
624635
[virtualenv]: https://virtualenv.pypa.io
625636

metadata/preview/azure-cosmos.json

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"Name": "azure-cosmos",
3-
"Version": "4.3.0b2",
3+
"Version": "4.3.0b3",
44
"DevVersion": null,
55
"DirectoryPath": "sdk/cosmos/azure-cosmos",
66
"ServiceDirectory": "cosmos",
@@ -10,5 +10,5 @@
1010
"SdkType": "client",
1111
"IsNewSdk": true,
1212
"ArtifactName": "azure-cosmos",
13-
"ReleaseStatus": "2022-01-25"
13+
"ReleaseStatus": "2022-03-10"
1414
}

0 commit comments

Comments
 (0)