Jupyter Notebook と Kqlmagic 拡張機能を使用して、Azure Data Explorer 内のデータを分析します。Use a Jupyter Notebook and Kqlmagic extension to analyze data in Azure Data Explorer

Jupyter Notebook はオープン ソースの Web アプリケーションであり、ライブ コード、数式、視覚化、説明テキストを含むドキュメントを作成して共有するために使用できます。Jupyter Notebook is an open-source web application that allows you to create and share documents containing live code, equations, visualizations, and narrative text. 用途には、データのクリーニングと変換、数値シミュレーション、統計モデリング、データの視覚化、機械学習などが含まれています。Usage includes data cleaning and transformation, numerical simulation, statistical modeling, data visualization, and machine learning. Jupyter Notebook では、追加コマンドをサポートすることによってカーネルの機能を拡張するマジック関数がサポートされています。Jupyter Notebook supports magic functions that extend the capabilities of the kernel by supporting additional commands. KQL magic は、Kusto 言語のクエリをネイティブに実行できるように、Jupyter Notebook で Python カーネルの機能を拡張するコマンドです。KQL magic is a command that extends the capabilities of the Python kernel in Jupyter Notebook so you can run Kusto language queries natively. Python と Kusto クエリ言語を簡単に組み合わせて、render コマンドに統合されたリッチな Plot.ly ライブラリを使用してデータのクエリと視覚化を実行できます。You can easily combine Python and Kusto query language to query and visualize data using rich Plot.ly library integrated with render commands. クエリを実行するためのデータ ソースがサポートされています。Data sources for running queries are supported. このようなデータ ソースとしては、ログとテレメトリ データのための高速でスケーラブルなデータ探索サービスである Azure Data Explorer や、Azure Monitor ログ、Application Insights などがあります。These data sources include Azure Data Explorer, a fast and highly scalable data exploration service for log and telemetry data, as well as Azure Monitor logs and Application Insights. KQL magic は、Azure Notebooks、Jupyter Lab、および Visual Studio Code Jupyter 拡張機能でも動作します。KQL magic also works with Azure Notebooks, Jupyter Lab, and Visual Studio Code Jupyter extension.

前提条件Prerequisites

  • Azure Active Directory (AAD) のメンバーである、組織の電子メール アカウント。Organizational email account that is a member of Azure Active Directory (AAD).
  • ローカル コンピューターにインストールされた Jupyter Notebook、または Azure Notebook を使用してサンプルの Azure ノートブックを複製しますJupyter Notebook installed on your local machine or use Azure Notebooks and clone the sample Azure Notebook

KQL magic ライブラリのインストールInstall KQL magic library

  1. KQL magic をインストールします。Install KQL magic:

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

    注意

    Azure Notebooks を使用するときは、この手順は必要ありません。When using Azure Notebooks, this step is not required.

  2. KQL magic を読み込みます。Load KQL magic:

    %reload_ext Kqlmagic
    

    注意

    [カーネル] > [カーネルの変更] > [Python 3.6] の順にクリックして、カーネルのバージョンを Python 3.6 に変更しますChange the Kernel version to Python 3.6 by clicking on Kernel > Change Kernel > Python 3.6

Azure Data Explorer のヘルプ クラスターに接続するConnect to the Azure Data Explorer Help cluster

次のコマンドを使用して、Help クラスターでホストされている Samples データベースに接続します。Use the following command to connect to the Samples database hosted on the Help cluster. Microsoft 以外の AAD ユーザーの場合は、テナント名 Microsoft.com をお使いの AAD テナントに置き換えてください。For non-Microsoft AAD users, replace the tenant name Microsoft.com with your AAD Tenant.

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

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

render 演算子を使用してデータのクエリを実行し、ploy.ly ライブラリを使用してデータを視覚化します。Query data using the render operator and visualize data using the ploy.ly library. このクエリと視覚化では、ネイティブの KQL を使用する統合されたエクスペリエンスが提供されます。This query and visualization supplies an integrated experience that uses native KQL. Kqlmagic では、timepivotpivotchartladderchart を除くほとんどのグラフがサポートされています。Kqlmagic supports most charts except timepivot, pivotchart, and ladderchart. レンダリングは、kindysplitaccumulate を除くすべての属性でサポートされています。Render is supported with all attributes except kind, ysplit, and accumulate.

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

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

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

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

注意

これらのグラフは対話形式です。These charts are interactive. 特定の時間を拡大するには、時間範囲を選択します。Select a time range to zoom into a specific time.

グラフの色をカスタマイズするCustomize the chart colors

既定のカラー パレットが好みでない場合は、パレット オプションを使用してグラフをカスタマイズします。If you don’t like the default color palette, customize the charts using palette options. 使用できるパレットは次の場所にあります。KQL magic クエリ グラフ結果のカラー パレットを選択するThe available palettes can be found here: Choose colors palette for your KQL magic query chart result

  1. パレットの一覧の場合:For a list of palettes:

    %kql --palettes -popup_window
    
  2. cool カラー パレットを選択し、もう一度クエリをレンダリングします。Select the cool color palette and render the query again:

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

Python でクエリをパラメーター化するParameterize a query with Python

KQL magic により、Kusto クエリ言語と Python の間での簡単なインターチェンジが可能になります。KQL magic allows for simple interchange between Kusto query language and Python. 詳細については、以下を参照してください。Python を使って KQL magic のクエリをパラメーター化するTo learn more: Parameterize your KQL magic query with Python

KQL のクエリで Python 変数を使用するUse a Python variable in your KQL query

Python 変数の値をクエリで使用して、データをフィルター処理できます。You can use the value of a Python variable in your query to filter the data:

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 データフレームに変換するConvert query results to Pandas DataFrame

Pandas データフレームで KQL クエリの結果にアクセスできます。You can access the results of a KQL query in Pandas DataFrame. 次のように、変数 _kql_raw_result_ で最後に実行されたクエリ結果にでアクセスし、Pandas データフレームに結果を簡単に変換できます。Access the last executed query results by variable _kql_raw_result_ and easily convert the results into Pandas DataFrame as follows:

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

Example

多くの分析シナリオでは、多数のクエリを含む再利用可能なノートブックを作成し、あるクエリから後続のクエリに結果をフィードすることが必要な場合があります。In many analytics scenarios, you may want to create reusable notebooks that contain many queries and feed the results from one query into subsequent queries. 次の例では、Python 変数 statefilter を使用してデータをフィルター処理しています。The example below uses the Python variable statefilter to filter the data.

  1. クエリを実行し、DamageProperty が最大の上位 10 個の状態を表示します。Run a query to view the top 10 states with maximum DamageProperty:

    %%kql
    StormEvents
    | summarize max(DamageProperty) by State
    | order by max_DamageProperty desc
    | limit 10
    
  2. クエリを実行して、上位の状態を抽出し、Python 変数に設定します。Run a query to extract the top state and set it into a Python variable:

    df = _kql_raw_result_.to_dataframe()
    statefilter =df.loc[0].State
    statefilter
    
  3. let ステートメントと Python 変数を使用してクエリを実行します。Run a query using the let statement and the Python variable:

    %%kql
    let _state = statefilter;
    StormEvents 
    | where State in (_state)
    | summarize statecount=count() by bin(StartTime,1d), State
    | render timechart title = "Trend"
    
  4. help コマンドを実行します。Run the help command:

    %kql --help "help"
    

ヒント

使用可能なすべての構成についての情報を受け取るには、%config Kqlmagic を使用します。To receive information about all available configurations use %config Kqlmagic. 接続の問題や不適切なクエリなどの Kusto エラーのトラブルシューティングとキャプチャを行うには、%config Kqlmagic.short_errors=Falseを使用しますTo troubleshoot and capture Kusto errors, such as connection issues and incorrect queries, use %config Kqlmagic.short_errors=False

次のステップNext steps

help コマンドを実行して、サポートされるすべての機能が含まれている次のサンプル ノートブックを調べます。Run the help command to explore the following sample notebooks that contain all the supported features: