クエリ API による CRM Analytics データの照会

プログラムによる Analytics クエリの実行

REST API では、SAQL または SQL クエリステートメントを使用して Analytics データを照会できます。クエリエンドポイントは wave/query です。クエリを実行するには、SAQL Query Input を使用して POST リクエストボディを取得します。

SAQL クエリ要求の例

REST API を使用して SAQL クエリを実行する場合は、照会するデータセットを指定するときにデータセット ID とデータセットバージョン ID の両方が必要です。クエリでデータセット名を使用するとエラーが返されます。要求に必要な属性は query のみです。

1{
2    "query" : "q = load \"<datasetId>/<datasetVersionId>\"; q = group q by 'Status'; q = foreach q generate 'Status' as 'Status', count() as 'count'; q = limit q 20;"
3}

SAQL クエリ応答の例

応答結果には、metadata と records が含まれています。元のクエリと応答時間も返されます。警告またはエラーが生じた場合は、warnings が含まれます。前の例で実行した SAQL クエリの場合、応答は次のようになります。

1{
2  "action" : "query",
3  "responseId" : "4l-kl6BTnH4ay9-qbx2Re-",
4  "results" : {
5    "metadata" : [ {
6      "lineage" : {
7        "type" : "foreach",
8        "projections" : [ {
9          "field" : {
10            "id" : "q.Status",
11            "type" : "string"
12          },
13          "inputs" : [ {
14            "id" : "q.Status"
15          } ]
16        }, {
17          "field" : {
18            "id" : "q.count",
19            "type" : "numeric"
20          }
21        } ],
22        "input" : {
23          "type" : "group",
24          "groups" : [ {
25            "id" : "q.Status"
26          } ]
27        }
28      },
29      "queryLanguage" : "SAQL"
30    } ],
31    "records" : [ {
32      "Status" : "Closed",
33      "count" : 7
34    }, {
35      "Status" : "Open",
36      "count" : 6
37    } ]
38  },
39  "query" : "q = load \"<datasetId>/<datasetVersionId>\"; q = group q by 'Status'; q = foreach q generate 'Status' as 'Status', count() as 'count'; q = limit q 20;",
40  "responseTime" : 3,
41  "warnings" : [
42    {
43      "code" : "001",
44      "message" : "Limit exceeded"
45    },
46    {
47      "code" : "002",
48      "message" : "Another warning..."
49    }
50  ]
51}

SQL リクエストボディの例

クエリを実行する場合のデフォルト言語は SAQL です。SQL を使用するには、要求に属性 "queryLanguage" : "SQL" を含めます。SQL クエリでは、データセット名を使用できます。SQL では、同じクエリ要求が次のようになります。

1{
2  "query" : "SELECT Status, COUNT(*) as StatusCount FROM \"<name>\" GROUP BY Status LIMIT 20;", 
3  "queryLanguage": "SQL"
4}

要求に "queryLanguage" : "SQL" を指定し忘れると、構文エラーが返されます。

メモ

SQL クエリ応答の例

この応答レコードは SAQL 応答と同じように見えますが、metadata が異なります。columns キーには、クエリの射影の名前と型が含まれます。

1{ 
2  "action" : "query", 
3  "responseId" : "4l-mtW26NZ4OYu-qbx3GN-", 
4  "results" : { 
5    "metadata" : [ 
6      { 
7        "columns" : [ 
8          { 
9            "columnLabel" : "Status", 
10            "columnType" : "varchar" 
11          }, 
12          { 
13            "columnLabel" : "StatusCount", 
14            "columnType" : "numeric" 
15          } 
16        ], 
17        "queryLanguage" : "SQL" 
18      } 
19    ], 
20    "records" : [ 
21      { 
22        "Status" : "Closed", 
23        "StatusCount" : 7 
24      }, 
25      { 
26        "Status" : "Open", 
27        "StatusCount" : 6 
28      } 
29    ] 
30  }, 
31  "query" : "SELECT Status, COUNT(*) as StatusCount FROM \"Cases1\" GROUP BY Status LIMIT 20;", 
32  "responseTime" : 9 
33}

SQL メタデータの例: 集計を含むグループ化クエリ

このクエリは、集計 avg(Sales) を AvgSales として射影し、数値データを返します。metadata では、対応する列のデータ型が数値として返されます。

1"metadata": [
2  "columns": [
3    {
4      "columnLabel": "City",
5      "columnType": "varchar"
6    },
7    {
8      "columnLabel": "AvgSales",
9      "columnType": "numeric"
10    }
11  ],
12  "queryLanguage": "SQL"
13]

SQL クエリおよびレスポンスボディの例 : 日付項目から日付要素を抽出

この例では、CloseDate 項目から年、月、日を数値として返します。この要求には timezone 属性があります。timezone は省略可能な属性で、組織でタイムゾーンが有効になっている場合にのみ使用できます。

1{
2  "query" : "SELECT EXTRACT(YEAR FROM CloseDate) as year, EXTRACT(MONTH FROM CloseDate) as month, EXTRACT(DAY FROM CloseDate) as day From "OpportunityFiscalEM"
3  "queryLanguage" : "SQL",
4  "timezone" : "America/Los_Angeles"
5}

1"metadata": [
2  "columns": [
3    {
4      "columnLabel": "year",
5      "columnType": "numeric"
6    },
7    {
8      "columnLabel": "month",
9      "columnType": "numeric"
10    },
11    {
12      "columnLabel": "day",
13      "columnType": "numeric"
14    }
15  ],
16  "timezone": "America/Los_Angeles",
17  "queryLanguage": "SQL"
18]

SQL クエリおよびレスポンスボディの例: DateTime 型の日付項目を射影

このクエリは、日付情報をタイムスタンプとして返します。

1{
2  "query" :  "SELECT CloseDate From "OpportunityFiscalEM",
3  "queryLanguage" : "SQL"
4}

1"metadata": [
2  "columns": [
3    {
4      "columnLabel": "CloseDate",
5      "columnType": "timestamp"
6    }
7  ],
8  "queryLanguage": "SQL"
9]

メタデータの詳細の照会

クライアントがクエリを解析して、使用されているディメンションとグループを判断できますが、コストがかかる可能性があります。そのためほとんどの場合、クエリ応答には metadata セクションが含まれ、このセクションでグルーピングと列情報が提供されます。metadata セクションが存在する場合は、クエリ応答ペイロードの results キーで見つけることができます。metadata セクションは、columns キーと groups キーで構成されます。

1"metadata":{
2  "columns" : [
3    {
4      "name" : "dim name",
5      "type" : "String"
6    }
7  ],
8  "groups" : [
9    "name",
10    "destination"
11  ]
12}

columns キーには、クエリの射影の名前と型が含まれます。groups キーには、クエリで使用されるグループのリストが含まれます。

• metadata は、クエリが成功したときに追加されます。クエリの実行が失敗した場合、構文エラーがある場合、または認証コールバックが失敗した場合、metadata は結果に追加されません。
• 列名に設定される値は、ディメンションの名前ではなく射影に付けられた別名です。
• クエリが複雑ではなく、返されるグループ名が非決定的な (グループの名前がクエリの複数のストリームで使用されている) 場合、クエリで使用されるグループのリストが groups キーで返されます。これは、クエリが cogroup または union を使用する場合です。そのような場合、groups キーは空になります。

メモ