NXQL tutorial (classic)
概要
Nexthink Query Language (NXQL) は、NXQL API を介して Nexthink Engine のインメモリデータベースをクエリするために設計された言語です。 この言語は、SQL に似たキーワードを使用していますが、LISP に類似した構文を持っています。
NXQL は、セレクタ言語（内部で開発された他の疑似SQL言語）の進化系です。 Finder、Portal、およびネクスシンクエンジンの統合された Lua インタープリタ内で動作する Lua スクリプトは、現在、エンジンをクエリするためにセレクタ言語を使用しています。 統合のために特別に設計され、速度向上を考慮しているため、NXQL は多くの分野でセレクタ言語を上回ります。 NXQL は、より複雑なクエリを記述できるようになり、オブジェクトのトラバーサルを制御できるため、クエリは通常より速く実行されます。
このチュートリアルは、NXQL を例を用いて学ぶ過程を案内するためのものです。 提案された順序で NXQL チュートリアルを進めることで、最大限に活用してください。
このチュートリアル内のクエリを実行するには、統合ツールキット モジュールを含むすべてのエンジンで入手可能な NXQL エディタを使用してください。 このチュートリアルの残りの部分は、管理者資格情報で NXQL エディタに認証されており、利用可能なすべてのデータ（コンピュータの名前やユーザー名など）を見るアクセス権を持っていることを前提としています。
最初のクエリ
利用可能なすべてのデバイスの一意識別子と名前のリストを取得するには、次のクエリを入力します：
クエリは開き括弧で始まり、閉じ括弧で終わることに注意してください。 クエリが適切に形成されるためには、開き括弧と閉じ括弧の数が均衡している必要があります。 クエリの構築を支援するために、必要に応じてシステムが自動的に欠落している括弧を最後に追加します。 クエリはキーワード select で始まるため、これを select ステートメントと呼びます。 select ステートメントには、取得するフィールドのリストと、フィールドが見つかるテーブルを指定する from 節が含まれます。
クエリ内では、フィールドにワイルドカード文字を含めることができます。 たとえば、デバイスの名前とアンチウイルスに関連するすべてのフィールドを取得するには、次のクエリを入力します：
フィールド名をタイプミスした場合、システムはエラーを示し、最も誤って入力したと思われる正確なフィールド名または、その入力に近いフィールドが存在しない場合は、その文脈で使用できるフィールド名の全リストを代替案として提案します。
デバイスのサブセットのみを取得するには、いくつかのフィールドの値によって結果をフィルタリングします。 たとえば、デバイス名が NXT-DV10 であるデバイスのみを選択するには、次のクエリを入力します：
from 節の中では、where 節は名前が NXT-DV10 に等しいデバイスのみを保持します。 where 節の最初の引数はフィルタが適用されるテーブルであり、2つ目の引数はフィルタそのものの式です。 フィルタは操作、フィールド名、型付き値の順で構成されます。 可能な操作には、eq、ne、lt、le、gt、ge（それぞれ、等しい、等しくない、未満、以下、より大きい、以上を意味します）があります。 値の型はフィールドの型と一致している必要があります。 データモデル でのすべてのフィールドの名前と型を確認してください。
論理的な AND 操作
複数のフィルタに対して where 節を定義できます。 この場合、すべてのフィルタに一致するオブジェクトのみが選択されます。
たとえば、次のクエリは、Windows 7 を実行しており、アンチウイルスがインストールされていないデバイスのリストを返します：
論理的な OR 操作
一方、他のフィルタセットのいずれかに一致するオブジェクトを取得したい場合は、同一種類のオブジェクトに対して 2 つの where 節を書く必要があります。
たとえば、Windows 7 または Windows 8 / 8.1 を実行しているデバイスのリストを取得するには、次のクエリを入力します：
これが同じ種類のオブジェクトに対する where 節に有効であることを忘れないでください。 異なるテーブルのオブジェクトに条件を設定するより高度なクエリを書くとき、異なる種類のオブジェクトに対する複数の where 節は論理 AND として動作することを覚えておいてください。 以下に例を示します。
この段階で、Nexthink によって定義された任意のオブジェクトテーブルの任意のフィールドをクエリできるようになります。 デバイスとは異なる他のオブジェクト、例えばユーザーやバイナリを試して、NXQL に慣れてください。
イベントの使用
イベントは、特定の瞬間に IT インフラストラクチャ内で発生する出来事です。 すべてのイベントにはタイムスタンプがあるため、イベントは時間で順序付けることができます。 イベントは、インメモリデータベースの基本的な情報ユニットであるという点で、Nexthink テクノロジーの中心です。 それらが記述する出来事の種類に応じて、いくつかのタイプのイベントがあります。 各イベントタイプは、明確に定義された一連のオブジェクトにリンクされています。 例えば、接続イベントは、ユーザー、デバイス、バイナリ、宛先、および ポートオブジェクトにリンクされています。
データベースのイベント数は通常、他の種類のオブジェクトの数よりも何桁も大きいです。 デバイステーブルのようなオブジェクトテーブルには数百から1万の要素が含まれる場合がありますが、イベントテーブルには数千万の要素が含まれることがあります。 パフォーマンスの理由から、イベントを含むクエリのタイムスパンを設定する際にはこれを念頭に置くことが重要です。
クエリでは、次の 2 つの方法でイベントテーブルを使用できます：
指定された期間内に発生したイベントを直接選択します。 例えば、firefox.exeによって最後に行われた100件の接続を取得するには、前日を指定します：
指定された期間内に発生するイベントにリンクされたオブジェクトを選択します。 例えば、前日に firefox.exe を使用して web にアクセスしたすべてのデバイスを取得するには：
イベントに加えて、with 節は、デバイスとパッケージオブジェクトとの関係を表す package キーワードの前にも使用できます。以下で説明します。
イベントによる論理操作
クエリをさらに絞り込むことができます。 例えば、前日に firefox.exe を使用して mail.google.com にアクセスしたデバイスに関心があると仮定します：
このクエリには、バイナリとドメインという異なる種類のオブジェクトに適用される 2 つの where 節があることに注意してください。 したがって、それらは論理 AND として動作し、2 つの条件が満たされる必要があります。
論理 OR として動作するには、where 節は同じ種類のオブジェクトに適用される必要があります。 例えば、前日 mail.google.com にアクセスするために firefox.exe に加えて chrome.exe を使用したデバイスを調べ、クエリを拡張します。以下のクエリを入力します：
一方、オリジナルのクエリをさらに詳細化し、firefox.exe のバージョンが 50 未満のデバイスのみを返したい場合は、次の式を入力します：
つまり、同じ種類のオブジェクトの where 節で複数の条件を設定します（この場合、バイナリ オブジェクト）。条件は論理 AND として結合されます。
最後に、異なる種類のオブジェクトの条件を論理 OR で組み合わせる必要がある稀な場合には、以下で文書化された union キーワードを使用します。
集計の計算
イベントにリンクされたオブジェクトの選択は 集計 で強化できます。 集計は、選択されたすべてのイベントに対して、指定されたフィールドのカウント、合計または平均を計算する名前付き関数です。 例えば、incoming_traffic 集計は、with 節で選択されたすべての connection または web_request イベントの incoming_traffic フィールドのすべての値を加算します。 集計は with 節内の compute 節で指定します。
一部の集計はその計算中にイベントの移動を必要とするため、集計を使用するときにイベントを使用する場合と同様のパフォーマンスの懸念があります。 さもないと、多くのイベントを移動する必要のある可能性があるクエリの時間間隔を制限することが重要です。 データモデルで FP としてマークされていない集計には、移動を制限するために between 節が必要です。 ただし、 between 節は指定可能な時間間隔を厳密に制限しません。 特にクエリが定期的に繰り返される場合は、合理的な時間間隔を設定する責任があります。
例えば、過去 7 日間に mail.google.com に対して行われたすべての web リクエストの各デバイスの受信トラフィックを計算するには、次のクエリを記述します：
各イベントテーブルの集計リストは NXQL データモデルに定義されています。
この段階で、集計の値に基づいてデバイスをフィルタリングする方法を疑問に思うかもしれません。 前の例のように、昨日 1GB のデータを転送したデバイスを選択したいかもしれません。 これが having 節の目的であり、with 節内の from 節に現れるかもしれません。 もちろん、having 節でフィルタリングされた集計は最初に compute 節内で宣言されている必要があります。
カテゴリとカスタムフィールドの使用
NXQL では、カテゴリとカスタムフィールドは同等に扱われます。 これらは通常のフィールドのように動作しますが、名前の前に # が付いています。 たとえば、デバイスのカテゴリとして Location があると仮定して、デバイスとその Location の一覧を取得するには、次のクエリを記述します：
また、カテゴリまたはカスタムフィールドをフィルタとして使用することもできます：
スペースまたは引用符を含むカテゴリまたはカスタムフィールドの名前は引用符で囲む必要があります：
キャンペーンのカスタムフィールド
キャンペーンの結果は、オブジェクト user のカスタムフィールドとして NXQL に表示されます。 キャンペーンに関連するカスタムフィールドの名前は次の形式を持ちます：
#"campaign:Name of the campaign/Name of the question"
カスタムフィールド名の先頭に campaign: キーワードを使用していることに注意してください。 例えば、キャンペーン Laptop satisfaction 内の質問 Device preference に対するすべてのユーザーの回答を知りたい場合、次のクエリを記述します：
single answer または opinion scale 質問への回答の基になる型は string 型です。 次に、複数回答質問への回答の基になる型は、文字列のリストです。 回答の値を eq と ne 演算子で比較します（回答値を比較するための他の演算子は使用できません）。 例えば、Device preference の単回答質問で No と答えなかったすべてのユーザーの名前と実際の回答を得るには、次のクエリを記述します：
同様に、特定の単回答または意見尺度質問にまだ回答していないユーザーを選択するには、空文字列と比較します：
複数回答質問の場合、ユーザーが回答で示した回答の組み合わせをクエリすることができます。 上記で説明した where 節で論理 AND および論理 OR 操作を使用するか、特定の組み合わせと正確に一致する値のリストを指定します。 例えば、キャンペーン Laptop satisfaction の Positive points 質問に対して Speed および Size（おそらく他のものも）と答えたユーザーを得るには、次のクエリを記述します：
代わりに、Speed と Size のみ（他のものは何もない）と正確に回答したユーザーをクエリしたい場合は、それらをリストとして指定します：
または、Speed または Size（または両方）を選択したユーザーを取得するには、論理 OR バージョンのクエリを記述します：
最後に、複数回答質問にまだ答えていないユーザーを取得するには、空文字列ではなく nil キーワードで比較します：
スコアのカスタムフィールド
スコアは、オブジェクトの特別なカスタムフィールドとして NXQL を通じてアクセス可能です device または user。 スコアに関連するカスタムフィールドの名前は次の形式を持ちます：
#"score:Name of the score definition/Name of the score"
カスタムフィールド名の先頭に score キーワードを使用していることに注意してください。 例えば、すべてのデバイスの ブート速度 リーフスコアを取得するには、以下のクエリを記述します。このスコアは、デバイスパフォーマンス スコア定義内にあります。
スコアは数値を保持しているため、スコアの基になる型はすべて real 型です。 スコアの値に条件を設定する例として、以下のクエリは、ブート速度 スコアが 5.0 よりも高いすべてのデバイスを取得します：
数値以外にも、スコアには値がまったく設定されていない場合もあります。 空のスコアを持つオブジェクトをクエリするには、eqまたはne演算子を使用してスコアの値をnilキーワードと比較します。 たとえば：
リモートアクションのカスタムフィールド
オブジェクト_device_の特別なカスタムフィールドにアクセスして、リモートアクションの実行結果やその他の情報をNXQLを通じて取得します。 リモートアクションに関連するカスタムフィールドの名前は以下の形式です：
#"action:Name of the remote action/Name of the output or exec info"
カスタムフィールドの名前の初めにactionキーワードを使用していることに注意してください。 たとえば、すべてのデバイスでリモートアクションGet Event LogのExecution statusを取得するには、以下のクエリを書きます：
特定のリモートアクションにステータスがないデバイスをフィルタリングするには、ステータスの値をnilキーワードと比較します。 たとえば、リモートアクションGet Event Logに関連するすべてのデバイスで実行ステータスを取得するには、以下を入力します：
リモートアクションの結果（つまり、その_出力_値）はNXQLを通じてアクセス可能です。 NXQLクエリ内で、リモートアクションで定義された出力の名前を正確に入力してください。 出力の_name_は、Finderに表示される_ラベル_とは異なる場合がありますので注意してください。 たとえば、リモートアクションGet Event Logで生成されたファイルへのパスを取得するには（出力の名前OutputFile、ラベルOutput file）、以下のクエリを書きます：
各出力値は、リモートアクションの定義に示される型です。 空の値を比較するには、数値出力の場合はnil、文字列型出力の場合は空文字列""を使用します。
Platformの使用
NXQLは3つのPlatformをサポートしています：Windows、Mac、およびMobileです。
NXQLエディターを使用する場合、エディターの右上隅のチェックボックスをクリックして、クエリが適用されるプラットフォームを選択します。
スクリプトやインテグレーションからのHTTPリクエストを介してAPIに直接クエリを行う場合は、導入部で説明されているplatformパラメータを使用します。
複数のプラットフォームを選択する場合、選択したすべてのプラットフォームに共通であるテーブルとフィールドのみがクエリで有効であることに注意してください。 たとえば、デバイスのnameフィールドは3つのプラットフォームすべてで使用可能ですが、all_antivirusesはWindowsプラットフォームのデバイスのみで使用可能です。 したがって、フィールドall_antivirusesを含むマルチプラットフォームクエリは無効です。
複数のテーブルの選択
NXQLには複数のテーブルから情報を組み合わせることができる2種類のクエリがあります：
特定の種類のイベントに関連しているオブジェクトのユニークなペアを選択します。
特定の種類のイベント、およびそれらのイベントにリンクされたオブジェクトからの情報を選択します。
同じように見えるかもしれませんが、これらのクエリは以下で詳述するいくつかの側面で異なります。
複数のテーブルを要求する最も一般的なタイプのクエリは、一連のイベントに参加したオブジェクトのユニークなペアを選択することです。 このタイプのクエリでは、2つのオブジェクトテーブルのみを選択でき、with句内で各オブジェクトペアをリンクするイベントテーブルを指定します。 select句では、対応するフィールドリストの前にそれぞれのオブジェクトテーブルの名前を指定し、その後from句でオブジェクトテーブルの名前を繰り返します。 たとえば、firefox.exeを実行したユーザーとそれが実行されたデバイスの名前に興味がある場合は、次のクエリを記述します：
2番目の種類のクエリでは、選択されたイベントテーブルの個々のイベントが主な関心事であり、各イベントにリンクされたオブジェクトからの情報によってデコレートすることができます。 したがって、第2の種類のクエリを書くには、from句でイベントテーブルの名前と各追加オブジェクトテーブルの名前、およびselect句でそれらの対応するフィールドリストの前に指定します。 たとえば、次のクエリは、firefox.exeの最後の100接続、および各接続を開始したデバイスの名前を返します：
この2番目の種類のクエリでは、オブジェクトが複数のイベントにリンクされている場合、結果で繰り返される可能性があります。 たとえば、上記の例では、選択された接続の1つ以上にリンクされているデバイスが存在するかもしれません。 そのデバイスの名前は、関連する各接続のために繰り返し表示されます。 これは、ユニークなペアのオブジェクトを含む最初の種類のクエリとは逆であり、多くのイベントにリンクされているかもしれませんが、個々のイベントには興味がありません。
示された例にもかかわらず、第2の種類のクエリは2つのテーブルに限定されないことに気付いたかもしれません。 代わりに、1つのイベントテーブルと1つ以上のオブジェクトテーブルを選択する必要があります。 たとえば、今日行われた脅威レベルが設定されていないバイナリの実行をすべて取得し、バイナリパスとそれに関与しているバイナリ、デバイス、ユーザーについての情報を表示するには、次のように記述します：
制約に関しては、両方のテーブルクエリには、返されるエントリーの最大数を制限するためのlimit句が必要であり、集計の計算を許可しません。
クエリでパッケージを使用
packageは、オブジェクトテーブルまたは関連テーブルとして機能できるという意味で、NXQLにおける特別なキーワードです。 実際、パッケージはその属性（名前、バージョン、会社など）を持つインストール済みのパッケージ自体、またはそのインストールを通じたデバイスとの関係を指すことができます。 これは、通常イベントのみに使用されるwith句の中でパッケージを使用できる理由です。
たとえば、パッケージMicrosoft Office 365がインストールされているすべてのデバイスをリストするには、次のクエリを記述します（packageは関連として機能）：
デバイスとともにパッケージバージョンを取得するには、次のクエリを記述します（packageがオブジェクトとしても関連としても機能する）：
単純に各デバイスにインストールされているパッケージの数を計算したい場合は、次のクエリを記述します（packageは関連として機能）：
オブジェクトのセットに対する操作
NXQLを使用すると、同じタイプのオブジェクトの2つのリストを計算し、それらを1つのクエリで単一の結果に結合することができます。
たとえば、パッケージMicrosoft Officeを持たないデバイスのリストを計算するには：
上記のクエリを実行するために、システムはすべてのデバイスのリストを計算し、Microsoft Officeを持つデバイスのリストを差し引くことで、Microsoft Officeを持たないデバイスのリストを論理的に作成します。
3つのセット演算子が存在します：
except (A) (B) AにあるがBにないオブジェクトを返します。
union (A) (B) AまたはBにあるすべてのオブジェクトを返します。
intersect (A) (B) AとBの両方にあるオブジェクトのみを返します。
セット演算子でリンクされる2つのfrom句には1つのオブジェクトテーブルしか使用できないことを覚えておいてください。 たとえば、デバイスとユーザーのユニオンを行うことは不可能です。
これらの演算子はオブジェクトテーブルでのみ機能し、イベントテーブルでは機能しないことにも注意してください。
カテゴリおよびカスタムフィールドの値を更新する
カテゴリ、つまり動的フィールドを更新するには、updateステートメントを使用します。 updateステートメントは、from句で選択されたすべてのオブジェクトに指定された動的フィールドの値を設定します。 たとえば、最後のIPアドレスに基づいて一部のデバイスの場所をパリに設定するには、次のクエリを記述します：
カテゴリの設定は、キーワードに関連する自動タグ付けルールをオーバーライドします。 自動タグ付けルールを再アクティブ化したい場合は、次のクエリを書いてください。
updateステートメントによって返されるテーブルには、すべての変更されたオブジェクトの識別子が含まれています。
プレースホルダーの使用
よく実行するクエリを一般化するには、プレースホルダーを使用します。 プレースホルダーは、値、カスタムフィールド名、またはクエリ内のカテゴリ名の代わりに使用する%キャラクターでプレフィックスされた数字です。 クエリが実行されると、各プレースホルダーはパラメータとして指定された実際の値に置き換えられます。 たとえば、次のクエリには2つのプレースホルダーが含まれています：
このクエリを実行するには、デバイスのカスタムフィールドまたはカテゴリの名前とその実際の値をパラメーターとして提供する必要があります。 NXQLエディターでは、クエリの下にある2つのパラメーター入力のテキストボックスにパラメーター値を提供します。
プログラムされたクエリでは、HTTPリクエストで実際のパラメーターを提供します。
Last updated