カスタムダッシュボードでは、 template variablesを使用してグラフやその他のウィジェットを動的にフィルター処理できます。 テンプレート変数は、ダッシュボードをより便利にし、さまざまなユースケースで再利用できるダッシュボードをより簡単に作成するのに役立ちます。
テンプレート変数を使用する理由
テンプレート変数は、ダッシュボードの作成者が選択した特定のメタデータ値に基づいてダッシュボード全体をフィルタリングする強力で動的な方法です。テンプレート変数を使用する利点は次のとおりです。
- これにより、ダッシュボードが使いやすくなります。ユーザーはデータの構造を理解する必要がなく、設定したさまざまなフィルター オプションから簡単に選択できます。
- これらを使用すると、再利用可能なダッシュボード テンプレートを作成できます。これを複製して、他の多くの用途に合わせて調整できます。
いくつかのテンプレート変数を含むダッシュボードの例を次に示します。これは、ダッシュボードの上部に表示されます。
テンプレート変数を使用すると、さまざまな変数とフィルターを設定して、必要なダッシュボード エクスペリエンスを作成できます。作成できるエクスペリエンスの例:
- アプリ名を選択するドロップダウン
- 特定の地域を選択するドロップダウン
- 特定の期間またはその他の数値を選択するためのドロップダウン
- フリー テキスト フィールドを使用して一致する文字列を検索するフィルター
要件と制限
テンプレート変数は、カスタム ダッシュボードのウィジェットを作成するコンテキストでのみ使用できます。NRQLクエリで変数を使用するには、NRQL変数を参照してください。
テンプレート変数を含むクエリは、ダッシュボードのコンテキストでのみ使用できます。このため、一部のクエリ関連機能は動作しません。たとえば、 Export dashboard as PDF
オプションは、変数を持つウィジェットをサポートしていません。
クエリの追加に関する重要な注意事項:
クエリの作成に関する制限については、「クエリの作成」を参照してください。
テンプレート変数を使用する
テンプレート変数の作成方法を順を追って説明し、その後、さまざまな種類のテンプレート変数の 例を いくつか示します。
テンプレート変数の作成は、2 つのステップで構成されます。
まず、テンプレート変数を定義します。これは、ウィジェットを作成するために NRQL クエリで使用する変数です。
変数を定義するには:
変数のない新しいダッシュボードから編集をクリックしますボタンをクリックし、左上隅にある+ Add variableボタンをクリックします。 変数の追加が完了したら、 Done editingをクリックします。
ダッシュボードにウィジェットが含まれている場合は、 + Add variableボタンをクリックします。
Add variableワークフローを完了します。 以下に、各フィールドのルールとヒントをいくつか示します。
フィールド | 詳細 |
---|
クエリで使用する名前 | 変数の名前。これは、 {{...}} で囲まれたクエリで使用するものです。たとえば、ここで名前としてcountry を使用する場合、クエリを記述するときに{{country}} で変数を呼び出します。 変数名は文字で始める必要があり、文字、数字、アンダースコアを含めることができます。 |
表示名 | オプション。このように変数がダッシュボードの上に表示されるため、ダッシュボードのユーザーは変数が何を表しているかがわかります。これを空白のままにすると、メインの名前の値が使用されます。 |
タイプ | 次の 3 つのオプションがあります。 Query: ドロップダウン メニューで使用されるオプションの動的なリストを返すクエリを作成できます。 たとえば、次のクエリはcountry 値の動的なリストを返します。 SELECT uniques(countryCode) FROM PageAction since 2 days ago
クエリを作成する際の規則とヒントについては、「クエリ型変数」を参照してください。 List: ドロップダウン メニューのオプションを設定するために使用されるカンマ区切りの値のリスト。 たとえば、次のようなリストを使用して、 country 値のリストを手動で定義できます。 ES, US, CA. Text field: ドロップダウンから値を選択する代わりに、ダッシュボード ユーザーは入力したテキストをフィルタリングできます。
|
アカウント | query タイプにのみ存在します。複数のアカウントを持つ組織の場合、これは照会されるアカウントを設定します。
|
クエリ | uniques (attribute) を使用してここにクエリを記述します。
|
タイムピッカーを無視する | オプション。 クエリ タイプの場合にのみ存在します。 このオプションをオフにすると、ダッシュボードで選択したタイムピッカーの値を使用してクエリが実行されます。 そうすることで、タイムピッカーの値が変化すると、変数のドロップダウンの結果が新しく選択された時間範囲に動的に応答します。 |
複数選択 | オプション。このオプションを使用すると、ドロップダウンで単一の選択ではなく、同時に複数の選択を許可できます。 |
デフォルト値 | オプション。これらは、ダッシュボードがフィルター処理するデフォルト値です。たとえば、上記のcountry クエリを使用した場合、デフォルト値としてES を入力すると、ダッシュボードはその値に自動的にフィルターをかけます。すべての可能性を選択することもできます。 WHERE 句で複数の値を使用するには、 = の代わりにIN を使用する必要があります。
|
出力フォーマット | これにより、変数によって生成されたデータがクエリ内でどのように処理されるかを変更できます。 ここで選択したオプションは、後でウィジェットに追加するクエリに関連しています。 defaultオプションは、ほとんどのクエリで使用される一般的なオプションであるため、文字列になります。 defaultオプションを次のいずれかに変更できます。 |
country
値のテンプレート変数がどのようになるかを示す次の例を参照してください。
テンプレート変数を定義したら、作成したテンプレート変数を使用するウィジェットを追加できます。
テンプレート変数を構成したら、クエリで定義した変数を使用するウィジェットがダッシュボードに必要になります。
ウィジェットを作成するには:
ダッシュボードで、右上隅にある+ Add widgetボタンをクリックします。
2 つのオプションがあります。
Add a chartオプションを選択します。
クエリを追加して、 Runをクリックします。
ステップ 1 で説明した例に従います。
SELECT countryCode FROM PageAction WHERE countryCode IN ({{countryCode}})
これらは、テンプレート変数を値として受け入れる NRQL 句であることに注意してください: SELECT
、 FROM
、 FACET
、 ORDER BY
、およびWHERE
。
代わりに、次の NRQL 句のリストはテンプレート変数を引数として受け入れません: AS
、 COMPARE WITH
、 LIMIT
、 OFFSET
、 SINCE
、 SLIDE BY
、 TIMESERIES
、 UNTIL
およびWITH...
.
クリック Save
テンプレート変数の定義とその変数を参照するウィジェットの追加が完了したら、テンプレート変数バーからさまざまなオプションを選択し、選択に基づいてウィジェットが変化するかどうかを確認することで、期待どおりに機能していることを確認できます。
右側に結果ウィジェットの例を示します。左側にはcountry
ドロップダウンがあります。
クエリ型テンプレート変数の書き方のルール
テンプレート変数の定義に関するセクションで説明したように、変数の種類にはクエリ、リスト、テキスト フィールドの 3 つがあります。 クエリ タイプの変数は、ダッシュボードの上部にあるテンプレート変数バーのドロップダウンに値を入力するために使用される値のリストを返す実用的なクエリを作成する必要があるため、作成が最も複雑です。
重要
これは、テンプレート変数を利用するクエリの記述とは異なるトピックであることに注意してください。
値のリストを返す限り、ほぼすべての NRQL クエリを使用できます。 そのためには、 uniques
関数またはkeyset
関数のいずれかを使用できます。
uniques
の場合:
From PageAction select uniques(countryCode)
From PageAction select uniques(countryCode, 10000)
keyset
の場合:
From PageAction select keyset() SINCE 1 day ago
変数内に変数が存在することはできないため、ネストされた変数はサポートされていないことに注意してください。
いくつかの例
テンプレート変数の実装のいくつかの異なるタイプを次に示します。
タイプ NRQL/ENUM
の変数を作成するときに、表示オプション セクションから複数値オプションを有効にすることができます。
{{MultiValue}}
という名前の変数を作成し、一意のすべての eventId のリストを返すクエリの例を次に示します。
SELECT uniques(eventId) FROM AjaxRequest
次に、次のクエリでウィジェットを作成します。
SELECT count(*) FROM AjaxRequest WHERE eventId IN ({{MultiValue}})
一度に定義できるテンプレート変数は 1 つだけですが、1 つのウィジェットで複数のテンプレート変数を使用できます。
次に、2 つのテンプレート変数を使用するクエリの例を示します。これは、 countryCode
および city
テンプレート変数がすでに作成されており、それらの値が 1 つであることを前提としていることに注意してください。
SELECT countryCode, city FROM PageAction WHERE countryCode = {{countryCode}} and city = {{city}}
city
変数の Chicago
、 New York
、 Paris
など、変数に複数の値がある場合は、 IN
を使用する必要があります。
SELECT countryCode, city FROM PageAction WHERE countryCode IN ({{countryCode}}) and city IN ({{city}})
変数とregexを使用して、フィルターの一部が修正されていることが確実であれば、フィルターを作成できます。
like
を使用する場合は、この部分一致を使用する必要があります。
リリース バージョンでフィルター処理するとします。クエリはrelease-1234
のようなものを返します。
aparse
を使用して変数を作成し、バージョン番号を解析できます。
SELECT uniques(aparse(platformVersion , 'release-*')) FROM PageView
次に、次のクエリでウィジェットを作成します。
SELECT count(*) FROM PageAction WHERE aparse(platformVersion, 'release-*') IN ({{releaseversion}}) facet platformVersion
または、 capture
コマンドを使用することもできます。
SELECT count(*) FROM PageAction WHERE capture(platformVersion, r'release-(?P<platformVersion>\d+)') IN ({{releaseversion}}) Facet platformVersion
LIKE
と RLIKE
テンプレート変数として使用して、ダッシュボード内のデータをフィルタリングできます。この機能を使用するには、テンプレート変数の作成時に追加する値で、値の先頭と末尾に %
ワイルドカード記号を使用する必要があります。
ここに例を示します。次に示すように、文字列変数を定義します。
次に、ウィジェット グラフを作成し、次のように変数を使用できます。
FROM NrdbQuery SELECT user WHERE user LIKE {{like_filter}}
またはこのように:
FROM NrdbQuery SELECT user WHERE user RLIKE {{like_filter}}
文字列出力形式で NRQL 型の変数を作成し、それを facet
句の後に使用して、異なる値でグループ化できます。
たとえば、次のような {{userAgentName}}
という名前の変数を作成できます。
SELECT uniques(userAgentName) FROM PageAction
次に、次のクエリを使用してウィジェットを作成します。
SELECT count(*) FROM PageAction WHERE userAgentName={{userAgentName}} FACET userAgentName
identifier
出力形式で変数を作成し、それをFACET
句の後に使用して、さまざまな値でグループ化できます。
たとえば、 countryCode
とcity
の 2 つの可能な値を持つリスト型の{{location}}
変数を作成するとします。出力形式をidentifier
に設定します。
次に、次のクエリを使用してウィジェットを作成します。
SELECT count(*) FROM PageAction FACET {{location}}
出力形式number
で変数を作成し、それをパーセンタイル関数内で使用できます。
たとえば、 55
と90
の 2 つの可能な値を持つタイプlist
の{{percentile}}
変数を作成できます。出力形式をnumber
として設定したいと思います。
次に、次のクエリを使用してウィジェットを作成します。
SELECT percentile(duration,{{percentile}}) FROM PageAction
フィルタリングに変数を使用するには、次のように、作成した変数をWHERE
句の右側に追加するだけです。
SELECT countryCode, city FROM PageAction WHERE countryCode IN ({{countryCode}})
デフォルトでは、「タイムピッカーを無視する」オプションが有効になっています。つまり、ダッシュボードのタイムピッカーに別の値が選択されている場合でも、クエリは常にデフォルトの 1 HOUR
時間範囲値を使用して実行されます (例: 5 分、3)時間など)。 この場合の例外は、次のようなクエリにSINCE
句を使用して明示的な時間範囲が設定されている場合です。
結果は過去 5 分間の範囲になります。
「タイムピッカーを無視」オプションがオフの場合、クエリはタイムピッカーで選択された値で実行されます。 たとえば、以下のスクリーンショットのようにタイムピッカーを 30 分に設定すると、変数編集フォームで「タイムピッカーを無視する」フィールドがオフに設定されます。
これにより、過去 30 分間の値が得られます。 タイムピッカーの値をDefaultに設定し、クエリにSINCE
句が含まれている場合、最新の値を使用してクエリが実行されます。
場合によっては、異なる種類のデータに同じルールを適用するクエリがあることがあります。 以下は、データ型を除いて同一の 2 つのウィジェットの例です。
ウィジェット 1:
SELECT count(*) FROM DataType1 SINCE 1 day ago
イド 2:
SELECT count(*) FROM DataType2 SINCE 1 day ago
2 つの別個の ウィジェット を作成する代わりに、Identifier[出力形式]のOutput format[識別子]を持つ変数を使用して 1 つの ウィジェット を作成できます。 次に、これをFROM
句で使用して、さまざまなデータ型をクエリできます。
たとえば、2 つの値DataType1
とDataType2
を持つList型の{{dataType}}
変数を作成できます。 Output Format[出力形式を]Identifier[識別子]に設定します。
次に、ウィジェットを作成して実行します。