Skip to content

Commit dda19c3

Browse files
PMEds28PMEds28
authored
Merge pull request #89507 from deborahc/dech-notebook-docs
Adding new how-to doc for notebook commands and features
2 parents e180049 + a7ada68 commit dda19c3

File tree

4 files changed

+161
-3
lines changed

4 files changed

+161
-3
lines changed

‎articles/cosmos-db/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -691,6 +691,8 @@
691691
items:
692692
- name: Enable notebooks
693693
href: enable-notebooks.md
694+
- name: Use built-in notebook commands
695+
href: use-notebook-features-and-commands.md
694696
- name : Server-side programming
695697
items:
696698
- name: Write stored procedures, triggers, & UDFs

‎articles/cosmos-db/cosmosdb-jupyter-notebooks.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ ms.author: rimman
1212

1313
Jupyter notebook is an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. Azure Cosmos DB supports built-in Jupyter notebooks for all APIs such as Cassandra, MongoDB, SQL, Gremlin, and Table. The built-in notebook support for all Azure Cosmos DB APIs and data models allows you to interactively run queries. The Jupyter notebooks run within the Azure Cosmos accounts and they enable developers to perform data exploration, data cleaning, data transformations, numerical simulations, statistical modeling, data visualization, and machine learning.
1414

15+
![Jupyter notebooks visualizations in Azure Cosmos DB](./media/cosmosdb-jupyter-notebooks/cosmos-notebooks-overview.png)
16+
1517
The Jupyter notebooks supports magic functions that extend the capabilities of the kernel by supporting additional commands. Cosmos magic is a command that extends the capabilities of the Python kernel in Jupyter notebook so you can run Azure Cosmos SQL API queries in addition to Apache Spark. You can easily combine Python and SQL API queries to query and visualize data by using rich visualization libraries integrated with render commands.
1618
Azure portal natively integrates Jupyter notebook experience into Azure Cosmos accounts as shown in the following image:
1719

@@ -51,9 +53,8 @@ Jupyter notebooks can include several types of components, each organized into d
5153

5254
To get started with built-in Jupyter notebooks in Azure Cosmos DB see the following articles:
5355

54-
* [How to create a notebook]()
55-
* [How to install dependencies in a notebook]()
56-
* [How to use a notebook and Cosmos magic extension to analyze data]()
56+
* [Enable notebooks in an Azure Cosmos account](enable-notebooks.md)
57+
* [Use notebook features and commands](use-notebook-features-and-commands.md)
5758

5859

5960

‎articles/cosmos-db/media/cosmosdb-jupyter-notebooks/cosmos-notebooks-overview.png

2.73 MB
Loading

‎articles/cosmos-db/use-notebook-features-and-commands.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Use built-in notebook commands and features in Azure Cosmos DB
3+
description: Learn how to use built-in commands and features to do common operations using Azure Cosmos DB's built-in notebooks.
4+
author: deborahc
5+
ms.service: cosmos-db
6+
ms.topic: conceptual
7+
ms.date: 09/23/2019
8+
ms.author: dech
9+
10+
---
11+
12+
# Use built-in notebook commands and features in Azure Cosmos DB
13+
14+
Built-in Jupyter notebooks in Azure Cosmos DB enable you to analyze and visualize your data from the Azure portal. This article describes how to use built-in notebook commands and features to do common operations.
15+
16+
## Install a new package
17+
After you enable notebook support for your Azure Cosmos accounts, you can open a new notebook and install a package.
18+
19+
In a new code cell, insert and run the following code, replacing ``PackageToBeInstalled`` with the desired Python package.
20+
```python
21+
import sys
22+
!{sys.executable} -m pip install PackageToBeInstalled –user
23+
```
24+
This package will be available to use from any notebook in the Azure Cosmos account.
25+
26+
## Run a SQL query
27+
28+
You can use the ``%%sql`` magic command to run a [SQL query](sql-query-getting-started.md) against any container in your account. Use the syntax:
29+
30+
```bash
31+
%%sql --database {database_id} --container {container_id}
32+
{Query text}
33+
```
34+
35+
- Replace ``{database_id}`` and ``{container_id}`` with the name of the database and container in your Cosmos account. If the ``--database`` and ``--container`` arguments are not provided, the query will be executed on the [default database and container](#set-default-database-for-queries).
36+
- You can run any SQL query that is valid in Azure Cosmos DB.
37+
The query text must be on a new line.
38+
39+
For example:
40+
```bash
41+
%%sql --database RetailDemo --container WebsiteData
42+
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c
43+
```
44+
Run ```%%sql?``` in a cell to see the help documentation for the sql magic command in the notebook.
45+
46+
## Run a SQL query and output to a Pandas DataFrame
47+
48+
You can output the results of a ``%%sql`` query into a [Pandas DataFrame](https://pandas.pydata.org/pandas-docs/stable/getting_started/dsintro.html#dataframe). Use the syntax:
49+
50+
```bash
51+
%%sql --database {database_id} --container {container_id} --output {outputDataFrameVar}
52+
{Query text}
53+
```
54+
- Replace ``{database_id}`` and ``{container_id}`` with the name of the database and container in your Cosmos account. If the ``--database`` and ``--container`` arguments are not provided, the query will be executed on the [default database and container](#set-default-database-for-queries).
55+
- Replace ``{outputDataFrameVar}`` with the name of the DataFrame variable that will contain the results.
56+
- You can run any SQL query that is valid in Azure Cosmos DB.
57+
The query text must be on a new line.
58+
59+
For example:
60+
61+
```bash
62+
%%sql --database RetailDemo --container WebsiteData --output df_cosmos
63+
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c
64+
```
65+
```bash
66+
df_cosmos.head(10)
67+
68+
Action ItemRevenue Country Item
69+
0 Viewed 9.00 Tunisia Black Tee
70+
1 Viewed 19.99 Antigua and Barbuda Flannel Shirt
71+
2 Added 3.75 Guinea-Bissau Socks
72+
3 Viewed 3.75 Guinea-Bissau Socks
73+
4 Viewed 55.00 Czech Republic Rainjacket
74+
5 Viewed 350.00 Iceland Cosmos T-shirt
75+
6 Added 19.99 Syrian Arab Republic Button-Up Shirt
76+
7 Viewed 19.99 Syrian Arab Republic Button-Up Shirt
77+
8 Viewed 33.00 Tuvalu Red Top
78+
9 Viewed 14.00 Cape Verde Flip Flop Shoes
79+
```
80+
81+
## Set default database for queries
82+
You can set the default database ```%%sql``` commands will use for the notebook. Replace ```{database_id}``` with the name of your database.
83+
84+
```bash
85+
%database {database_id}
86+
```
87+
Run ```%database?``` in a cell to see documentation in the notebook.
88+
89+
## Set default container for queries
90+
You can set the default container ```%%sql``` commands will use for the notebook. Replace ```{container_id}``` with the name of your container.
91+
92+
```bash
93+
%container {container_id}
94+
```
95+
Run ```%container?``` in a cell to see documentation in the notebook.
96+
97+
## Use the built-in Python SDK
98+
Version 4 of the [Azure Cosmos DB Python SDK for SQL API](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos) is installed and included in the notebook environment for the Cosmos account.
99+
100+
Use the built-in ``cosmos_client`` instance to run any SDK operation.
101+
102+
For example:
103+
104+
```python
105+
## Import modules as needed
106+
from azure.cosmos.partition_key import PartitionKey
107+
108+
## Create a new database if it doesn't exist
109+
database = cosmos_client.create_database_if_not_exists('RetailDemo')
110+
111+
## Create a new container if it doesn't exist
112+
container = database.create_container_if_not_exists(id='WebsiteData', partition_key=PartitionKey(path='/CartID'))
113+
```
114+
See [Python SDK samples](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos/samples).
115+
116+
> [!IMPORTANT]
117+
> The built-in Python SDK is only supported for SQL (Core) API accounts. For other APIs, you will need to [install the relevant Python driver](#install-a-new-package) that corresponds to the API.
118+
119+
## Create a custom instance of ``cosmos_client``
120+
For more flexibility, you can create a custom instance of ``cosmos_client`` in order to:
121+
122+
- Customize the [connection policy](https://docs.microsoft.com/python/api/azure-cosmos/azure.cosmos.documents.connectionpolicy?view=azure-python-preview)
123+
- Run operations against a different Cosmos account than the one you are in
124+
125+
You can access the connection string and primary key of the current account via the [environment variables](#access-the-account-endpoint-and-primary-key-env-variables).
126+
127+
```python
128+
import os
129+
import azure.cosmos.cosmos_client as cosmos
130+
import azure.cosmos.documents as documents
131+
132+
# These should be set to a region you've added for Cosmos DB
133+
region_1 = "Central US"
134+
region_2 = "East US 2"
135+
136+
custom_connection_policy = documents.ConnectionPolicy()
137+
custom_connection_policy.PreferredLocations = [region_1, region_2] # Set the order of regions the SDK will route requests to. The regions should be regions you've added for Cosmos, otherwise this will error.
138+
139+
# Create a new instance of CosmosClient, getting the endpoint and key from the environment variables
140+
custom_client = cosmos.CosmosClient(os.environ["COSMOS_ENDPOINT"], {'masterKey': os.environ["COSMOS_KEY"]}, connection_policy=custom_connection_policy)
141+
```
142+
## Access the account endpoint and primary key env variables
143+
```python
144+
import os
145+
146+
endpoint = os.environ["COSMOS_ENDPOINT"]
147+
primary_key = os.environ["COSMOS_KEY"]
148+
```
149+
> [!IMPORTANT]
150+
> The ``COSMOS_ENDPOINT`` and ``COSMOS_KEY`` environment variables are only applicable for SQL API. For other APIs, find the endpoint and key in the **Connection Strings** or **Keys** blade in your Cosmos account.
151+
152+
## Next steps
153+
154+
- Learn about the benefits of [Azure Cosmos DB Jupyter notebooks](cosmosdb-jupyter-notebooks.md)
155+
- Learn about the [Azure Cosmos DB Python SDK for SQL API](https://github.com/Azure/azure-sdk-for-python/tree/master/sdk/cosmos/azure-cosmos)

0 commit comments

Comments
 (0)