| 1 |
begin: &begin |
| 2 |
in: query |
| 3 |
description: | |
| 4 |
Begin of the period for which the summary is required. |
| 5 |
type: iso8601 timestamp |
| 6 |
required: false |
| 7 |
|
| 8 |
custom_fields: |
| 9 |
in: query |
| 10 |
description: | |
| 11 |
Optional attributes to customize the summary GET API response. When |
| 12 |
using this parameter, users can create custom reports. The default |
| 13 |
behavior is to list the sum of the quantity and the sum of the price, |
| 14 |
which is projected as ``rate`` field. The default value for the |
| 15 |
``custom_fields`` parameter is ``SUM(qty) AS qty, SUM(price) AS rate``. |
| 16 |
One can customize this field as they wish with InfluxDB queries. The |
| 17 |
following statements ``"select", "from", "drop", "delete", "create", |
| 18 |
"alter", "insert", "update"`` are not allowed though. For instance, if |
| 19 |
one wants to retrieve the quantity field as the last value of the |
| 20 |
quantity, and not the sum (this is quite interesting when generating |
| 21 |
reports for storage values), the user can send the parameter as ``last(qty) |
| 22 |
AS qty, SUM(price) AS rate``. To discover all possible fields that one |
| 23 |
can work with, the user can also use ``*`` as a parameter. |
| 24 |
|
| 25 |
``Currently this feature only works for Influx storage backend.`` It |
| 26 |
(the feature) depends on the storage backend driver to support it. If |
| 27 |
the user tries to set this configuration while using other storage |
| 28 |
backends, it will be ignored. |
| 29 |
type: list of strings |
| 30 |
required: false |
| 31 |
|
| 32 |
end: &end |
| 33 |
in: query |
| 34 |
description: | |
| 35 |
End of the period for which the summary is required. |
| 36 |
type: iso8601 timestamp |
| 37 |
required: false |
| 38 |
|
| 39 |
filters: |
| 40 |
in: query |
| 41 |
description: | |
| 42 |
Optional filters. These filters accept multiple query parameters. To use |
| 43 |
this option with multiple parameters, repeat it as many time as desired in |
| 44 |
the query string. For instance, to restrict the result to only two |
| 45 |
projects, add to the query string |
| 46 |
``filters=project_id:<project_id_one>&filters=project_id:<project_id_two>``. |
| 47 |
Bear in mind that this string must be URL escaped. Therefore, it becomes |
| 48 |
``filters=project_id%3A<project_id_one>&filters=project_id%3A<project_id_two>``. |
| 49 |
type: dict |
| 50 |
required: false |
| 51 |
|
| 52 |
groupby: |
| 53 |
in: query |
| 54 |
description: | |
| 55 |
Optional attributes to group the summary by. The ``groupby`` elements are |
| 56 |
defined in the collector YML settings. Therefore, one can group the |
| 57 |
result using any of the ``groupby`` attributes defined in the collector |
| 58 |
settings of CloudKitty. Besides those attributes, by default, starting |
| 59 |
in CloudKitty ``2024.1`` release, we will have the following new groupby |
| 60 |
options: (i) time: to group data hourly; (ii) time-d: to group data |
| 61 |
by day of the year; (iii) time-w: to group data by week of the year; |
| 62 |
(iv) time-m: to group data by month; and, (v) time-y: to group data by |
| 63 |
year. If you have old data in CloudKitty and you wish to use these |
| 64 |
group by methods, you will need to reprocess the desired timeframe. |
| 65 |
The `groupby` options ``time-d``, ``time-w``, ``time-m``, ``time-y`` are the |
| 66 |
short versions of the following `groupby` options ``day_of_the_year``, |
| 67 |
``week_of_the_year``, ``month``, and ``year`` respectively. |
| 68 |
type: list of strings |
| 69 |
required: false |
| 70 |
|
| 71 |
limit: |
| 72 |
in: query |
| 73 |
description: | |
| 74 |
For pagination. The maximum number of results to return. |
| 75 |
type: int |
| 76 |
required: false |
| 77 |
|
| 78 |
offset: &offset |
| 79 |
in: query |
| 80 |
description: | |
| 81 |
For pagination. The index of the first element that should be returned. |
| 82 |
type: int |
| 83 |
required: false |
| 84 |
|
| 85 |
response_format: |
| 86 |
in: query |
| 87 |
description: | |
| 88 |
Optional attribute to define the object structure used in the response. |
| 89 |
Both responses will be JSON objects. Possible values are ``table`` or |
| 90 |
``object``. |
| 91 |
|
| 92 |
The default value is ``table`` object structure, where one has the |
| 93 |
attributes `total`, which indicates the total number of entries in the |
| 94 |
response; `results`, which is a list of lists, where the nested list |
| 95 |
contains the values of each entry; and, `columns`, which is the attribute |
| 96 |
that describes all of the available columns. Then, each index in this |
| 97 |
list (`columns`) corresponds to the metadata of the values in the `results` |
| 98 |
list. |
| 99 |
|
| 100 |
The structure for the `object` option uses a dictionary. The response still |
| 101 |
has the `total` attribute. However, in the `results` attribute, one will |
| 102 |
find a list of objects, instead of a list of lists of values that we see |
| 103 |
in the `table` option. This facilitates the processing of some use cases. |
| 104 |
type: string |
| 105 |
required: false |
| 106 |
|
| 107 |
begin_resp: |
| 108 |
<<: *begin |
| 109 |
required: true |
| 110 |
description: Begin of the period for the item. |
| 111 |
in: body |
| 112 |
|
| 113 |
end_resp: |
| 114 |
<<: *end |
| 115 |
required: true |
| 116 |
description: End of the period for the item. |
| 117 |
in: body |
| 118 |
|
| 119 |
qty: &qty |
| 120 |
in: body |
| 121 |
description: | |
| 122 |
Qty for the item. |
| 123 |
type: float |
| 124 |
required: true |
| 125 |
|
| 126 |
qty_resp: |
| 127 |
<<: *qty |
| 128 |
required: true |
| 129 |
description: Qty for the item in the specified period. |
| 130 |
in: body |
| 131 |
|
| 132 |
rate: &rate |
| 133 |
in: body |
| 134 |
description: | |
| 135 |
Rate for the item. |
| 136 |
type: float |
| 137 |
required: true |
| 138 |
|
| 139 |
rate_resp: |
| 140 |
<<: *rate |
| 141 |
required: true |
| 142 |
description: Rate for the item in the specified period. |
| 143 |
in: body |