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 データ エクスプローラーに格納されているデータに接続してクエリを実行する方法について説明します。
前提条件
- Microsoft アカウントまたは Microsoft Entra ユーザー ID。 Azure サブスクリプションは不要です。
- ローカル コンピューターにインストールされている Jupyter Notebook。 それ以外の場合は、 Azure Data Studio を使用します。
- Python 3.6. Jupyter Notebook カーネルのバージョンを Python 3.6 に変更するには、 Kernel>Change Kernel>Python 3.6 を選択します。
kqlmagic をインストールする
kqlmagic 拡張機能をインストールして読み込むと、ノートブックに KQL クエリを記述できます。 カーネルが停止した場合、または結果が期待どおりでない場合は、kqlmagic 拡張機能を再読み込みします。
kqlmagic をインストールするには、次のコマンドを実行します。
!pip install Kqlmagic --no-cache-dir --upgradekqlmagic 拡張機能を読み込むには、次のコマンドを実行します。
%reload_ext Kqlmagic
クラスターへの接続
クラスターに接続する任意の方法のタブを選択します。
Note
可能な場合は、証明書の認証方法を使用することをお勧めします。
Microsoft Entra 証明書は、ノートブックからアクセスできるファイルに格納する必要があります。 このファイルは、接続文字列で参照できます。
%kql AzureDataExplorer://tenant='<tenant-id>';certificate='<certificate>';certificate_thumbprint='<thumbprint>';cluster='<cluster-name>';database='<database-name>'
ヒント
- 接続文字列をパラメーター化するには、引用符で囲まれていない値を使用して Python 式として解釈します。
- 資格情報の取得プロセスを簡略化するには、「 Connection オプションを参照してください。
クラスター接続の例
次のコマンドでは、Microsoft Entra コード メソッドを使用して、help クラスターでホストされているSamples データベースに対して認証を行います。 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_id/object_id/mis_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
| take 10
| render piechart title="My Pie Chart by State"
クエリを実行して時間グラフをレンダリングする
%%kql
StormEvents
| summarize count() by bin(StartTime,7d)
| render timechart
Note
これらのグラフは対話形式です。 特定の時間を拡大するには、時間範囲を選択します。
グラフの色をカスタマイズする
既定のカラー パレットが好みでない場合は、パレット オプションを使用してグラフをカスタマイズします。 使用可能なパレットは次のとおりです。 kqlmagic クエリ グラフの結果の色パレットを選択します。
パレットの一覧の場合:
%kql --palettes -popup_windowcoolカラー パレットを選択し、もう一度クエリをレンダリングします。%%kql -palette_name "cool" StormEvents | summarize statecount=count() by State | sort by statecount | take 10 | 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 を使用してデータをフィルター処理しています。
クエリを実行し、
DamagePropertyが最大の上位 10 個の状態を表示します。%%kql StormEvents | summarize max(DamageProperty) by State | order by max_DamageProperty desc | take 10クエリを実行して、上位の状態を抽出し、Python 変数に設定します。
df = _kql_raw_result_.to_dataframe() statefilter =df.loc[0].State statefilterletステートメントと Python 変数を使用してクエリを実行します。%%kql let _state = statefilter; StormEvents | where State in (_state) | summarize statecount=count() by bin(StartTime,1d), State | render timechart title = "Trend"help コマンドを実行します。
%kql --help "help"
ヒント
使用可能なすべての構成についての情報を受け取るには、%config Kqlmagic を使用します。 接続の問題や不適切なクエリなどの Kusto エラーのトラブルシューティングとキャプチャを行うには、%config Kqlmagic.short_errors=Falseを使用します
サンプル ノートブック
- Azure Data Explorer に対して Kqlmagic を使用する
- Application Insights に対して Kqlmagic を使用する
- Azure Monitor のログに対して Kqlmagic を使用する
- Python で Kqlmagic のクエリをパラメーター化する
- Kqlmagic クエリ グラフ結果のカラー パレットを選択する
関連するコンテンツ
- learn Kusto 照会言語 (KQL)