Azure Cosmos DB の組み込みノートブックのコマンドと機能を使用する (プレビュー)Use built-in notebook commands and features in Azure Cosmos DB (preview)

Azure Cosmos DB の組み込みの Jupyter ノートブックを使用すると、Azure portal のデータを分析して視覚化することができます。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.

新しいパッケージをインストールするInstall a new package

Azure Cosmos アカウントのノートブック サポートを有効にしたら、新しいノートブックを開き、パッケージをインストールできます。After you enable notebook support for your Azure Cosmos accounts, you can open a new notebook and install a package.

新しいコード セルに次のコードを挿入して実行します。このとき、PackageToBeInstalled を任意の Python パッケージに変更します。In a new code cell, insert and run the following code, replacing PackageToBeInstalled with the desired Python package.

import sys
!{sys.executable} -m pip install PackageToBeInstalled –user

このパッケージは、Azure Cosmos アカウントワークスペースの任意のノートブックから使用できます。This package will be available to use from any notebook in the Azure Cosmos account workspace.

ヒント

お使いのノートブックにカスタム パッケージが必要な場合、ワークスペースをリセットするとパッケージが削除されるため、ノートブックにセルを追加してパッケージをインストールすることをお勧めします。If your notebook requires a custom package, we recommend that you add a cell in your notebook to install the package, as packages are removed if you reset the workspace.

SQL クエリを実行するRun a SQL query

マジック コマンドの %%sql を使用し、お使いのアカウントにあるあらゆるコンテナーに対して SQL クエリを実行できます。You can use the %%sql magic command to run a SQL query against any container in your account. 次の構文を使用します。Use the syntax:

%%sql --database {database_id} --container {container_id}
{Query text}
  • {database_id}{container_id} をお使いの Cosmos アカウントにあるデータベースとコンテナーの名前に変更します。Replace {database_id} and {container_id} with the name of the database and container in your Cosmos account. 引数の --database--container が指定されない場合、既定のデータベースとコンテナーでクエリが実行されます。If the --database and --container arguments are not provided, the query will be executed on the default database and container.
  • Azure Cosmos DB で有効なあらゆる SQL クエリを実行できます。You can run any SQL query that is valid in Azure Cosmos DB. クエリ テキストは新しい行に配置する必要があります。The query text must be on a new line.

次に例を示します。For example:

%%sql --database RetailDemo --container WebsiteData
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c

セルで %%sql? を実行すると、ノートブックに SQL マジック コマンドのヘルプ ドキュメントが表示されます。Run %%sql? in a cell to see the help documentation for the sql magic command in the notebook.

SQL クエリを実行し、Pandas DataFrame に出力するRun a SQL query and output to a Pandas DataFrame

%%sqlPandas DataFrame クエリの結果を出力できます。You can output the results of a %%sql query into a Pandas DataFrame. 次の構文を使用します。Use the syntax:

%%sql --database {database_id} --container {container_id} --output {outputDataFrameVar}
{Query text}
  • {database_id}{container_id} をお使いの Cosmos アカウントにあるデータベースとコンテナーの名前に変更します。Replace {database_id} and {container_id} with the name of the database and container in your Cosmos account. 引数の --database--container が指定されない場合、既定のデータベースとコンテナーでクエリが実行されます。If the --database and --container arguments are not provided, the query will be executed on the default database and container.
  • 結果が含まれる DataFrame 変数の名前に {outputDataFrameVar} を変更します。Replace {outputDataFrameVar} with the name of the DataFrame variable that will contain the results.
  • Azure Cosmos DB で有効なあらゆる SQL クエリを実行できます。You can run any SQL query that is valid in Azure Cosmos DB. クエリ テキストは新しい行に配置する必要があります。The query text must be on a new line.

次に例を示します。For example:

%%sql --database RetailDemo --container WebsiteData --output df_cosmos
SELECT c.Action, c.Price as ItemRevenue, c.Country, c.Item FROM c
df_cosmos.head(10)

    Action  ItemRevenue Country Item
0   Viewed  9.00    Tunisia Black Tee
1   Viewed  19.99   Antigua and Barbuda Flannel Shirt
2   Added   3.75    Guinea-Bissau   Socks
3   Viewed  3.75    Guinea-Bissau   Socks
4   Viewed  55.00   Czech Republic  Rainjacket
5   Viewed  350.00  Iceland Cosmos T-shirt
6   Added   19.99   Syrian Arab Republic    Button-Up Shirt
7   Viewed  19.99   Syrian Arab Republic    Button-Up Shirt
8   Viewed  33.00   Tuvalu  Red Top
9   Viewed  14.00   Cape Verde  Flip Flop Shoes

JSON 項目をコンテナーにアップロードするUpload JSON items to a container

%%upload マジックコマンドを使用して、JSON ファイルから指定された Azure Cosmos コンテナーにデータをアップロードできます。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:

%%upload --databaseName {database_id} --containerName {container_id} --url {url_location_of_file}
  • {database_id}{container_id} をお使いの Azure Cosmos アカウントにあるデータベースとコンテナーの名前に変更します。Replace {database_id} and {container_id} with the name of the database and container in your Azure Cosmos account. 引数の --database--container が指定されない場合、既定のデータベースとコンテナーでクエリが実行されます。If the --database and --container arguments are not provided, the query will be executed on the default database and container.
  • {url_location_of_file} を JSON ファイルの場所に置き換えます。Replace {url_location_of_file} with the location of your JSON file. ファイルは有効な JSON オブジェクトの配列である必要があり、パブリック インターネット経由でアクセスできる必要があります。The file must be an array of valid JSON objects and it should be accessible over the public Internet.

次に例を示します。For example:

%%upload --database databaseName --container containerName --url 
https://contoso.com/path/to/data.json
Documents successfully uploaded to ContainerName
Total number of documents imported : 2654
Total time taken : 00:00:38.1228087 hours
Total RUs consumed : 25022.58

出力統計を使用すると、項目のアップロードに使用される有効な RU/秒を計算できます。With the output statistics, you can calculate the effective RU/s used to upload the items. たとえば、25000 の RU が 38 秒で使用された場合、有効な RU/秒は 25000ru/38 秒 = 658 RU/秒になります。For example, if 25,000 RUs were consumed over 38 seconds, the effective RU/s is 25,000 RUs / 38 seconds = 658 RU/s.

クエリの既定のデータベースを設定するSet default database for queries

ノートブックに既定のデータベース %%sql コマンドが使用されるように設定できます。You can set the default database %%sql commands will use for the notebook. {database_id} をお使いのデータベースの名前に変更します。Replace {database_id} with the name of your database.

%database {database_id}

セルで %database? を実行すると、ノートブックにドキュメントが表示されます。Run %database? in a cell to see documentation in the notebook.

クエリの既定のコンテナーを設定するSet default container for queries

ノートブックに既定のコンテナー %%sql コマンドが使用されるように設定できます。You can set the default container %%sql commands will use for the notebook. {container_id} をお使いのコンテナーの名前に変更します。Replace {container_id} with the name of your container.

%container {container_id}

セルで %container? を実行すると、ノートブックにドキュメントが表示されます。Run %container? in a cell to see documentation in the notebook.

組み込みの nteract データ エクスプローラーを使用するUse built-in nteract data explorer

組み込みの nteract データ エクスプローラーを使用すると、データフレームをフィルター処理したり視覚化したりできます。You can use the built-in nteract data explorer to filter and visualize a DataFrame. この機能を有効にするには、オプション pd.options.display.html.table_schemaTrue に設定し、pd.options.display.max_rows を目的の値に設定します (すべての結果を表示するには、pd.options.display.max_rowsNone に設定します)。To enable this feature, set the option pd.options.display.html.table_schema to True and pd.options.display.max_rows to the desired value (you can set pd.options.display.max_rows to None to show all results).

import pandas as pd
pd.options.display.html.table_schema = True
pd.options.display.max_rows = None

df_cosmos.groupby("Item").size()

nteract データ エクスプローラー

組み込みの Python SDK を使用するUse the built-in Python SDK

Azure Cosmos DB Python SDK for SQL API のバージョン 4 がインストールされ、Azure Cosmos アカウントのノートブック環境に含まれます。Version 4 of the Azure Cosmos DB Python SDK for SQL API is installed and included in the notebook environment for the Azure Cosmos account.

組み込みの cosmos_client インスタンスを使用し、あらゆる SDK 操作を実行します。Use the built-in cosmos_client instance to run any SDK operation.

次に例を示します。For example:

## Import modules as needed
from azure.cosmos.partition_key import PartitionKey

## Create a new database if it doesn't exist
database = cosmos_client.create_database_if_not_exists('RetailDemo')

## Create a new container if it doesn't exist
container = database.create_container_if_not_exists(id='WebsiteData', partition_key=PartitionKey(path='/CartID'))

Python SDK のサンプル」を参照してください。See Python SDK samples.

重要

組み込みの Python SDK は、SQL (Core) API アカウントでのみサポートされています。The built-in Python SDK is only supported for SQL (Core) API accounts. その他の API については、API に対応する関連 Python ドライバーをインストールする必要があります。For other APIs, you will need to install the relevant Python driver that corresponds to the API.

cosmos_client のカスタム インスタンスを作成するCreate a custom instance of cosmos_client

自由度を上げるために、次の目的で cosmos_client のカスタム インスタンスを作成できます。For more flexibility, you can create a custom instance of cosmos_client in order to:

  • 接続ポリシーをカスタマイズするCustomize the connection policy
  • 現在のアカウントとは異なる Azure Cosmos アカウントに対して操作を実行するRun operations against a different Azure Cosmos account than the one you are in

環境変数を介して現在のアカウントの接続文字列と主キーにアクセスできます。You can access the connection string and primary key of the current account via the environment variables.

import os
import azure.cosmos.cosmos_client as cosmos
import azure.cosmos.documents as documents

# These should be set to a region you've added for Azure Cosmos DB
region_1 = "Central US" 
region_2 = "East US 2"

custom_connection_policy = documents.ConnectionPolicy()
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.

# Create a new instance of CosmosClient, getting the endpoint and key from the environment variables
custom_client = cosmos.CosmosClient(url=os.environ["COSMOS_ENDPOINT"], credential=os.environ["COSMOS_KEY"], connection_policy=custom_connection_policy)

アカウント エンドポイントと主キーの環境変数にアクセスするAccess the account endpoint and primary key env variables

import os

endpoint = os.environ["COSMOS_ENDPOINT"]
primary_key = os.environ["COSMOS_KEY"]

重要

環境変数の COSMOS_ENDPOINTCOSMOS_KEY は SQL API にのみ適用できます。The COSMOS_ENDPOINT and COSMOS_KEY environment variables are only applicable for SQL API. その他の API については、お使いの Azure Cosmos アカウントの [接続文字列] または [キー] ブレードでエンドポイントとキーを見つけてください。For other APIs, find the endpoint and key in the Connection Strings or Keys blade in your Azure Cosmos account.

ノートブック ワークスペースをリセットするReset notebooks workspace

ノートブック ワークスペースをリセットし、既定の設定に戻すには、コマンド バーで [Reset Workspace](ワークスペースのリセット) を選択します。To reset the notebooks workspace to the default settings, select Reset Workspace on the command bar. これでインストールされているカスタム パッケージがすべて削除され、Jupyter サーバーが再起動されます。This will remove any custom installed packages and restart the Jupyter server. ノートブック、ファイル、Azure Cosmos リソースは影響を受けません。Your notebooks, files, and Azure Cosmos resources will not be affected.

ノートブック ワークスペースをリセットする

次のステップNext steps