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
name	String	The query name.	Required	41.0
query	Object (Saql​Query​Input​Representation)	The query, in JSON format.	Either query or query​String is required, but not both.	36.0
query​String	String	The query string.	Either query or query​String is required, but not both.	40.0
timezone	String	The timezone for the query.	Optional	44.0

Example SAQL 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}

Example SQL Request Body

1{
2    SELECT City, sum(Sales) as TotalSales
3    From "em/SuperStoreSales"
4    GROUP BY City
5    LIMIT 10;"
6}

POST Response Body

Description	Filter Group and Version	Available Version
The results of a SAQL or SQL 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

Saql​Query​Input​Representation

Property Name	Type	Description	Required or Optional	Available Version
name	String	The query name.	Required	41.0
query	String	The query string.	Required	40.0
query​Language	Analytics​Query​Language​Enum	The language in which the query in written. Valid values are: SAQL SQL	Required	48.0
timezone	String	The timezone for the query.	Optional	43.0

Example SAQL 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 SAQL 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}

Example SQL Response Body (with metadata)

1"metadata": [
2  "columns": {
3    {
4      "columnLabel": "City",
5      "columnType": "varchar"
6    },
7    {
8      "columnLabel": "TotalSales",
9      "columnType": "numeric"
10    }
11  },
12  "timezone": "America/Los_Angeles", // if present
13  "queryLanguage": "SQL"
14]

The columns key includes the name and type of projections in the query.

Example SQL Response Body - Group By Query With an Aggregation

This query projects the aggregation avg(Sales) as AvgSales, which returns numerical data. In the metadata, the corresponding column type is returned as numeric.

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]

Example SQL Query and Response Body - Extract Date Parts from a Date Field

This example returns the year, month, and day from the CloseDate field as numerical values. The query features the timezone field, which is returned in the metadata as America/Los Angeles.

1SELECT EXTRACT(YEAR FROM CloseDate) as year,
2  EXTRACT(MONTH FROM CloseDate) as month,
3  EXTRACT(DAY FROM CloseDate) as day
4  From "OpportunityFiscalEM"

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]

Example SQL Query and Response Body- Project Date Field of Type DateTime

This query returns date information as timestamps.

1SELECT CloseDate
2  From "OpportunityFiscalEM

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

Query metadata

Clients can parse the 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 Cloud SAQL Reference and the Tableau CRM SDK Guide.