Debian Codegraph @

valkey/commands/graph/commands.py

raw
1 from valkey import DataError
2 from valkey.exceptions import ResponseError
3
4 from .exceptions import VersionMismatchException
5 from .execution_plan import ExecutionPlan
6 from .query_result import AsyncQueryResult, QueryResult
7
8 PROFILE_CMD = "GRAPH.PROFILE"
9 RO_QUERY_CMD = "GRAPH.RO_QUERY"
10 QUERY_CMD = "GRAPH.QUERY"
11 DELETE_CMD = "GRAPH.DELETE"
12 SLOWLOG_CMD = "GRAPH.SLOWLOG"
13 CONFIG_CMD = "GRAPH.CONFIG"
14 LIST_CMD = "GRAPH.LIST"
15 EXPLAIN_CMD = "GRAPH.EXPLAIN"
16
17
18 class GraphCommands:
19 """RedisGraph Commands"""
20
21 def commit(self):
22 """
23 Create entire graph.
24 """
25 if len(self.nodes) == 0 and len(self.edges) == 0:
26 return None
27
28 query = "CREATE "
29 for _, node in self.nodes.items():
30 query += str(node) + ","
31
32 query += ",".join([str(edge) for edge in self.edges])
33
34 # Discard leading comma.
35 if query[-1] == ",":
36 query = query[:-1]
37
38 return self.query(query)
39
40 def query(self, q, params=None, timeout=None, read_only=False, profile=False):
41 """
42 Executes a query against the graph.
43 For more information see `GRAPH.QUERY <https://valkey.io/commands/graph.query>`_. # noqa
44
45 Args:
46
47 q : str
48 The query.
49 params : dict
50 Query parameters.
51 timeout : int
52 Maximum runtime for read queries in milliseconds.
53 read_only : bool
54 Executes a readonly query if set to True.
55 profile : bool
56 Return details on results produced by and time
57 spent in each operation.
58 """
59
60 # maintain original 'q'
61 query = q
62
63 # handle query parameters
64 query = self._build_params_header(params) + query
65
66 # construct query command
67 # ask for compact result-set format
68 # specify known graph version
69 if profile:
70 cmd = PROFILE_CMD
71 else:
72 cmd = RO_QUERY_CMD if read_only else QUERY_CMD
73 command = [cmd, self.name, query, "--compact"]
74
75 # include timeout is specified
76 if isinstance(timeout, int):
77 command.extend(["timeout", timeout])
78 elif timeout is not None:
79 raise Exception("Timeout argument must be a positive integer")
80
81 # issue query
82 try:
83 response = self.execute_command(*command)
84 return QueryResult(self, response, profile)
85 except ResponseError as e:
86 if "unknown command" in str(e) and read_only:
87 # `GRAPH.RO_QUERY` is unavailable in older versions.
88 return self.query(q, params, timeout, read_only=False)
89 raise e
90 except VersionMismatchException as e:
91 # client view over the graph schema is out of sync
92 # set client version and refresh local schema
93 self.version = e.version
94 self._refresh_schema()
95 # re-issue query
96 return self.query(q, params, timeout, read_only)
97
98 def merge(self, pattern):
99 """
100 Merge pattern.
101 """
102 query = "MERGE "
103 query += str(pattern)
104
105 return self.query(query)
106
107 def delete(self):
108 """
109 Deletes graph.
110 For more information see `DELETE <https://valkey.io/commands/graph.delete>`_. # noqa
111 """
112 self._clear_schema()
113 return self.execute_command(DELETE_CMD, self.name)
114
115 # declared here, to override the built in valkey.db.flush()
116 def flush(self):
117 """
118 Commit the graph and reset the edges and the nodes to zero length.
119 """
120 self.commit()
121 self.nodes = {}
122 self.edges = []
123
124 def bulk(self, **kwargs):
125 """Internal only. Not supported."""
126 raise NotImplementedError(
127 "GRAPH.BULK is internal only. "
128 "Use https://github.com/valkeygraph/valkeygraph-bulk-loader."
129 )
130
131 def profile(self, query):
132 """
133 Execute a query and produce an execution plan augmented with metrics
134 for each operation's execution. Return a string representation of a
135 query execution plan, with details on results produced by and time
136 spent in each operation.
137 For more information see `GRAPH.PROFILE <https://valkey.io/commands/graph.profile>`_. # noqa
138 """
139 return self.query(query, profile=True)
140
141 def slowlog(self):
142 """
143 Get a list containing up to 10 of the slowest queries issued
144 against the given graph ID.
145 For more information see `GRAPH.SLOWLOG <https://valkey.io/commands/graph.slowlog>`_. # noqa
146
147 Each item in the list has the following structure:
148 1. A unix timestamp at which the log entry was processed.
149 2. The issued command.
150 3. The issued query.
151 4. The amount of time needed for its execution, in milliseconds.
152 """
153 return self.execute_command(SLOWLOG_CMD, self.name)
154
155 def config(self, name, value=None, set=False):
156 """
157 Retrieve or update a RedisGraph configuration.
158 For more information see `<https://redis.io/commands/graph.config-get/>`__.
159
160 Args:
161
162 name : str
163 The name of the configuration
164 value :
165 The value we want to set (can be used only when `set` is on)
166 set : bool
167 Turn on to set a configuration. Default behavior is get.
168 """
169 params = ["SET" if set else "GET", name]
170 if value is not None:
171 if set:
172 params.append(value)
173 else:
174 raise DataError(
175 "``value`` can be provided only when ``set`` is True"
176 ) # noqa
177 return self.execute_command(CONFIG_CMD, *params)
178
179 def list_keys(self):
180 """
181 Lists all graph keys in the keyspace.
182 For more information see `GRAPH.LIST <https://valkey.io/commands/graph.list>`_. # noqa
183 """
184 return self.execute_command(LIST_CMD)
185
186 def execution_plan(self, query, params=None):
187 """
188 Get the execution plan for given query,
189 GRAPH.EXPLAIN returns an array of operations.
190
191 Args:
192 query: the query that will be executed
193 params: query parameters
194 """
195 query = self._build_params_header(params) + query
196
197 plan = self.execute_command(EXPLAIN_CMD, self.name, query)
198 if isinstance(plan[0], bytes):
199 plan = [b.decode() for b in plan]
200 return "\n".join(plan)
201
202 def explain(self, query, params=None):
203 """
204 Get the execution plan for given query,
205 GRAPH.EXPLAIN returns ExecutionPlan object.
206 For more information see `GRAPH.EXPLAIN <https://valkey.io/commands/graph.explain>`_. # noqa
207
208 Args:
209 query: the query that will be executed
210 params: query parameters
211 """
212 query = self._build_params_header(params) + query
213
214 plan = self.execute_command(EXPLAIN_CMD, self.name, query)
215 return ExecutionPlan(plan)
216
217
218 class AsyncGraphCommands(GraphCommands):
219 async def query(self, q, params=None, timeout=None, read_only=False, profile=False):
220 """
221 Executes a query against the graph.
222 For more information see `GRAPH.QUERY <https://oss.valkey.com/valkeygraph/master/commands/#graphquery>`_. # noqa
223
224 Args:
225
226 q : str
227 The query.
228 params : dict
229 Query parameters.
230 timeout : int
231 Maximum runtime for read queries in milliseconds.
232 read_only : bool
233 Executes a readonly query if set to True.
234 profile : bool
235 Return details on results produced by and time
236 spent in each operation.
237 """
238
239 # maintain original 'q'
240 query = q
241
242 # handle query parameters
243 query = self._build_params_header(params) + query
244
245 # construct query command
246 # ask for compact result-set format
247 # specify known graph version
248 if profile:
249 cmd = PROFILE_CMD
250 else:
251 cmd = RO_QUERY_CMD if read_only else QUERY_CMD
252 command = [cmd, self.name, query, "--compact"]
253
254 # include timeout is specified
255 if isinstance(timeout, int):
256 command.extend(["timeout", timeout])
257 elif timeout is not None:
258 raise Exception("Timeout argument must be a positive integer")
259
260 # issue query
261 try:
262 response = await self.execute_command(*command)
263 return await AsyncQueryResult().initialize(self, response, profile)
264 except ResponseError as e:
265 if "unknown command" in str(e) and read_only:
266 # `GRAPH.RO_QUERY` is unavailable in older versions.
267 return await self.query(q, params, timeout, read_only=False)
268 raise e
269 except VersionMismatchException as e:
270 # client view over the graph schema is out of sync
271 # set client version and refresh local schema
272 self.version = e.version
273 self._refresh_schema()
274 # re-issue query
275 return await self.query(q, params, timeout, read_only)
276
277 async def execution_plan(self, query, params=None):
278 """
279 Get the execution plan for given query,
280 GRAPH.EXPLAIN returns an array of operations.
281
282 Args:
283 query: the query that will be executed
284 params: query parameters
285 """
286 query = self._build_params_header(params) + query
287
288 plan = await self.execute_command(EXPLAIN_CMD, self.name, query)
289 if isinstance(plan[0], bytes):
290 plan = [b.decode() for b in plan]
291 return "\n".join(plan)
292
293 async def explain(self, query, params=None):
294 """
295 Get the execution plan for given query,
296 GRAPH.EXPLAIN returns ExecutionPlan object.
297
298 Args:
299 query: the query that will be executed
300 params: query parameters
301 """
302 query = self._build_params_header(params) + query
303
304 plan = await self.execute_command(EXPLAIN_CMD, self.name, query)
305 return ExecutionPlan(plan)
306
307 async def flush(self):
308 """
309 Commit the graph and reset the edges and the nodes to zero length.
310 """
311 await self.commit()
312 self.nodes = {}
313 self.edges = []