Query Resource

Resource URL

1/wave/query

Formats

JSON

Available Version

36.0

HTTP Methods

POST

POST Request Body

Parameter Name	Type	Description	Required or Optional	Available Version
query	Object (Saql​Query​Input​Representation)	The query, in JSON format.	Required	36.0

Example Request Body

1{
2    "query":"q = load \"0Fbxx0000000006CAA/0Fcxx000000001dCAA\";
3     q = group q by 'FirstName';
4     q = foreach q generate 'FirstName' as 'FirstName', count() as 'count';
5     q = limit q 2000;"
6}

POST Response Body

Description	Filter Group and Version	Available Version
The results of a SAQL query, in JSON format. This may also contain metadata describing grouping and column types/names. Refer to the example response bodies and the section discussing query metadata.	Small, 36.0	36.0

SaqlQueryInputRepresentation

Property Name	Type	Description	Required or Optional	Available Version
name	String	The query name.	Required	41.0
query	String	The query.	Required	36.0

Example Response Body (without metadata)

1{
2  "action":"query",
3  "responseId":"3vy-E9YmX-TIWe0769juD-",
4  "results": {
5    "records":[
6      {"FirstName":"","count":1},
7      {"FirstName":"Admin","count":1},
8      {"FirstName":"Integration","count":1},
9      {"FirstName":"Security","count":1}
10    ]
11  },
12  "query":"q = load \"0Fbxx0000000006CAA/0Fcxx000000001dCAA\";
13           q = group q by 'FirstName';
14           q = foreach q generate 'FirstName' as 'FirstName', count() as 'count';
15           q = limit q 2000;",
16  "responseTime":544
17}

Example Response Body (with metadata)

1{
2  "action":"query",
3  "responseId":"3vy-E9YmX-TIWe0769juD-",
4  "results": {
5    "metadata": {
6      "columns":[
7        {"name":"FirstName", "type":"String"},
8        {"name":"count", "type":"Numeric"}
9      ],
10      "groups":["FirstName"]
11    },
12    "records":[
13      {"FirstName":"","count":1},
14      {"FirstName":"Admin","count":1},
15      {"FirstName":"Integration","count":1},
16      {"FirstName":"Security","count":1}
17    ]
18  },
19  "query":"q = load \"0Fbxx0000000006CAA/0Fcxx000000001dCAA\";
20           q = group q by 'FirstName';
21           q = foreach q generate 'FirstName' as 'FirstName', count() as 'count';
22           q = limit q 2000;",
23  "responseTime":544
24}

Query metadata

Clients can parse the SAQL queries to figure out what dimensions and groups are used, but this can be expensive. So, in most cases, the query response will contain a metadata section, which provides grouping and column information. The metadata section, if present, will be found in the results key in the query response payload. The metadata section is structured with columns and groups keys:

1"metadata":{
2  "columns":[{"name":"dim name", "type":"String"}],
3  "groups":["name","destination"]
4}

The columns key includes the name and type of the projections of the query, and the groups key contains a list of groups used in the query.

• The metadata will be added when the query is successful. If the query fails to run, if there is a syntax error, or if the authorization callback fails then the metadata will not be added to the results.
• The value set in a column name is the alias given to the projection and not the name of the dimension.
• A list of the groups used in the query will be returned in the groups key, provided the query is not considered complex—where the group name returned is nondeterministic (the name of the group is used in multiple streams of the query). This is the case when the query uses cogroup or union. In such cases, the groups key will be empty.

Note

For more information about creating SAQL queries, see Analytics SAQL Referenceand the Analytics SDK Guide.