Grouping¶

Overview¶

The resulting data points can be grouped by one or more tags, a time range, or by value, or by a combination of the three.

Description¶

You can group results by specifying one or more tag names. For example, if you have a customer tag, grouping by customer would create a resulting object for each customer. Multiple tag names can be used to further group the data points. You can set a limit to the number of groups to be returned.

The time grouper groups results by time ranges. For example, you could group data by day of week. Note that the grouper calculates ranges based on the start time of the query. So if you wanted to group by day of week and wanted the first group to be Sunday, then you need to set the query’s start time to be on Sunday.

The value grouper groups by data point values. Values are placed into groups based on a range size. For example, if the range size is 10, then values between 0-9 are placed in the first group, values between 10-19 into the second group, and so forth.

Note: The default group by option selected in the UI is Tags

Usage in API¶

The group_by property in the metric part of the query is an array of one or more groupers. Each grouper has a name (tag, time or value) and then additional properties specific to that grouper.

• Tag group by: tags attribute with a list of tag names

• Time group by: group_count with an integer and range_size with a range object (time value + time unit)

• Value group by: value_size with an integer

...
"group_by": [
    {
        "name": "tag",
        "tags": ["customer", "antenna"]
    }
]
...

Note that grouping by a time range or value can slow down the query. Note also that the group limit is a metric attribute and not a group by attribute.

Response

Each object of the response JSON contains the group_by information you specified in the query as well as a group object. The group object contains the tags names and their corresponding values for the particular grouping. The first group in the results below include data points for the dc1 data center and server1 host.

{
    "queries": [
        {
            "results": [
                {
                    "name": "metric1",
                    "group_by": [
                        {
                            "name": "tag",
                            "tags": ["data_center", "host"],
                            "group": {
                                "data_center": "dc1",
                                "host": "server1"
                            }
                        }
                    ],
                    "tags": {
                        "data_center": ["dc1"],
                        "host": ["server1"]
                    },
                    "values": [
                        [1353222000000, 31],
                        [1364796000000, 723]
                    ]
                },
                {
                    "name": "metric1",
                    "group_by": [
                        {
                            "name": "tag",
                            "tags": ["data_center", "host"],
                            "group": {
                                "data_center": "dc2",
                                "host": "server1"
                            }
                        }
                    ],
                    "tags": {
                        "data_center": ["dc2"],
                        "host": ["server1"]
                    },
                    "values": [
                        [1353222000000, 108],
                        [1364796000000, 1318]
                    ]
                }
            ]
        }
    ]
}