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 エクスプローラー、Azure Monitor ログ、アプリケーション インサイトが含まれます。
この記事では、Jupyter Notebook で kqlmagic を使用して、Azure Data エクスプローラー に格納されているデータに接続してクエリを実行する方法について説明します。
前提条件
- 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 拡張機能を再読み込みします。
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 式として解釈します。
- 資格情報を取得するプロセスを簡略化するには、「接続オプション」を参照してください。
クラスター接続の例
次のコマンドでは、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 パラメーターを持つディクショナリが必要です。 resourceclient_id/object_id/mis_res_idcloud_environmenttimeout |
-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
Note
これらのグラフは対話形式です。 特定の時間を拡大するには、時間範囲を選択します。
グラフの色をカスタマイズする
既定のカラー パレットが好みでない場合は、パレット オプションを使用してグラフをカスタマイズします。 使用可能なパレットは次の場所にあります。 kqlmagic クエリ グラフの結果に対してカラー パレットを選択します
パレットの一覧の場合:
%kql --palettes -popup_windowcoolカラー パレットを選択し、もう一度クエリをレンダリングします。%%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 を使用してデータをフィルター処理しています。
クエリを実行し、
DamagePropertyが最大の上位 10 個の状態を表示します。%%kql StormEvents | summarize max(DamageProperty) by State | order by max_DamageProperty desc | take10クエリを実行して、上位の状態を抽出し、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)