Filtering and Sorting Query Results
You can use parameters to filter and sort your data when you answer questions that your customers ask Alexa. For example, your customer can ask Alexa for all data since May 31, 2018, and you can use filter parameters to return the correct data. When customers ask Alexa a question about their data, Alexa sends a Get
directive to your skill.
Filter parameters
Use filter parameters to return only specific records when you query your data.
Filter parameter payload details
Field | Description | Type | Required |
---|---|---|---|
fieldName |
The name of the field to compare to value . The left side of the comparison equation. |
String | Yes |
operator |
A comparison operator. | String | Yes |
value |
The value to compare to. The right side of the comparison equation. | Object | Yes |
Filter parameter payload format
"filterParameters": [
{
"fieldName": "<field name>",
"operator": "<GT, GTE, LT, LTE, EQ>",
"value": "<comparison value>"
}
]
Comparison operators
You can use the following values for operator
in your filter parameters.
Value | Description |
---|---|
GT | Greater than |
GTE | Greater than or equal to |
LT | Less than |
LTE | Less than or equal to |
EQ | Equal to |
Sort parameters
Use sort parameters to sort your results when you query your data.
Sort parameter payload details
Field | Description | Type | Required |
---|---|---|---|
fieldName |
Sort the results by the values in this field. | String | Yes |
order |
Sort the results in this order. | String | Yes |
Sort parameter payload format
"sortParameters": [
{
"fieldName": "<field name>",
"order": "<DESC, ASC>"
}
]
Sort orders
You can use the following values for order
in your sort parameters.
Value | Description |
---|---|
ASC | Sort in ascending order. |
DESC | Sort in descending order. |
Query examples
The following query gets the most recently recorded data.
Result most recently recorded
"payload": {
"queryParameters": {
"maxResults": "1",
"sortParameters": [
{
"fieldName": "measurementTime",
"order": "DESC"
}
]
}
}
The following query finds all results since May 30, 2018. The query returns the first 10 results, and sorts the results in descending order.
Results since a specific date
"payload": {
"queryParameters": {
"maxResults": "10",
"filterParameters": [
{
"fieldName": "measurementTime",
"operator": "GTE",
"value": "2018-05-30T00:00:00Z"
}
],
"sortParameters": [
{
"fieldName": "measurementTime",
"order": "DESC"
}
]
}
}
The following query finds all results between May 1 and May 31. The query returns the first 50 results, and sorts the results in ascending order.
Results between two dates
"payload": {
"queryParameters": {
"maxResults": "50",
"filterParameters": [
{
"fieldName": "measurementTime",
"comparisonOperator": "GTE",
"value": "2018-05-01T00:00:00Z"
},
{
"fieldName": "measurementTime",
"comparisonOperator": "LT",
"value": "2018-06-01T00:00:00Z"
}
],
"sortParameters": [
{
"fieldName": "measurementTime",
"order": "ASC"
}
]
}
}
Paginating Results
When Alexa sends a Get
request to your skill, the payload contains the field maxResults
. Your skill can return fewer results than maxResults
, but not more. If there are more results, then in the payload of your response you include the field nextToken
. Then Alexa can send a new Get
request that contains the nextToken
to retrieve additional results.
For example, in the following sequence, Alexa requests data with a maximum of three results at a time, and there are eight results total.
1 Initial Alexa Get request
"payload": {
"queryParameters": {
"maxResults": "3",
"filterParameters": [{...}],
"sortParameters": [{...}]
}
}
2 Initial skill response with nextToken
"payload": {
"nextToken": "4",
... result 1 ...
... result 2 ...
... result 3 ...
}
3 Alexa Get request with nextToken
"payload": {
"queryParameters": {
"maxResults": "3",
"nextToken": "4",
"filterParameters": [{...}],
"sortParameters": [{...}]
}
}
4 Skill response
"payload": {
"nextToken": "7",
... result 4 ...
... result 5 ...
... result 6 ...
}
5 Alexa Get request
"payload": {
"queryParameters": {
"maxResults": "3",
"nextToken": "7",
"filterParameters": [{...}],
"sortParameters": [{...}]
}
}
6 Final skill response without nextToken
"payload": {
... result 7 ...
... result 8 ...
}