Skip to content

Commit b626549

Browse files
PMEds28PMEds28
authored
Merge pull request #94580 from deborahc/dech-cosmos-sdk-updates
Updating python quickstart to use v4
2 parents d7286f7 + 55ff0ab commit b626549

File tree

2 files changed

+60
-69
lines changed

2 files changed

+60
-69
lines changed

‎.openpublishing.publish.config.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -342,6 +342,11 @@
342342
"url": "https://github.com/Azure-Samples/azure-cosmos-db-sql-api-nodejs-getting-started",
343343
"branch": "master"
344344
},
345+
{
346+
"path_to_root": "azure-cosmos-db-python-getting-started",
347+
"url": "https://github.com/Azure-Samples/azure-cosmos-db-python-getting-started",
348+
"branch": "master"
349+
},
345350
{
346351
"path_to_root": "cognitive-services-content-moderator-samples",
347352
"url": "https://github.com/Azure-Samples/cognitive-services-content-moderator-samples",

‎articles/cosmos-db/create-sql-api-python.md

Lines changed: 55 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ ms.service: cosmos-db
66
ms.subservice: cosmosdb-sql
77
ms.devlang: python
88
ms.topic: quickstart
9-
ms.date: 05/21/2019
9+
ms.date: 11/03/2019
1010
ms.author: sngun
1111
ms.custom: [seodec18, seo-javascript-september2019, seo-python-october2019]
1212
---
@@ -24,7 +24,7 @@ This quickstart demonstrates how to create an Azure Cosmos DB [SQL API](sql-api-
2424

2525
Azure Cosmos DB is Microsoft’s globally distributed multi-model database service. You can quickly create and query documents, key/value, wide column and graph databases. All of these operations benefit from the distribution and scale of Azure Cosmos DB.
2626

27-
This quickstart uses version 3.0 of the [Python SDK](https://pypi.org/project/azure-cosmos).
27+
This quickstart uses version 4 of the [Python SDK](https://pypi.org/project/azure-cosmos/#history).
2828

2929
[!INCLUDE [quickstarts-free-trial-note](../../includes/quickstarts-free-trial-note.md)] [!INCLUDE [cosmos-db-emulator-docdb-api](../../includes/cosmos-db-emulator-docdb-api.md)]
3030

@@ -81,92 +81,50 @@ Now let's clone a SQL API app from GitHub, set the connection string, and run it
8181

8282
Now go back to the Azure portal to get your connection string information and copy it into the app.
8383

84-
1. In the [Azure portal](https://portal.azure.com/), in your Azure Cosmos account, in the left navigation select **Keys**. You'll use the copy buttons on the right side of the screen to copy the **URI** and **Primary Key** into the `CosmosGetStarted.py` file in the next step.
84+
1. In the [Azure portal](https://portal.azure.com/), in your Azure Cosmos account, in the left navigation select **Keys**. You'll use the copy buttons on the right side of the screen to copy the **URI** and **Primary Key** into the `cosmos_get_started.py` file in the next step.
8585
8686
![Get an access key and URI in the Keys settings in the Azure portal](./media/create-sql-api-dotnet/access-key-and-uri-in-keys-settings-in-the-azure-portal.png)
8787
88-
2. Open the `CosmosGetStarted.py` file in \git-samples\azure-cosmos-db-python-getting-started in Visual Studio Code.
88+
2. Open the `cosmos_get_started.py` file in \git-samples\azure-cosmos-db-python-getting-started in Visual Studio Code.
8989
90-
3. Copy your **URI** value from the portal (using the copy button) and make it the value of the **endpoint** key in ``CosmosGetStarted.py``.
90+
3. Copy your **URI** value from the portal (using the copy button) and make it the value of the **endpoint** variable in ``cosmos_get_started.py``.
9191
92-
`'ENDPOINT': 'https://FILLME.documents.azure.com',`
92+
`endpoint = 'https://FILLME.documents.azure.com',`
9393
94-
4. Then copy your **PRIMARY KEY** value from the portal and make it the value of the **config.PRIMARYKEY** in ``CosmosGetStarted.py``. You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.
94+
4. Then copy your **PRIMARY KEY** value from the portal and make it the value of the **key** in ``cosmos_get_started.py``. You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.
9595

96-
`'PRIMARYKEY': 'FILLME',`
96+
`key = 'FILLME'`
9797

98-
5. Save the ``CosmosGetStarted.py`` file.
98+
5. Save the ``cosmos_get_started.py`` file.
9999

100100
## Review the code
101101

102102
This step is optional. Learn about the database resources created in code, or skip ahead to [Update your connection string](#update-your-connection-string).
103103

104-
Note, if you are familiar with the previous version of the Python SDK, you may be used to seeing the terms "collection" and "document." Because Azure Cosmos DB supports multiple API models, version 3.0+ of the Python SDK uses the generic terms "container,", which may be a collection, graph, or table and "item" to describe the content of the container.
104+
The following snippets are all taken from the `cosmos_get_started.py` file.
105105

106-
The following snippets are all taken from the `CosmosGetStarted.py` file.
106+
* The CosmosClient is initialized. Make sure to update the "endpoint" and "key" values as described in the [Update your connection string](#update-your-connection-string) section.
107107

108-
* The CosmosClient is initialized. Make sure to update the "Endpoint" and "master key" values as described in the [Update your connection string](#update-your-connection-string) section.
109-
110-
```python
111-
# Initialize the Cosmos client
112-
client = cosmos_client.CosmosClient(url_connection=config['ENDPOINT'], auth={'masterKey': config['MASTERKEY']})
113-
```
108+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=create_cosmos_client)]
114109

115110
* A new database is created.
116111

117-
```python
118-
# Create a database
119-
db = client.CreateDatabase({ 'id': config['DATABASE'] })
120-
```
112+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=create_database_if_not_exists)]
121113

122-
* A new container is created.
114+
* A new container is created, with 400 RU/s of [provisioned throughput](request-units.md). We choose `lastName` as the [partition key](partitioning-overview.md#choose-partitionkey), which allows us to do efficient queries that filter on this property.
123115

124-
```python
125-
# Create container options
126-
options = {
127-
'offerThroughput': 400
128-
}
116+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=create_container_if_not_exists)]
129117

130-
# Create a container
131-
container = client.CreateContainer(db['_self'], container_definition, options)
132-
```
118+
* Some items are added to the container. Containers are a collection of items (JSON documents) that can have varied schema. The helper methods ```get_[name]_family_item``` return representations of a family that are stored in Azure Cosmos DB as JSON documents.
133119

134-
* Some items are added to the container.
120+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=create_item)]
135121

136-
```python
137-
# Create and add some items to the container
138-
item1 = client.CreateItem(container['_self'], {
139-
'serverId': 'server1',
140-
'Web Site': 0,
141-
'Cloud Service': 0,
142-
'Virtual Machine': 0,
143-
'message': 'Hello World from Server 1!'
144-
}
145-
)
146-
147-
item2 = client.CreateItem(container['_self'], {
148-
'serverId': 'server2',
149-
'Web Site': 1,
150-
'Cloud Service': 0,
151-
'Virtual Machine': 0,
152-
'message': 'Hello World from Server 2!'
153-
}
154-
)
155-
```
156-
157-
* A query is performed using SQL
158-
159-
```python
160-
query = {'query': 'SELECT * FROM server s'}
122+
* Point reads (key value lookups) are performed using the `read_item` method. We print out the [RU charge](request-units.md) of each operation.
123+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=read_item)]
161124

162-
options = {}
163-
options['enableCrossPartitionQuery'] = True
164-
options['maxItemCount'] = 2
125+
* A query is performed using SQL query syntax. Because we're using partition key values of ```lastName``` in the WHERE clause, Azure Cosmos DB will efficiently route this query to the relevant partitions, improving performance.
165126
166-
result_iterable = client.QueryItems(container['_self'], query, options)
167-
for item in iter(result_iterable):
168-
print(item['message'])
169-
```
127+
[!code-python[](~/azure-cosmos-db-python-getting-started/cosmos_get_started.py?name=query_items)]
170128
171129
## Run the app
172130
@@ -187,20 +145,48 @@ The following snippets are all taken from the `CosmosGetStarted.py` file.
187145
5. Run the following command to install the azure-cosmos package.
188146
189147
```python
190-
pip3 install azure-cosmos
148+
pip3 install azure-cosmos==4.0.0b5
191149
```
192150
193151
If you get an error about access being denied when attempting to install azure-cosmos, you'll need to [run VS Code as an administrator](https://stackoverflow.com/questions/37700536/visual-studio-code-terminal-how-to-run-a-command-with-administrator-rights).
194152

195-
6. Run the following command to run the sample and create and store new documents in Azure Cosmos dB.
153+
6. Run the following command to run the sample and create and store new documents in Azure Cosmos DB.
196154

197155
```python
198-
python CosmosGetStarted.py
156+
python cosmos_get_started.py
199157
```
200158

201-
7. To confirm the new items were created and saved, in the Azure portal, select **Data Explorer**, expand **coll**, expand **Documents**, and then select the **server1** document. The server1 document contents match the content returned in the integrated terminal window.
202-
203-
![View the new documents in the Azure portal](./media/create-sql-api-python/azure-cosmos-db-confirm-documents.png)
159+
7. To confirm the new items were created and saved, in the Azure portal, select **Data Explorer** > **AzureSampleFamilyDatabase** > **Items**. View the items that were created. For example, here is a sample JSON document for the Wakefield family:
160+
161+
```json
162+
{
163+
"id": "Andersen-1569479288379",
164+
"lastName": "Andersen",
165+
"district": "WA5",
166+
"parents": [
167+
{
168+
"familyName": null,
169+
"firstName": "Thomas"
170+
},
171+
{
172+
"familyName": null,
173+
"firstName": "Mary Kay"
174+
}
175+
],
176+
"children": null,
177+
"address": {
178+
"state": "WA",
179+
"county": "King",
180+
"city": "Seattle"
181+
},
182+
"registered": true,
183+
"_rid": "8K5qAIYtZXeBhB4AAAAAAA==",
184+
"_self": "dbs/8K5qAA==/colls/8K5qAIYtZXc=/docs/8K5qAIYtZXeBhB4AAAAAAA==/",
185+
"_etag": "\"a3004d78-0000-0800-0000-5d8c5a780000\"",
186+
"_attachments": "attachments/",
187+
"_ts": 1569479288
188+
}
189+
```
204190

205191
## Review SLAs in the Azure portal
206192

0 commit comments

Comments
 (0)