Debian Codegraph @

valkey/commands/graph/query_result.py

raw
1 import sys
2 from collections import OrderedDict
3
4 # from prettytable import PrettyTable
5 from valkey import ResponseError
6
7 from .edge import Edge
8 from .exceptions import VersionMismatchException
9 from .node import Node
10 from .path import Path
11
12 LABELS_ADDED = "Labels added"
13 LABELS_REMOVED = "Labels removed"
14 NODES_CREATED = "Nodes created"
15 NODES_DELETED = "Nodes deleted"
16 RELATIONSHIPS_DELETED = "Relationships deleted"
17 PROPERTIES_SET = "Properties set"
18 PROPERTIES_REMOVED = "Properties removed"
19 RELATIONSHIPS_CREATED = "Relationships created"
20 INDICES_CREATED = "Indices created"
21 INDICES_DELETED = "Indices deleted"
22 CACHED_EXECUTION = "Cached execution"
23 INTERNAL_EXECUTION_TIME = "internal execution time"
24
25 STATS = [
26 LABELS_ADDED,
27 LABELS_REMOVED,
28 NODES_CREATED,
29 PROPERTIES_SET,
30 PROPERTIES_REMOVED,
31 RELATIONSHIPS_CREATED,
32 NODES_DELETED,
33 RELATIONSHIPS_DELETED,
34 INDICES_CREATED,
35 INDICES_DELETED,
36 CACHED_EXECUTION,
37 INTERNAL_EXECUTION_TIME,
38 ]
39
40
41 def strtobool(value: str) -> bool:
42 """
43 Convert a string representation of truth to True or False.
44 True values are 'y', 'yes', 't', 'true', 'on', and '1'; false values
45 are 'n', 'no', 'f', 'false', 'off', and '0'. Raises ValueError if
46 'value' is anything else.
47 """
48 value = value.lower()
49 if value in ("y", "yes", "t", "true", "on", "1"):
50 return True
51 elif value in ("n", "no", "f", "false", "off", "0"):
52 return False
53 else:
54 raise ValueError(f"invalid truth value {value}")
55
56
57 class ResultSetColumnTypes:
58 COLUMN_UNKNOWN = 0
59 COLUMN_SCALAR = 1
60 COLUMN_NODE = 2 # Unused as of RedisGraph v2.1.0, retained for backwards compatibility. # noqa
61 COLUMN_RELATION = 3 # Unused as of RedisGraph v2.1.0, retained for backwards compatibility. # noqa
62
63
64 class ResultSetScalarTypes:
65 VALUE_UNKNOWN = 0
66 VALUE_NULL = 1
67 VALUE_STRING = 2
68 VALUE_INTEGER = 3
69 VALUE_BOOLEAN = 4
70 VALUE_DOUBLE = 5
71 VALUE_ARRAY = 6
72 VALUE_EDGE = 7
73 VALUE_NODE = 8
74 VALUE_PATH = 9
75 VALUE_MAP = 10
76 VALUE_POINT = 11
77
78
79 class QueryResult:
80 def __init__(self, graph, response, profile=False):
81 """
82 A class that represents a result of the query operation.
83
84 Args:
85
86 graph:
87 The graph on which the query was executed.
88 response:
89 The response from the server.
90 profile:
91 A boolean indicating if the query command was "GRAPH.PROFILE"
92 """
93 self.graph = graph
94 self.header = []
95 self.result_set = []
96
97 # in case of an error an exception will be raised
98 self._check_for_errors(response)
99
100 if len(response) == 1:
101 self.parse_statistics(response[0])
102 elif profile:
103 self.parse_profile(response)
104 else:
105 # start by parsing statistics, matches the one we have
106 self.parse_statistics(response[-1]) # Last element.
107 self.parse_results(response)
108
109 def _check_for_errors(self, response):
110 """
111 Check if the response contains an error.
112 """
113 if isinstance(response[0], ResponseError):
114 error = response[0]
115 if str(error) == "version mismatch":
116 version = response[1]
117 error = VersionMismatchException(version)
118 raise error
119
120 # If we encountered a run-time error, the last response
121 # element will be an exception
122 if isinstance(response[-1], ResponseError):
123 raise response[-1]
124
125 def parse_results(self, raw_result_set):
126 """
127 Parse the query execution result returned from the server.
128 """
129 self.header = self.parse_header(raw_result_set)
130
131 # Empty header.
132 if len(self.header) == 0:
133 return
134
135 self.result_set = self.parse_records(raw_result_set)
136
137 def parse_statistics(self, raw_statistics):
138 """
139 Parse the statistics returned in the response.
140 """
141 self.statistics = {}
142
143 # decode statistics
144 for idx, stat in enumerate(raw_statistics):
145 if isinstance(stat, bytes):
146 raw_statistics[idx] = stat.decode()
147
148 for s in STATS:
149 v = self._get_value(s, raw_statistics)
150 if v is not None:
151 self.statistics[s] = v
152
153 def parse_header(self, raw_result_set):
154 """
155 Parse the header of the result.
156 """
157 # An array of column name/column type pairs.
158 header = raw_result_set[0]
159 return header
160
161 def parse_records(self, raw_result_set):
162 """
163 Parses the result set and returns a list of records.
164 """
165 records = [
166 [
167 self.parse_record_types[self.header[idx][0]](cell)
168 for idx, cell in enumerate(row)
169 ]
170 for row in raw_result_set[1]
171 ]
172
173 return records
174
175 def parse_entity_properties(self, props):
176 """
177 Parse node / edge properties.
178 """
179 # [[name, value type, value] X N]
180 properties = {}
181 for prop in props:
182 prop_name = self.graph.get_property(prop[0])
183 prop_value = self.parse_scalar(prop[1:])
184 properties[prop_name] = prop_value
185
186 return properties
187
188 def parse_string(self, cell):
189 """
190 Parse the cell as a string.
191 """
192 if isinstance(cell, bytes):
193 return cell.decode()
194 elif not isinstance(cell, str):
195 return str(cell)
196 else:
197 return cell
198
199 def parse_node(self, cell):
200 """
201 Parse the cell to a node.
202 """
203 # Node ID (integer),
204 # [label string offset (integer)],
205 # [[name, value type, value] X N]
206
207 node_id = int(cell[0])
208 labels = None
209 if len(cell[1]) > 0:
210 labels = []
211 for inner_label in cell[1]:
212 labels.append(self.graph.get_label(inner_label))
213 properties = self.parse_entity_properties(cell[2])
214 return Node(node_id=node_id, label=labels, properties=properties)
215
216 def parse_edge(self, cell):
217 """
218 Parse the cell to an edge.
219 """
220 # Edge ID (integer),
221 # reltype string offset (integer),
222 # src node ID offset (integer),
223 # dest node ID offset (integer),
224 # [[name, value, value type] X N]
225
226 edge_id = int(cell[0])
227 relation = self.graph.get_relation(cell[1])
228 src_node_id = int(cell[2])
229 dest_node_id = int(cell[3])
230 properties = self.parse_entity_properties(cell[4])
231 return Edge(
232 src_node_id, relation, dest_node_id, edge_id=edge_id, properties=properties
233 )
234
235 def parse_path(self, cell):
236 """
237 Parse the cell to a path.
238 """
239 nodes = self.parse_scalar(cell[0])
240 edges = self.parse_scalar(cell[1])
241 return Path(nodes, edges)
242
243 def parse_map(self, cell):
244 """
245 Parse the cell as a map.
246 """
247 m = OrderedDict()
248 n_entries = len(cell)
249
250 # A map is an array of key value pairs.
251 # 1. key (string)
252 # 2. array: (value type, value)
253 for i in range(0, n_entries, 2):
254 key = self.parse_string(cell[i])
255 m[key] = self.parse_scalar(cell[i + 1])
256
257 return m
258
259 def parse_point(self, cell):
260 """
261 Parse the cell to point.
262 """
263 p = {}
264 # A point is received an array of the form: [latitude, longitude]
265 # It is returned as a map of the form: {"latitude": latitude, "longitude": longitude} # noqa
266 p["latitude"] = float(cell[0])
267 p["longitude"] = float(cell[1])
268 return p
269
270 def parse_null(self, cell):
271 """
272 Parse a null value.
273 """
274 return None
275
276 def parse_integer(self, cell):
277 """
278 Parse the integer value from the cell.
279 """
280 return int(cell)
281
282 def parse_boolean(self, value):
283 """
284 Parse the cell value as a boolean.
285 """
286 value = value.decode() if isinstance(value, bytes) else value
287 try:
288 scalar = strtobool(value)
289 except ValueError:
290 sys.stderr.write("unknown boolean type\n")
291 scalar = None
292 return scalar
293
294 def parse_double(self, cell):
295 """
296 Parse the cell as a double.
297 """
298 return float(cell)
299
300 def parse_array(self, value):
301 """
302 Parse an array of values.
303 """
304 scalar = [self.parse_scalar(value[i]) for i in range(len(value))]
305 return scalar
306
307 def parse_unknown(self, cell):
308 """
309 Parse a cell of unknown type.
310 """
311 sys.stderr.write("Unknown type\n")
312 return None
313
314 def parse_scalar(self, cell):
315 """
316 Parse a scalar value from a cell in the result set.
317 """
318 scalar_type = int(cell[0])
319 value = cell[1]
320 scalar = self.parse_scalar_types[scalar_type](value)
321
322 return scalar
323
324 def parse_profile(self, response):
325 self.result_set = [x[0 : x.index(",")].strip() for x in response]
326
327 def is_empty(self):
328 return len(self.result_set) == 0
329
330 @staticmethod
331 def _get_value(prop, statistics):
332 for stat in statistics:
333 if prop in stat:
334 return float(stat.split(": ")[1].split(" ")[0])
335
336 return None
337
338 def _get_stat(self, stat):
339 return self.statistics[stat] if stat in self.statistics else 0
340
341 @property
342 def labels_added(self):
343 """Returns the number of labels added in the query"""
344 return self._get_stat(LABELS_ADDED)
345
346 @property
347 def labels_removed(self):
348 """Returns the number of labels removed in the query"""
349 return self._get_stat(LABELS_REMOVED)
350
351 @property
352 def nodes_created(self):
353 """Returns the number of nodes created in the query"""
354 return self._get_stat(NODES_CREATED)
355
356 @property
357 def nodes_deleted(self):
358 """Returns the number of nodes deleted in the query"""
359 return self._get_stat(NODES_DELETED)
360
361 @property
362 def properties_set(self):
363 """Returns the number of properties set in the query"""
364 return self._get_stat(PROPERTIES_SET)
365
366 @property
367 def properties_removed(self):
368 """Returns the number of properties removed in the query"""
369 return self._get_stat(PROPERTIES_REMOVED)
370
371 @property
372 def relationships_created(self):
373 """Returns the number of relationships created in the query"""
374 return self._get_stat(RELATIONSHIPS_CREATED)
375
376 @property
377 def relationships_deleted(self):
378 """Returns the number of relationships deleted in the query"""
379 return self._get_stat(RELATIONSHIPS_DELETED)
380
381 @property
382 def indices_created(self):
383 """Returns the number of indices created in the query"""
384 return self._get_stat(INDICES_CREATED)
385
386 @property
387 def indices_deleted(self):
388 """Returns the number of indices deleted in the query"""
389 return self._get_stat(INDICES_DELETED)
390
391 @property
392 def cached_execution(self):
393 """Returns whether or not the query execution plan was cached"""
394 return self._get_stat(CACHED_EXECUTION) == 1
395
396 @property
397 def run_time_ms(self):
398 """Returns the server execution time of the query"""
399 return self._get_stat(INTERNAL_EXECUTION_TIME)
400
401 @property
402 def parse_scalar_types(self):
403 return {
404 ResultSetScalarTypes.VALUE_NULL: self.parse_null,
405 ResultSetScalarTypes.VALUE_STRING: self.parse_string,
406 ResultSetScalarTypes.VALUE_INTEGER: self.parse_integer,
407 ResultSetScalarTypes.VALUE_BOOLEAN: self.parse_boolean,
408 ResultSetScalarTypes.VALUE_DOUBLE: self.parse_double,
409 ResultSetScalarTypes.VALUE_ARRAY: self.parse_array,
410 ResultSetScalarTypes.VALUE_NODE: self.parse_node,
411 ResultSetScalarTypes.VALUE_EDGE: self.parse_edge,
412 ResultSetScalarTypes.VALUE_PATH: self.parse_path,
413 ResultSetScalarTypes.VALUE_MAP: self.parse_map,
414 ResultSetScalarTypes.VALUE_POINT: self.parse_point,
415 ResultSetScalarTypes.VALUE_UNKNOWN: self.parse_unknown,
416 }
417
418 @property
419 def parse_record_types(self):
420 return {
421 ResultSetColumnTypes.COLUMN_SCALAR: self.parse_scalar,
422 ResultSetColumnTypes.COLUMN_NODE: self.parse_node,
423 ResultSetColumnTypes.COLUMN_RELATION: self.parse_edge,
424 ResultSetColumnTypes.COLUMN_UNKNOWN: self.parse_unknown,
425 }
426
427
428 class AsyncQueryResult(QueryResult):
429 """
430 Async version for the QueryResult class - a class that
431 represents a result of the query operation.
432 """
433
434 def __init__(self):
435 """
436 To init the class you must call self.initialize()
437 """
438 pass
439
440 async def initialize(self, graph, response, profile=False):
441 """
442 Initializes the class.
443 Args:
444
445 graph:
446 The graph on which the query was executed.
447 response:
448 The response from the server.
449 profile:
450 A boolean indicating if the query command was "GRAPH.PROFILE"
451 """
452 self.graph = graph
453 self.header = []
454 self.result_set = []
455
456 # in case of an error an exception will be raised
457 self._check_for_errors(response)
458
459 if len(response) == 1:
460 self.parse_statistics(response[0])
461 elif profile:
462 self.parse_profile(response)
463 else:
464 # start by parsing statistics, matches the one we have
465 self.parse_statistics(response[-1]) # Last element.
466 await self.parse_results(response)
467
468 return self
469
470 async def parse_node(self, cell):
471 """
472 Parses a node from the cell.
473 """
474 # Node ID (integer),
475 # [label string offset (integer)],
476 # [[name, value type, value] X N]
477
478 labels = None
479 if len(cell[1]) > 0:
480 labels = []
481 for inner_label in cell[1]:
482 labels.append(await self.graph.get_label(inner_label))
483 properties = await self.parse_entity_properties(cell[2])
484 node_id = int(cell[0])
485 return Node(node_id=node_id, label=labels, properties=properties)
486
487 async def parse_scalar(self, cell):
488 """
489 Parses a scalar value from the server response.
490 """
491 scalar_type = int(cell[0])
492 value = cell[1]
493 try:
494 scalar = await self.parse_scalar_types[scalar_type](value)
495 except TypeError:
496 # Not all of the functions are async
497 scalar = self.parse_scalar_types[scalar_type](value)
498
499 return scalar
500
501 async def parse_records(self, raw_result_set):
502 """
503 Parses the result set and returns a list of records.
504 """
505 records = []
506 for row in raw_result_set[1]:
507 record = [
508 await self.parse_record_types[self.header[idx][0]](cell)
509 for idx, cell in enumerate(row)
510 ]
511 records.append(record)
512
513 return records
514
515 async def parse_results(self, raw_result_set):
516 """
517 Parse the query execution result returned from the server.
518 """
519 self.header = self.parse_header(raw_result_set)
520
521 # Empty header.
522 if len(self.header) == 0:
523 return
524
525 self.result_set = await self.parse_records(raw_result_set)
526
527 async def parse_entity_properties(self, props):
528 """
529 Parse node / edge properties.
530 """
531 # [[name, value type, value] X N]
532 properties = {}
533 for prop in props:
534 prop_name = await self.graph.get_property(prop[0])
535 prop_value = await self.parse_scalar(prop[1:])
536 properties[prop_name] = prop_value
537
538 return properties
539
540 async def parse_edge(self, cell):
541 """
542 Parse the cell to an edge.
543 """
544 # Edge ID (integer),
545 # reltype string offset (integer),
546 # src node ID offset (integer),
547 # dest node ID offset (integer),
548 # [[name, value, value type] X N]
549
550 edge_id = int(cell[0])
551 relation = await self.graph.get_relation(cell[1])
552 src_node_id = int(cell[2])
553 dest_node_id = int(cell[3])
554 properties = await self.parse_entity_properties(cell[4])
555 return Edge(
556 src_node_id, relation, dest_node_id, edge_id=edge_id, properties=properties
557 )
558
559 async def parse_path(self, cell):
560 """
561 Parse the cell to a path.
562 """
563 nodes = await self.parse_scalar(cell[0])
564 edges = await self.parse_scalar(cell[1])
565 return Path(nodes, edges)
566
567 async def parse_map(self, cell):
568 """
569 Parse the cell to a map.
570 """
571 m = OrderedDict()
572 n_entries = len(cell)
573
574 # A map is an array of key value pairs.
575 # 1. key (string)
576 # 2. array: (value type, value)
577 for i in range(0, n_entries, 2):
578 key = self.parse_string(cell[i])
579 m[key] = await self.parse_scalar(cell[i + 1])
580
581 return m
582
583 async def parse_array(self, value):
584 """
585 Parse array value.
586 """
587 scalar = [await self.parse_scalar(value[i]) for i in range(len(value))]
588 return scalar