From 39b99faf81ddcaaaf2491fda697330e9e8cb282a Mon Sep 17 00:00:00 2001 From: Terri Yu Date: Thu, 12 Sep 2013 03:03:20 +0000 Subject: [PATCH] Add group by statistics examples in API v2 docs Fixes bug #1224222 There are currently no examples in the API v2 documentation that show the user how to request statistics with the groupby parameter. This patch adds examples and explains that period aggregation is applied before group by aggregation. Change-Id: I5561c4397d124e2976771b3a3b14d666a611351e --- doc/source/webapi/v2.rst | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/doc/source/webapi/v2.rst b/doc/source/webapi/v2.rst index 6a9a325f1..cf6b21816 100644 --- a/doc/source/webapi/v2.rst +++ b/doc/source/webapi/v2.rst @@ -231,6 +231,39 @@ durations:: "value": "64da755c-9120-4236-bee1-54acafe24980"}] period: 600 +The *period* parameter aggregates by time range. You can also aggregate by +field using the *groupby* parameter. Currently, the *user_id*, *resource_id*, +*project_id*, and *source* fields are supported. Below is an example that uses +a query filter and group by aggregation on *project_id* and *resource_id*:: + + GET /v2/meters/instance/statistics + q: [{"field": "user_id", + "op": "eq", + "value": "user-2"}, + {"field": "source", + "op": "eq", + "value": "source-1"}] + groupby: ["project_id", "resource_id"] + +The statistics will be returned in a list, and each entry of the list will be +labeled with the group name. For the previous example, the first entry might +have *project_id* be "project-1" and *resource_id* be "resource-1", the second +entry have *project_id* be "project-1" and *resource_id* be "resource-2", and +so on. + +You can request both period and group by aggregation in the same query:: + + GET /v2/meters/instance/statistics + q: [{"field": "source", + "op": "eq", + "value": "source-1"}] + groupby: ["project_id"] + period: 7200 + +Note that period aggregation is applied first, followed by group by +aggregation. Order matters because the period aggregation determines the time +ranges for the statistics. + If you want to retrieve all the instances (not the list of samples, but the resource itself) that have been run during this month for a given project, you should ask the resource endpoint for the list of resources (all types: