Debian Codegraph @

api-ref/source/v2/summary/summary_parameters.yml

raw
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