カスタム クエリの仕様

  • [アーティクル]

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

データセット

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

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

{
      "datasetName": "OfficeUsage",
      "selectableColumns": [
        "CustomerTenantId",
        "CustomerTpid",
        "WorkloadName",
        "Month",
        "PaidAvailableUnits",
        "MonthlyActiveUsers",
        "CustomerName",
        "CustomerMarket",
        "CustomerSegment",
        "MPNId",
        "PartnerName",
        "PartnerLocationID",
        "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 とします。
  • データをエクスポートできる一定の期間があります。

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

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

クエリ 説明
SELECT CustomerTenantId, PaidAvailableUnits FROM 
OfficeUsage TIMESPAN LAST_MONTH		 このクエリは、過去 1 か月間のすべての CustomerTenantID とそれに対応する PaidAvailableUnits を取得します。
SELECT CustomerTenantId, PaidAvailableUnits FROM
OfficeUsage ORDER BY PaidAvailableUnits LIMIT 10		 このクエリでは、上位10件の顧客テナントが、利用可能なユニット数の降順で取得されます。 
Standard Edition LECTCustomerTenantId、PaidAvailableUnits、MonthlyActiveUsers FROM OfficeUsage WHERE MonthlyActiveUsers > 100000 ORDER BY MonthlyActiveUsers TIMESPAN LAST_6_MONTHS このクエリでは、月単位の Activeusers が10万より大きいすべての顧客の Paid利用単位と月単位のユーザーが取得されます。 
SELECT CustomerTenantId, Month, MonthlyActiveUsers FROM
OfficeUsage WHERE CustomerTpId IN ('2a31c234-1f4e-4c60-909e-76d234f93161', '80780748-3f9a-11eb-b378-0242ac130002') 		このクエリでは、顧客の 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 演算子値
      • 演算子: = | > | < | >= | <= | != | LIKE | NOT LIKE | IN | NOT IN
        • 値: Number | StringLiteral | MultiNumberList | MultiStringList - Number: -? [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、選択列の一覧にメトリック列が含まれている場合、キーワード (keyword)は必要ありません。

例:

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 フィールドの値にする必要があります。

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

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

次のステップ