Jupyter Notebook と Kqlmagic 拡張機能を使用して Azure Data Explorer 内のデータを分析する

  • [アーティクル]

Jupyter Notebookは、ライブ コード、数式、視覚化、説明テキストを含むドキュメントを作成して共有できるオープンソースの Web アプリケーションです。 これは、データのクリーニングと変換、数値シミュレーション、統計モデリング、データの視覚化、機械学習など、さまざまなタスクに役立ちます。

Kqlmagic は、Jupyter Notebook の Python カーネルの機能を拡張し、Kusto 照会言語 (KQL) クエリをネイティブに実行できるようにします。 Python と KQL を組み合わせて、レンダー オペレーターと統合された豊富な Plot.ly ライブラリを使用してデータのクエリと視覚化を行うことができます。 kqlmagic 拡張機能は、Jupyter Lab、Visual Studio Code Jupyter 拡張機能、Azure Data Studio と互換性があり、サポートされているデータ ソースには Azure Data Explorer、Azure Monitor ログ、Application Insights が含まれます。

この記事では、Jupyter Notebookで kqlmagic を使用して、Azure Data Explorerに格納されているデータに接続してクエリを実行する方法について説明します。

前提条件

  • Microsoft アカウントまたはMicrosoft Entraユーザー ID。 Azure サブスクリプションは不要です。
  • Jupyter Notebookローカル コンピューターにインストールされます。 それ以外の場合は、 Azure Data Studio を使用します。
  • Python 3.6。 Jupyter Notebook カーネル バージョンを Python 3.6 に変更するには、[カーネルの変更]> [カーネル >Python 3.6] を選択します。

kqlmagic をインストールする

kqlmagic 拡張機能をインストールして読み込むと、ノートブックに KQL クエリを記述できます。 カーネルが停止した場合、または結果が期待どおりでない場合は、kqlmagic 拡張機能を再読み込みします。

  1. kqlmagic をインストールするには、次のコマンドを実行します。

    !pip install Kqlmagic --no-cache-dir  --upgrade

  2. kqlmagic 拡張機能を読み込むには、次のコマンドを実行します。

    %reload_ext Kqlmagic

クラスターへの接続

クラスターに接続するために使用する方法のタブを選択します。

Microsoft Entra コード メソッドは、MSAL 対話型サインインを求めます。 認証用に入力するコードを受け取ります。

%kql AzureDataExplorer://code;cluster='<cluster-name>';database='<database-name>'

ヒント

  • 接続文字列をパラメーター化するには、Python 式として解釈される引用符で囲まれていない値を使用します。
  • 資格情報を取得するプロセスを簡略化するには、「 接続オプション」を参照してください。

クラスター接続の例

次のコマンドでは、Microsoft Entra コード メソッドを使用して、クラスターでホストされているデータベースに対するSamples認証を行helpいます。 Microsoft Entra以外のユーザーの場合は、テナント名Microsoft.comをMicrosoft Entraテナントに置き換えます。

%kql AzureDataExplorer://tenant="Microsoft.com";code;cluster='help';database='Samples'

接続オプション

資格情報を取得するプロセスを簡略化するために、接続文字列の後に次のいずれかのオプション フラグを追加できます。

オプション 説明 構文例
try_azcli_login Azure CLI から認証資格情報の取得を試みます。 -try_azcli_login
try_azcli_login_subscription 指定したサブスクリプションに基づいて、Azure CLI から認証資格情報を取得しようとします。 -try_azcli_login_subscription=<subscription_id>
try_vscode_login Visual Studio Code Azure アカウントのサインインから認証資格情報を取得しようとします。 -try_vscode_login
try_msi MSI ローカル エンドポイントから認証資格情報の取得を試みます。 省略可能な MSI パラメーター resource(、、/client_idobject_idmis_res_id/cloud_environment、timeout) を含むディクショナリが必要です。 -try_msi={"client_id":<id>}
try_token 指定したトークンを使用して認証します。 Azure AD v1 または v2 トークン のプロパティを持つディクショナリが必要です。 -try_token={"tokenType":"bearer","accessToken":"<token>"}

接続オプションの例

前の表で説明したオプションは、接続文字列の後に追加できます。 次の例では、Azure CLI サインイン オプションを使用します。

%kql azureDataExplorer://code;cluster='help';database='Samples' -try_azcli_login

接続情報を表示する

既存のすべての接続を表示するには、次のコマンドを実行します。

%kql --conn

特定の接続の詳細をチェックするには、次のコマンドを実行します。

%kql --conn <database-name>@<cluster-name>

クエリと視覚化を実行する

render 演算子を使用してデータのクエリを実行し、ploy.ly ライブラリを使用してデータを視覚化します。 このクエリと視覚化では、ネイティブの KQL を使用する統合されたエクスペリエンスが提供されます。 Kqlmagic では、timepivot、pivotchart、ladderchart を除くほとんどのグラフがサポートされています。 レンダリングは、kind、ysplit、accumulate を除くすべての属性でサポートされています。

クエリを実行して円グラフをレンダリングする

%%kql
StormEvents
| summarize statecount=count() by State
| sort by statecount 
| take10
| render piechart title="My Pie Chart by State"

クエリを実行して時間グラフをレンダリングする

%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart

注意

これらのグラフは対話形式です。 特定の時間を拡大するには、時間範囲を選択します。

グラフの色をカスタマイズする

既定のカラー パレットが好みでない場合は、パレット オプションを使用してグラフをカスタマイズします。 使用できるパレットは次の場所にあります。Kqlmagic クエリ グラフ結果のカラー パレットを選択する

  1. パレットの一覧の場合:

    %kql --palettes -popup_window

  2. cool カラー パレットを選択し、もう一度クエリをレンダリングします。

    %%kql -palette_name "cool"
StormEvents
| summarize statecount=count() by State
| sort by statecount
| take10
| render piechart title="My Pie Chart by State"

Python でクエリをパラメーター化する

Kqlmagic を使用すると、Kusto 照会言語と Python を簡単に交換できます。 詳細については、以下を参照してください。Python で Kqlmagic のクエリをパラメーター化する

KQL のクエリで Python 変数を使用する

Python 変数の値をクエリで使用して、データをフィルター処理できます。

statefilter = ["TEXAS", "KANSAS"]

%%kql
let _state = statefilter;
StormEvents 
| where State in (_state) 
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

クエリの結果を Pandas データフレームに変換する

Pandas データフレームで KQL クエリの結果にアクセスできます。 次のように、変数 _kql_raw_result_ で最後に実行されたクエリ結果にでアクセスし、Pandas データフレームに結果を簡単に変換できます。

df = _kql_raw_result_.to_dataframe()
df.head(10)

例

多くの分析シナリオでは、多数のクエリを含む再利用可能なノートブックを作成し、あるクエリから後続のクエリに結果をフィードすることが必要な場合があります。 次の例では、Python 変数 statefilter を使用してデータをフィルター処理しています。

  1. クエリを実行し、DamageProperty が最大の上位 10 個の状態を表示します。

    %%kql
StormEvents
| summarize max(DamageProperty) by State
| order by max_DamageProperty desc
| take10

  2. クエリを実行して、上位の状態を抽出し、Python 変数に設定します。

    df = _kql_raw_result_.to_dataframe()
statefilter =df.loc[0].State
statefilter

  3. let ステートメントと Python 変数を使用してクエリを実行します。

    %%kql
let _state = statefilter;
StormEvents 
| where State in (_state)
| summarize statecount=count() by bin(StartTime,1d), State
| render timechart title = "Trend"

  4. help コマンドを実行します。

    %kql --help "help"

ヒント

使用可能なすべての構成についての情報を受け取るには、%config Kqlmagic を使用します。 接続の問題や不適切なクエリなどの Kusto エラーのトラブルシューティングとキャプチャを行うには、%config Kqlmagic.short_errors=Falseを使用します

サンプル ノートブック

関連コンテンツ