Vielen Dank für deinen Besuch. Diese Seite ist nur in Englisch verfügbar.

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