Debian Codegraph @

valkey/commands/search/aggregation.py

raw
1 from typing import List, Union
2
3 FIELDNAME = object()
4
5
6 class Limit:
7 def __init__(self, offset: int = 0, count: int = 0) -> None:
8 self.offset = offset
9 self.count = count
10
11 def build_args(self):
12 if self.count:
13 return ["LIMIT", str(self.offset), str(self.count)]
14 else:
15 return []
16
17
18 class Reducer:
19 """
20 Base reducer object for all reducers.
21
22 See the `valkeyearch.reducers` module for the actual reducers.
23 """
24
25 NAME = None
26
27 def __init__(self, *args: List[str]) -> None:
28 self._args = args
29 self._field = None
30 self._alias = None
31
32 def alias(self, alias: str) -> "Reducer":
33 """
34 Set the alias for this reducer.
35
36 ### Parameters
37
38 - **alias**: The value of the alias for this reducer. If this is the
39 special value `aggregation.FIELDNAME` then this reducer will be
40 aliased using the same name as the field upon which it operates.
41 Note that using `FIELDNAME` is only possible on reducers which
42 operate on a single field value.
43
44 This method returns the `Reducer` object making it suitable for
45 chaining.
46 """
47 if alias is FIELDNAME:
48 if not self._field:
49 raise ValueError("Cannot use FIELDNAME alias with no field")
50 # Chop off initial '@'
51 alias = self._field[1:]
52 self._alias = alias
53 return self
54
55 @property
56 def args(self) -> List[str]:
57 return self._args
58
59
60 class SortDirection:
61 """
62 This special class is used to indicate sort direction.
63 """
64
65 DIRSTRING = None
66
67 def __init__(self, field: str) -> None:
68 self.field = field
69
70
71 class Asc(SortDirection):
72 """
73 Indicate that the given field should be sorted in ascending order
74 """
75
76 DIRSTRING = "ASC"
77
78
79 class Desc(SortDirection):
80 """
81 Indicate that the given field should be sorted in descending order
82 """
83
84 DIRSTRING = "DESC"
85
86
87 class AggregateRequest:
88 """
89 Aggregation request which can be passed to `Client.aggregate`.
90 """
91
92 def __init__(self, query: str = "*") -> None:
93 """
94 Create an aggregation request. This request may then be passed to
95 `client.aggregate()`.
96
97 In order for the request to be usable, it must contain at least one
98 group.
99
100 - **query** Query string for filtering records.
101
102 All member methods (except `build_args()`)
103 return the object itself, making them useful for chaining.
104 """
105 self._query = query
106 self._aggregateplan = []
107 self._loadfields = []
108 self._loadall = False
109 self._max = 0
110 self._with_schema = False
111 self._verbatim = False
112 self._cursor = []
113 self._dialect = None
114
115 def load(self, *fields: List[str]) -> "AggregateRequest":
116 """
117 Indicate the fields to be returned in the response. These fields are
118 returned in addition to any others implicitly specified.
119
120 ### Parameters
121
122 - **fields**: If fields not specified, all the fields will be loaded.
123 Otherwise, fields should be given in the format of `@field`.
124 """
125 if fields:
126 self._loadfields.extend(fields)
127 else:
128 self._loadall = True
129 return self
130
131 def group_by(
132 self, fields: List[str], *reducers: Union[Reducer, List[Reducer]]
133 ) -> "AggregateRequest":
134 """
135 Specify by which fields to group the aggregation.
136
137 ### Parameters
138
139 - **fields**: Fields to group by. This can either be a single string,
140 or a list of strings. both cases, the field should be specified as
141 `@field`.
142 - **reducers**: One or more reducers. Reducers may be found in the
143 `aggregation` module.
144 """
145 fields = [fields] if isinstance(fields, str) else fields
146 reducers = [reducers] if isinstance(reducers, Reducer) else reducers
147
148 ret = ["GROUPBY", str(len(fields)), *fields]
149 for reducer in reducers:
150 ret += ["REDUCE", reducer.NAME, str(len(reducer.args))]
151 ret.extend(reducer.args)
152 if reducer._alias is not None:
153 ret += ["AS", reducer._alias]
154
155 self._aggregateplan.extend(ret)
156 return self
157
158 def apply(self, **kwexpr) -> "AggregateRequest":
159 """
160 Specify one or more projection expressions to add to each result
161
162 ### Parameters
163
164 - **kwexpr**: One or more key-value pairs for a projection. The key is
165 the alias for the projection, and the value is the projection
166 expression itself, for example `apply(square_root="sqrt(@foo)")`
167 """
168 for alias, expr in kwexpr.items():
169 ret = ["APPLY", expr]
170 if alias is not None:
171 ret += ["AS", alias]
172 self._aggregateplan.extend(ret)
173
174 return self
175
176 def limit(self, offset: int, num: int) -> "AggregateRequest":
177 """
178 Sets the limit for the most recent group or query.
179
180 If no group has been defined yet (via `group_by()`) then this sets
181 the limit for the initial pool of results from the query. Otherwise,
182 this limits the number of items operated on from the previous group.
183
184 Setting a limit on the initial search results may be useful when
185 attempting to execute an aggregation on a sample of a large data set.
186
187 ### Parameters
188
189 - **offset**: Result offset from which to begin paging
190 - **num**: Number of results to return
191
192
193 Example of sorting the initial results:
194
195 ```
196 AggregateRequest("@sale_amount:[10000, inf]")\
197 .limit(0, 10)\
198 .group_by("@state", r.count())
199 ```
200
201 Will only group by the states found in the first 10 results of the
202 query `@sale_amount:[10000, inf]`. On the other hand,
203
204 ```
205 AggregateRequest("@sale_amount:[10000, inf]")\
206 .limit(0, 1000)\
207 .group_by("@state", r.count()\
208 .limit(0, 10)
209 ```
210
211 Will group all the results matching the query, but only return the
212 first 10 groups.
213
214 If you only wish to return a *top-N* style query, consider using
215 `sort_by()` instead.
216
217 """
218 _limit = Limit(offset, num)
219 self._aggregateplan.extend(_limit.build_args())
220 return self
221
222 def sort_by(self, *fields: List[str], **kwargs) -> "AggregateRequest":
223 """
224 Indicate how the results should be sorted. This can also be used for
225 *top-N* style queries
226
227 ### Parameters
228
229 - **fields**: The fields by which to sort. This can be either a single
230 field or a list of fields. If you wish to specify order, you can
231 use the `Asc` or `Desc` wrapper classes.
232 - **max**: Maximum number of results to return. This can be
233 used instead of `LIMIT` and is also faster.
234
235
236 Example of sorting by `foo` ascending and `bar` descending:
237
238 ```
239 sort_by(Asc("@foo"), Desc("@bar"))
240 ```
241
242 Return the top 10 customers:
243
244 ```
245 AggregateRequest()\
246 .group_by("@customer", r.sum("@paid").alias(FIELDNAME))\
247 .sort_by(Desc("@paid"), max=10)
248 ```
249 """
250 if isinstance(fields, (str, SortDirection)):
251 fields = [fields]
252
253 fields_args = []
254 for f in fields:
255 if isinstance(f, SortDirection):
256 fields_args += [f.field, f.DIRSTRING]
257 else:
258 fields_args += [f]
259
260 ret = ["SORTBY", str(len(fields_args))]
261 ret.extend(fields_args)
262 max = kwargs.get("max", 0)
263 if max > 0:
264 ret += ["MAX", str(max)]
265
266 self._aggregateplan.extend(ret)
267 return self
268
269 def filter(self, expressions: Union[str, List[str]]) -> "AggregateRequest":
270 """
271 Specify filter for post-query results using predicates relating to
272 values in the result set.
273
274 ### Parameters
275
276 - **fields**: Fields to group by. This can either be a single string,
277 or a list of strings.
278 """
279 if isinstance(expressions, str):
280 expressions = [expressions]
281
282 for expression in expressions:
283 self._aggregateplan.extend(["FILTER", expression])
284
285 return self
286
287 def with_schema(self) -> "AggregateRequest":
288 """
289 If set, the `schema` property will contain a list of `[field, type]`
290 entries in the result object.
291 """
292 self._with_schema = True
293 return self
294
295 def verbatim(self) -> "AggregateRequest":
296 self._verbatim = True
297 return self
298
299 def cursor(self, count: int = 0, max_idle: float = 0.0) -> "AggregateRequest":
300 args = ["WITHCURSOR"]
301 if count:
302 args += ["COUNT", str(count)]
303 if max_idle:
304 args += ["MAXIDLE", str(max_idle * 1000)]
305 self._cursor = args
306 return self
307
308 def build_args(self) -> List[str]:
309 # @foo:bar ...
310 ret = [self._query]
311
312 if self._with_schema:
313 ret.append("WITHSCHEMA")
314
315 if self._verbatim:
316 ret.append("VERBATIM")
317
318 if self._cursor:
319 ret += self._cursor
320
321 if self._loadall:
322 ret.append("LOAD")
323 ret.append("*")
324 elif self._loadfields:
325 ret.append("LOAD")
326 ret.append(str(len(self._loadfields)))
327 ret.extend(self._loadfields)
328
329 if self._dialect:
330 ret.extend(["DIALECT", self._dialect])
331
332 ret.extend(self._aggregateplan)
333
334 return ret
335
336 def dialect(self, dialect: int) -> "AggregateRequest":
337 """
338 Add a dialect field to the aggregate command.
339
340 - **dialect** - dialect version to execute the query under
341 """
342 self._dialect = dialect
343 return self
344
345
346 class Cursor:
347 def __init__(self, cid: int) -> None:
348 self.cid = cid
349 self.max_idle = 0
350 self.count = 0
351
352 def build_args(self):
353 args = [str(self.cid)]
354 if self.max_idle:
355 args += ["MAXIDLE", str(self.max_idle)]
356 if self.count:
357 args += ["COUNT", str(self.count)]
358 return args
359
360
361 class AggregateResult:
362 def __init__(self, rows, cursor: Cursor, schema) -> None:
363 self.rows = rows
364 self.cursor = cursor
365 self.schema = schema
366
367 def __repr__(self) -> (str, str):
368 cid = self.cursor.cid if self.cursor else -1
369 return (
370 f"<{self.__class__.__name__} at 0x{id(self):x} "
371 f"Rows={len(self.rows)}, Cursor={cid}>"
372 )