カスタム クエリの仕様

パートナーは、このクエリの仕様を使用して、分析テーブルからデータを抽出するためのカスタム クエリを簡単に作成できます。 クエリを使用すると、特定の条件に一致する目的の列とメトリックのみを選択できます。 言語仕様の中核となるのは、カスタム クエリを記述する基礎となるデータセット定義です。

データセット

テーブルと列を含むデータベースに対して一部のクエリが実行されるのと同じように、カスタム クエリは列とメトリックを持つデータセットに対して動作します。 クエリを作成するために使用できるデータセットの完全な一覧は、データセット API を使用して取得できます。

JSON として表示されるデータセットの例を次に示します。

{ 
      "datasetName": "OfficeUsage", 
      "selectableColumns": [ 
        "CustomerTenantId", 
        "CustomerTpid", 
        "WorkloadName", 
        "Month", 
        "PaidAvailableUnits", 
        "MonthlyActiveUsers", 
        "CustomerName", 
        "CustomerMarket", 
        "CustomerSegment",  
        "MPNId", 
        "PartnerName", 
        "PartnerLocation", 
        "PartnerAttributionType", 
        "IsDuplicateRowForPGA" 
      ], 
      "availableMetrics": [ 
        "CustomerCount", 
        "CustomerTenantCount", 
        "TotalPaidAvailableUnits", 
        "TotalMonthlyActiveUsers" 
      ], 
      "availableDateRanges": [ 
        "LAST_MONTH", 
        "LAST_3_MONTHS", 
        "LAST_6_MONTHS", 
        "LAST_1_YEAR", 
        "LIFETIME" 
      ], 
      "minimumRecurrenceInterval": 24 
    },

データセットの各部分

  • データセット名は、データベース テーブル名に似ています。 たとえば、OfficeUsage などです。 データセットには、顧客の Tenantid など、選択できる列の一覧があります。
  • データセットには、データベース内の集計関数に似たメトリックもあります。 たとえば、Total当月を Activeusers とします。
  • データをエクスポートできる一定の期間があります。

データセットに対するクエリの作成

これらは、さまざまな種類のデータを抽出する方法を示すサンプル クエリです。

クエリ 説明
選択 顧客 Tenantid、 Paidの ユニット
OfficeUsage TIMESPAN LAST_MONTH
このクエリでは、過去1か月のすべての CusotmerTenantID とそれに対応する Paid利用単位が取得されます。
選択 顧客 Tenantid、 Paidの ユニット
Paid利用単位 数の 制限 10 による officeusage
このクエリでは、上位10件の顧客テナントが、利用可能なユニット数の降順で取得されます。
選択 顧客 Tenantid、 Paid利用単位、月 単位 Activeusers FROM officeusage (月単位のユーザー > 10万 ORDER BY 月単位 の時間 間隔 LAST_6_MONTHS このクエリでは、月単位の Activeusers が10万より大きいすべての顧客の Paid利用単位と月単位のユーザーが取得されます。
選択 顧客 テナント Id、月、月のユーザー
OfficeUsage ( "2a31c234-1f4e-4c60-909e-76d234f93161"、"807807483f9a-11eb8-02 42 ac130002") の顧客 tpid
このクエリでは、顧客の Tenantid と毎月2人の顧客の Tpid 値によって毎月の月ごとのアクティブユーザーが取得されます: ' 2a31c234-1f4e-4c60-909e-76d234f93161 ' と ' 80780748-3f9a-11eb8-0242 ac130002 '。

クエリの仕様

このセクションでは、クエリの定義と構造について説明します。

文法リファレンス

この表では、クエリで使用される記号を説明します。

クエリ 説明
? オプション
* 0 個以上
+ 1 個以上
\| または、いずれかのリスト

[クエリ定義]

クエリステートメントには、SelectClause、FromClause、WhereClause、OrderClause、LimitClause、TimeSpan の各句があります。

  • Selectclause: SELECT ColumOrMetricName (, ColumOrMetricName)*
    • ColumOrMetricName: データセット内で定義される列とメトリック
  • FromClause: FROM DatasetName
    • DatasetName: データセット内で定義されるデータセット名
  • WhereClause: WHERE FilterCondition (AND FilterCondition)
    • FilterCondition: ColumOrMetricName Operator Value
      • 演算子: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
      • Value: Number | StringLiteral | MultiNumberList | MultiStringList
        • 数値: -? [0-9]+ (. [0-9] [0-9]*)?
        • Stringliteral: ' [a-zA-Z0-9_]*'
        • MultiNumberList: (Number (,Number)*)
        • Multistringlist: (StringLiteral (,StringLiteral)*)
  • Orderclause: ORDER BY OrderCondition (,OrderCondition)
    • Ordercondition: ColumOrMetricName (ASC | DESC)*
  • Limitclause: LIMIT [0-9]+
  • TimeSpan: TIMESPAN ( TODAY | YESTERDAY | LAST_7_DAYS | LAST_14_DAYS |LAST_30_DAYS | LAST_90_DAYS | LAST_180_DAYS | LAST_365_DAYS |LAST_MONTH | LAST_3_MONTHS | LAST_6_MONTHS | LAST_1_YEAR | LIFETIME)

クエリ構造

レポート クエリは次の複数の部分で構成されます。

  • SELECT
  • FROM
  • WHERE
  • ORDER BY
  • LIMIT
  • TIMESPAN

各部分について、下で説明します。

SELECT

クエリのこの部分では、エクスポートする列を指定します。 選択できる列は、データセットの selectableColumns および availableMetrics セクションに示されているフィールドです。

必要に応じて、の DISTINCT 後にキーワードを指定でき SELECT ます。 を指定した場合 DISTINCT 、最後にエクスポートされた行には、選択した列の個別の値が常に含まれます。 メトリックは、選択した列の個別の組み合わせごとに計算され DISTINCT ます。したがって、[列の選択] の一覧にメトリック列が含まれている場合、キーワードは必要ありません。

例:

SELECT CustomerTenantId, PaidAvailableUnits; 
SELECT DISTINCT CustomerTenantId

FROM

クエリのこの部分は、データをエクスポートする必要があるデータセットを示します。 ここで指定するデータセット名は、データセット API によって返される有効なデータセット名である必要があります。

例:

  • FROM OfficeUsage
  • FROM AzureUsage

WHERE

クエリのこの部分は、データセットのフィルター条件を指定するために使用されます。 この句に示されているすべての条件に一致する行のみが、最終的にエクスポートされたファイルに存在します。 フィルター条件は、 selectableColumns および availableMetrics に示されている任意の列に設定できます。 演算子が IN または NOT IN の場合、フィルター条件に指定する値は、数値のリストまたは文字列のリストにのみすることができます。 値は常にリテラル文字列として指定でき、列のネイティブ型に変換されます。 複数のフィルター条件は、AND 演算で区切る必要があります。

例:

  • CustomerTenantId= '868368da-957d-4959-8992-3c12dc7e6260'
  • CustomerName LIKE '%Contoso%'
  • CustomerId NOT IN (1000, 1001, 1002)
  • OrderQuantity=100
  • CustomerTenantId='7b487ac0-ce12-b732-dcd6-91a1e4e74a50' AND CustomerTpId=' 0f8b7fa0-eb83-a183-1225-ca153ef807aa'

ORDER BY

クエリのこの部分では、エクスポートされる行の順序付け条件を指定します。 順序を定義できる列は、データセットの selectableColumns および availableMetrics からのものである必要があります。 順序付けの方向が指定されていない場合、列の既定値は DESC になります。 条件をコンマで区切ることで、複数の列に対して順序付けを定義できます。

例:

  • ORDER BY MonthlyActiveUsers ASC, Month DESC
  • ORDER BY CustomerName ASC, Month

LIMIT

クエリのこの部分では、エクスポートする行の数を指定します。 指定する数値は、0 以外の正の整数である必要があります。

TIMESPAN

クエリのこの部分では、データをエクスポートする必要がある期間を指定します。 使用できる値は、データセット定義の availableDateRanges フィールドの値にする必要があります。

クエリの仕様における大文字と小文字の区別

この仕様では、大文字と小文字はいっさい区別されません。 定義済みのキーワードや列の名前および値は、大文字または小文字を使用して指定できます。

次のステップ