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
Sort parameters
Query examples
Paginating Results

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 ...
}