Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Querying for aggregate data

Amazon IoT provides four APIs (GetStatistics, GetCardinality, GetPercentiles, and GetBucketsAggregation) that allow you to search your device fleet for aggregate data.

GetStatistics

The GetStatistics API and the get-statistics CLI command return the count, average, sum, minimum, maximum, sum of squares, variance, and standard deviation for the specified aggregated field.

The get-statistics CLI command takes the following parameters:

The type of aggregation field can affect the statistics returned.

GetStatistics with string values

If you aggregate on a string field, calling GetStatistics returns a count of devices that have attributes that match the query. For example:

aws iot get-statistics --aggregation-field 'attributes.stringAttribute'
            --query-string '*'

This command returns the number of devices that contain an attribute named stringAttribute:

{
  "statistics": {
    "count": 3
  }
}

GetStatistics with Boolean values

When you call GetStatistics with a Boolean aggregation field:

GetStatistics with numerical values

When you call GetStatistics and specify an aggregation field of type Number, GetStatistics returns the following values:

The following example shows how to call get-statistics with a numerical custom field.

aws iot get-statistics --aggregation-field 'attributes.numericAttribute2'
            --query-string '*'

{
  "statistics": {
    "count": 3,
    "average": 33.333333333333336,
    "sum": 100.0,
    "minimum": -125.0,
    "maximum": 150.0,
    "sumOfSquares": 43750.0,
    "variance": 13472.22222222222,
    "stdDeviation": 116.06990230986766
  }
}

For numerical aggregation fields, if the field values exceed the maximum double value, the statistics values are empty.

GetCardinality

The GetCardinality API and the get-cardinality CLI command return the approximate count of unique values that match the query. For example, you might want to find the number of devices with battery levels at less than 50 percent:

aws iot get-cardinality --index-name AWS_Things --query-string "batterylevel
          > 50" --aggregation-field "shadow.reported.batterylevel"

This command returns the number of things with battery levels at more than 50 percent:

{
    "cardinality": 100
}

cardinality is always returned by get-cardinality even if there are no matching fields. For example:

aws iot get-cardinality --query-string "thingName:Non-existent*"
          --aggregation-field "attributes.customField_STR"

{
    "cardinality": 0
}

The get-cardinality CLI command takes the following parameters:

GetPercentiles

The GetPercentiles API and the get-percentiles CLI command groups the aggregated values that match the query into percentile groupings. The default percentile groupings are: 1,5,25,50,75,95,99, although you can specify your own when you call GetPercentiles. This function returns a value for each percentile group specified (or the default percentile groupings). The percentile group "1" contains the aggregated field value that occurs in approximately one percent of the values that match the query. The percentile group "5" contains the aggregated field value that occurs in approximately five percent of the values that match the query, and so on. The result is an approximation, the more values that match the query, the more accurate the percentile values.

The following example shows how to call the get-percentiles CLI command.

aws iot get-percentiles --query-string "thingName:*" --aggregation-field
          "attributes.customField_NUM" --percents 10 20 30 40 50 60 70 80 90 99

{
    "percentiles": [
        {
            "value": 3.0,
            "percent": 80.0
        },
        {
            "value": 2.5999999999999996,
            "percent": 70.0
        },
        {
            "value": 3.0,
            "percent": 90.0
        },
        {
            "value": 2.0,
            "percent": 50.0
        },
        {
            "value": 2.0,
            "percent": 60.0
        },
        {
            "value": 1.0,
            "percent": 10.0
        },
        {
            "value": 2.0,
            "percent": 40.0
        },
        {
            "value": 1.0,
            "percent": 20.0
        },
        {
            "value": 1.4,
            "percent": 30.0
        },
        {
            "value": 3.0,
            "percent": 99.0
        }
    ]
}

The following command shows the output returned from get-percentiles when there are no matching documents.

aws iot get-percentiles --query-string "thingName:Non-existent*"
          --aggregation-field "attributes.customField_NUM"

{
    "percentiles": []
}

The get-percentile CLI command takes the following parameters:

GetBucketsAggregation

The GetBucketsAggregation API and the get-buckets-aggregation CLI command return a list of buckets and the total number of things that fit the query string criteria.

The following example shows how to call the get-buckets-aggregation CLI command.

aws iot get-buckets-aggregation --query-string '*' --index-name AWS_Things --aggregation-field 'shadow.reported.batterylevelpercent' --buckets-aggregation-type 'termsAggregation={maxBuckets=5}'

This command returns the following:

{
    "totalCount": 20,
    "buckets": [
        {
            "keyValue": "100",
            "count": 12
        },
        {
            "keyValue": "90",
            "count": 5
        },
        {
            "keyValue": "75",
            "count": 3
        }
    ]
}

The get-buckets-aggregation CLI command takes the following parameters:

Authorization

You can specify the thing groups index as a resource ARN in an Amazon IoT policy action, as follows.