Skip to content

Commit 1dcb97d

Browse files
deborahcdeborahc
committed
Removing extra chars
1 parent bf2809b commit 1dcb97d

File tree

1 file changed

+160
-0
lines changed

1 file changed

+160
-0
lines changed

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

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
---
2+
title: Use built-in notebook commands and features in Azure Cosmos DB C# notebooks (preview)
3+
description: Learn how to use built-in commands and features to do common operations using Azure Cosmos DB's built-in C# notebooks.
4+
author: deborahc
5+
ms.service: cosmos-db
6+
ms.topic: conceptual
7+
ms.date: 05/19/2020
8+
ms.author: dech
9+
10+
---
11+
12+
# Use built-in notebook commands and features in Azure Cosmos DB C# notebooks (preview)
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 in C# notebooks.
15+
16+
## Install a new NuGet 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 NuGet package, and ``optionalVersion`` with a specific version of the package if desired.
20+
21+
```csharp
22+
#r "nuget: PackageToBeInstalled, optionalVersion"
23+
```
24+
You can install multiple NuGet packages in the same cell. Packages will be available to use from any notebook in the Azure Cosmos account workspace.
25+
26+
Currently, the C# notebooks workspace does not support recursive resolution of NuGet packages. If a NuGet package has dependencies on other NuGet packages not currently installed, you may have to explicitly reference them along with the parent package.
27+
28+
> [!TIP]
29+
> If your notebook requires a custom package, we recommend that you add a cell to your notebook to install the package and make it the first cell. This reduces the chance of conflicts with any packages Azure Cosmos DB loads by default. It also makes it easy to re-install them if you [reset the workspace](#reset-notebooks-workspace), which removes all packages.
30+
## Use the built-in Azure Cosmos DB .NET SDK
31+
Version 3 of the [Azure Cosmos DB .NET SDK for SQL API](https://github.com/Azure/azure-cosmos-dotnet-v3) is installed and included in the notebook environment for the Azure Cosmos account.
32+
33+
Create an instance of ``CosmosClient`` to run any SDK operation.
34+
35+
For example:
36+
37+
```csharp
38+
// Include usings
39+
using System;
40+
using Microsoft.Azure.Cosmos; //namespace for Azure Cosmos DB .NET V3 SDK
41+
using System.Collections;
42+
43+
// Initialize a new instance of CosmosClient using the built-in account endpoint and key parameters
44+
CosmosClient cosmosClient = new CosmosClient(Cosmos.Endpoint, Cosmos.Key);
45+
46+
// Create a new database and container with 400 RU/s
47+
Database database = await cosmosClient.CreateDatabaseIfNotExistsAsync("DatabaseName");
48+
Container container = await database.CreateContainerIfNotExistsAsync("ContainerName", "/partitionKey", 400);
49+
```
50+
See [.NET SDK samples](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage).
51+
52+
> [!IMPORTANT]
53+
> The built-in Azure Cosmos DB .NET SDK is only supported for SQL (Core) API accounts. For other APIs, you will need to [install the relevant .NET driver](#install-a-new-nuget-package) that corresponds to the API.
54+
55+
## Set custom options using ```CosmosClientOptions```
56+
For more flexibility, you can set custom ``CosmosClientOptions`` to pass in your ``CosmosClient`` instance. You can use this to:
57+
58+
- Set an application name in the user-agent suffix to include in every request
59+
- Set the preferred region to be used to operations against the service
60+
- Set a custom retry policy on rate-limited requests
61+
62+
See the [documentation](/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions) for all ``CosmosClientOptions`` settings.
63+
64+
```csharp
65+
using Microsoft.Azure.Cosmos;
66+
67+
// Configure CosmosClientOptions
68+
var cosmosClientOptions = new CosmosClientOptions
69+
{
70+
ApplicationName = "ContosoNotebookAppName",
71+
ApplicationRegion = Regions.RegionName, // By default, this is the region you first created your account in
72+
MaxRetryAttemptsOnRateLimitedRequests = 9, // By default, this value is 9
73+
};
74+
75+
var client = new CosmosClient(Cosmos.Endpoint, Cosmos.Key, cosmosClientOptions);
76+
```
77+
78+
## Access the account endpoint and primary key variables
79+
You can access the built-in endpoint and key of the account your notebook is in.
80+
81+
```csharp
82+
var key = Cosmos.Key;
83+
var endpoint = Cosmos.Endpoint;
84+
```
85+
86+
> [!IMPORTANT]
87+
> The ``Cosmos.Key`` and ``Cosmos.Endpoint`` variables are only applicable for SQL API. For other APIs, find the endpoint and key in the **Connection Strings** or **Keys** blade in your Azure Cosmos account.
88+
89+
## Print console output in C# code
90+
In your C# code, you can use the Display.AsMarkdown() syntax with [string interpolation](/dotnet/csharp/language-reference/tokens/interpolated) to print console output that will appear when you run the cell.
91+
92+
For example:
93+
94+
```csharp
95+
// Print text in the output
96+
Display.AsMarkdown($"Hello world!");
97+
98+
// Print a variable in the output
99+
for (int i = 0; i < 5; i++) {
100+
Display.AsMarkdown($"Printing out variable: {i}");
101+
}
102+
```
103+
> [!IMPORTANT]
104+
> Console.WriteLine() syntax is not currently supported in C# notebooks. Use Display.AsMarkdown to print console output from your program.
105+
106+
## Use built-in nteract data explorer
107+
You can use the built-in [nteract data explorer](https://blog.nteract.io/designing-the-nteract-data-explorer-f4476d53f897) to filter and visualize a collection of items. In a cell, put the variable you want to visualize in the last line, which will automatically be displayed in nteract when the cell is run.
108+
109+
For example, in the GetingStarted_Csharp.ipynb example, we can print out the variable with our result, the ``telemetryEvents``. See the [GettingStarted_Csharp.ipynb notebook](https://github.com/Azure-Samples/cosmos-notebooks/blob/master/CSharp_quickstarts/GettingStarted_CSharp.ipynb) for the entire sample.
110+
111+
![Csharp query cell](media/use-notebook-features-and-commands/csharp-query-cell.png)
112+
113+
![nteract data explorer](media/use-notebook-features-and-commands/csharp-nteract-built-in-chart.png)
114+
115+
## Use built-in dictionary viewer
116+
You can use the built-in dictionary viewer to view a variable. In a cell, put the variable you want to visualize in the last line, which will be automatically displayed when the cell is run.
117+
118+
![Built-in dictionary viewer](media/use-notebook-features-and-commands/csharp-built-in-dictionary-viewer.png)
119+
120+
## Upload JSON items to a container
121+
You can use the ``%%upload`` magic command to upload data from a JSON file to a specified Azure Cosmos container. Use the following command to upload the items:
122+
123+
```csharp
124+
%%upload --databaseName {database_id} --containerName {container_id} --url {url_location_of_file}
125+
```
126+
127+
- Replace ``{database_id}`` and ``{container_id}`` with the name of the database and container in your Azure Cosmos account.
128+
- Replace ``{url_location_of_file}`` with the location of your JSON file. The file must be an array of valid JSON objects and it should be accessible over the public Internet.
129+
130+
For example:
131+
132+
```csharp
133+
%%upload --database databaseName --container containerName --url
134+
https://contoso.com/path/to/data.json
135+
```
136+
```
137+
Documents successfully uploaded to ContainerName
138+
Total number of documents imported : 2654
139+
Total time taken : 00:00:38.1228087 hours
140+
Total RUs consumed : 25022.58
141+
```
142+
With the output statistics, you can calculate the effective RU/s used to upload the items. For example, if 25,000 RUs were consumed over 38 seconds, the effective RU/s is 25,000 RUs / 38 seconds = 658 RU/s.
143+
144+
## Run another notebook in current notebook
145+
You can use the ``%%run`` magic command to run another notebook in your workspace from your current notebook. Use the syntax:
146+
147+
```csharp
148+
%%run ./path/to/{notebookName}.ipynb
149+
```
150+
Replace ``{notebookName}`` with the name of the notebook you want to run. The notebook must be in your current 'My Notebooks' workspace.
151+
152+
## Reset notebooks workspace
153+
To reset the notebooks workspace to the default settings, select **Reset Workspace** on the command bar. This will remove any custom installed packages and restart the Jupyter server. Your notebooks, files, and Azure Cosmos resources will not be affected.
154+
155+
![Reset notebooks workspace](media/use-notebook-features-and-commands/reset-workspace.png)
156+
157+
## Next steps
158+
159+
- Learn about the benefits of [Azure Cosmos DB Jupyter notebooks](cosmosdb-jupyter-notebooks.md)
160+
- Learn about the [Azure Cosmos DB .NET SDK for SQL API](https://github.com/Azure/azure-cosmos-dotnet-v3)

0 commit comments

Comments
 (0)