Debian Codegraph @

valkey/commands/search/commands.py

raw
1 import itertools
2 import time
3 from typing import Dict, List, Optional, Union
4
5 from valkey.client import Pipeline
6 from valkey.utils import deprecated_function
7
8 from ..helpers import get_protocol_version, parse_to_dict
9 from ._util import to_string
10 from .aggregation import AggregateRequest, AggregateResult, Cursor
11 from .document import Document
12 from .query import Query
13 from .result import Result
14 from .suggestion import SuggestionParser
15
16 NUMERIC = "NUMERIC"
17
18 CREATE_CMD = "FT.CREATE"
19 ALTER_CMD = "FT.ALTER"
20 SEARCH_CMD = "FT.SEARCH"
21 ADD_CMD = "FT.ADD"
22 ADDHASH_CMD = "FT.ADDHASH"
23 DROP_CMD = "FT.DROP"
24 DROPINDEX_CMD = "FT.DROPINDEX"
25 EXPLAIN_CMD = "FT.EXPLAIN"
26 EXPLAINCLI_CMD = "FT.EXPLAINCLI"
27 DEL_CMD = "FT.DEL"
28 AGGREGATE_CMD = "FT.AGGREGATE"
29 PROFILE_CMD = "FT.PROFILE"
30 CURSOR_CMD = "FT.CURSOR"
31 SPELLCHECK_CMD = "FT.SPELLCHECK"
32 DICT_ADD_CMD = "FT.DICTADD"
33 DICT_DEL_CMD = "FT.DICTDEL"
34 DICT_DUMP_CMD = "FT.DICTDUMP"
35 GET_CMD = "FT.GET"
36 MGET_CMD = "FT.MGET"
37 CONFIG_CMD = "FT.CONFIG"
38 TAGVALS_CMD = "FT.TAGVALS"
39 ALIAS_ADD_CMD = "FT.ALIASADD"
40 ALIAS_UPDATE_CMD = "FT.ALIASUPDATE"
41 ALIAS_DEL_CMD = "FT.ALIASDEL"
42 INFO_CMD = "FT.INFO"
43 SUGADD_COMMAND = "FT.SUGADD"
44 SUGDEL_COMMAND = "FT.SUGDEL"
45 SUGLEN_COMMAND = "FT.SUGLEN"
46 SUGGET_COMMAND = "FT.SUGGET"
47 SYNUPDATE_CMD = "FT.SYNUPDATE"
48 SYNDUMP_CMD = "FT.SYNDUMP"
49
50 NOOFFSETS = "NOOFFSETS"
51 NOFIELDS = "NOFIELDS"
52 NOHL = "NOHL"
53 NOFREQS = "NOFREQS"
54 MAXTEXTFIELDS = "MAXTEXTFIELDS"
55 TEMPORARY = "TEMPORARY"
56 STOPWORDS = "STOPWORDS"
57 SKIPINITIALSCAN = "SKIPINITIALSCAN"
58 WITHSCORES = "WITHSCORES"
59 FUZZY = "FUZZY"
60 WITHPAYLOADS = "WITHPAYLOADS"
61
62
63 class SearchCommands:
64 """Search commands."""
65
66 def _parse_results(self, cmd, res, **kwargs):
67 if get_protocol_version(self.client) in ["3", 3]:
68 return res
69 else:
70 return self._RESP2_MODULE_CALLBACKS[cmd](res, **kwargs)
71
72 def _parse_info(self, res, **kwargs):
73 it = map(to_string, res)
74 return dict(zip(it, it))
75
76 def _parse_search(self, res, **kwargs):
77 return Result(
78 res,
79 not kwargs["query"]._no_content,
80 duration=kwargs["duration"],
81 has_payload=kwargs["query"]._with_payloads,
82 with_scores=kwargs["query"]._with_scores,
83 )
84
85 def _parse_aggregate(self, res, **kwargs):
86 return self._get_aggregate_result(res, kwargs["query"], kwargs["has_cursor"])
87
88 def _parse_profile(self, res, **kwargs):
89 query = kwargs["query"]
90 if isinstance(query, AggregateRequest):
91 result = self._get_aggregate_result(res[0], query, query._cursor)
92 else:
93 result = Result(
94 res[0],
95 not query._no_content,
96 duration=kwargs["duration"],
97 has_payload=query._with_payloads,
98 with_scores=query._with_scores,
99 )
100
101 return result, parse_to_dict(res[1])
102
103 def _parse_spellcheck(self, res, **kwargs):
104 corrections = {}
105 if res == 0:
106 return corrections
107
108 for _correction in res:
109 if isinstance(_correction, int) and _correction == 0:
110 continue
111
112 if len(_correction) != 3:
113 continue
114 if not _correction[2]:
115 continue
116 if not _correction[2][0]:
117 continue
118
119 # For spellcheck output
120 # 1) 1) "TERM"
121 # 2) "{term1}"
122 # 3) 1) 1) "{score1}"
123 # 2) "{suggestion1}"
124 # 2) 1) "{score2}"
125 # 2) "{suggestion2}"
126 #
127 # Following dictionary will be made
128 # corrections = {
129 # '{term1}': [
130 # {'score': '{score1}', 'suggestion': '{suggestion1}'},
131 # {'score': '{score2}', 'suggestion': '{suggestion2}'}
132 # ]
133 # }
134 corrections[_correction[1]] = [
135 {"score": _item[0], "suggestion": _item[1]} for _item in _correction[2]
136 ]
137
138 return corrections
139
140 def _parse_config_get(self, res, **kwargs):
141 return {kvs[0]: kvs[1] for kvs in res} if res else {}
142
143 def _parse_syndump(self, res, **kwargs):
144 return {res[i]: res[i + 1] for i in range(0, len(res), 2)}
145
146 def batch_indexer(self, chunk_size=100):
147 """
148 Create a new batch indexer from the client with a given chunk size
149 """
150 return self.BatchIndexer(self, chunk_size=chunk_size)
151
152 def create_index(
153 self,
154 fields,
155 no_term_offsets=False,
156 no_field_flags=False,
157 stopwords=None,
158 definition=None,
159 max_text_fields=False,
160 temporary=None,
161 no_highlight=False,
162 no_term_frequencies=False,
163 skip_initial_scan=False,
164 ):
165 """
166 Create the search index. The index must not already exist.
167
168 ### Parameters:
169
170 - **fields**: a list of TextField or NumericField objects
171 - **no_term_offsets**: If true, we will not save term offsets in
172 the index
173 - **no_field_flags**: If true, we will not save field flags that
174 allow searching in specific fields
175 - **stopwords**: If not None, we create the index with this custom
176 stopword list. The list can be empty
177 - **max_text_fields**: If true, we will encode indexes as if there
178 were more than 32 text fields which allows you to add additional
179 fields (beyond 32).
180 - **temporary**: Create a lightweight temporary index which will
181 expire after the specified period of inactivity (in seconds). The
182 internal idle timer is reset whenever the index is searched or added to.
183 - **no_highlight**: If true, disabling highlighting support.
184 Also implied by no_term_offsets.
185 - **no_term_frequencies**: If true, we avoid saving the term frequencies
186 in the index.
187 - **skip_initial_scan**: If true, we do not scan and index.
188
189 For more information see `FT.CREATE <https://valkey.io/commands/ft.create>`_.
190 """ # noqa
191
192 args = [CREATE_CMD, self.index_name]
193 if definition is not None:
194 args += definition.args
195 if max_text_fields:
196 args.append(MAXTEXTFIELDS)
197 if temporary is not None and isinstance(temporary, int):
198 args.append(TEMPORARY)
199 args.append(temporary)
200 if no_term_offsets:
201 args.append(NOOFFSETS)
202 if no_highlight:
203 args.append(NOHL)
204 if no_field_flags:
205 args.append(NOFIELDS)
206 if no_term_frequencies:
207 args.append(NOFREQS)
208 if skip_initial_scan:
209 args.append(SKIPINITIALSCAN)
210 if stopwords is not None and isinstance(stopwords, (list, tuple, set)):
211 args += [STOPWORDS, len(stopwords)]
212 if len(stopwords) > 0:
213 args += list(stopwords)
214
215 args.append("SCHEMA")
216 try:
217 args += list(itertools.chain(*(f.valkey_args() for f in fields)))
218 except TypeError:
219 args += fields.valkey_args()
220
221 return self.execute_command(*args)
222
223 def alter_schema_add(self, fields: List[str]):
224 """
225 Alter the existing search index by adding new fields. The index
226 must already exist.
227
228 ### Parameters:
229
230 - **fields**: a list of Field objects to add for the index
231
232 For more information see `FT.ALTER <https://valkey.io/commands/ft.alter>`_.
233 """ # noqa
234
235 args = [ALTER_CMD, self.index_name, "SCHEMA", "ADD"]
236 try:
237 args += list(itertools.chain(*(f.valkey_args() for f in fields)))
238 except TypeError:
239 args += fields.valkey_args()
240
241 return self.execute_command(*args)
242
243 def dropindex(self, delete_documents: bool = False):
244 """
245 Drop the index if it exists.
246 Replaced `drop_index` in RediSearch 2.0.
247 Default behavior was changed to not delete the indexed documents.
248
249 ### Parameters:
250
251 - **delete_documents**: If `True`, all documents will be deleted.
252
253 For more information see `FT.DROPINDEX <https://valkey.io/commands/ft.dropindex>`_.
254 """ # noqa
255 delete_str = "DD" if delete_documents else ""
256 return self.execute_command(DROPINDEX_CMD, self.index_name, delete_str)
257
258 def _add_document(
259 self,
260 doc_id,
261 conn=None,
262 nosave=False,
263 score=1.0,
264 payload=None,
265 replace=False,
266 partial=False,
267 language=None,
268 no_create=False,
269 **fields,
270 ):
271 """
272 Internal add_document used for both batch and single doc indexing
273 """
274
275 if partial or no_create:
276 replace = True
277
278 args = [ADD_CMD, self.index_name, doc_id, score]
279 if nosave:
280 args.append("NOSAVE")
281 if payload is not None:
282 args.append("PAYLOAD")
283 args.append(payload)
284 if replace:
285 args.append("REPLACE")
286 if partial:
287 args.append("PARTIAL")
288 if no_create:
289 args.append("NOCREATE")
290 if language:
291 args += ["LANGUAGE", language]
292 args.append("FIELDS")
293 args += list(itertools.chain(*fields.items()))
294
295 if conn is not None:
296 return conn.execute_command(*args)
297
298 return self.execute_command(*args)
299
300 def _add_document_hash(
301 self, doc_id, conn=None, score=1.0, language=None, replace=False
302 ):
303 """
304 Internal add_document_hash used for both batch and single doc indexing
305 """
306
307 args = [ADDHASH_CMD, self.index_name, doc_id, score]
308
309 if replace:
310 args.append("REPLACE")
311
312 if language:
313 args += ["LANGUAGE", language]
314
315 if conn is not None:
316 return conn.execute_command(*args)
317
318 return self.execute_command(*args)
319
320 @deprecated_function(
321 version="2.0.0", reason="deprecated since redisearch 2.0, call hset instead"
322 )
323 def add_document(
324 self,
325 doc_id: str,
326 nosave: bool = False,
327 score: float = 1.0,
328 payload: bool = None,
329 replace: bool = False,
330 partial: bool = False,
331 language: Optional[str] = None,
332 no_create: str = False,
333 **fields: List[str],
334 ):
335 """
336 Add a single document to the index.
337
338 Args:
339
340 doc_id: the id of the saved document.
341 nosave: if set to true, we just index the document, and don't
342 save a copy of it. This means that searches will just
343 return ids.
344 score: the document ranking, between 0.0 and 1.0
345 payload: optional inner-index payload we can save for fast
346 access in scoring functions
347 replace: if True, and the document already is in the index,
348 we perform an update and reindex the document
349 partial: if True, the fields specified will be added to the
350 existing document.
351 This has the added benefit that any fields specified
352 with `no_index`
353 will not be reindexed again. Implies `replace`
354 language: Specify the language used for document tokenization.
355 no_create: if True, the document is only updated and reindexed
356 if it already exists.
357 If the document does not exist, an error will be
358 returned. Implies `replace`
359 fields: kwargs dictionary of the document fields to be saved
360 and/or indexed.
361 NOTE: Geo points should be encoded as strings of "lon,lat"
362 """ # noqa
363 return self._add_document(
364 doc_id,
365 conn=None,
366 nosave=nosave,
367 score=score,
368 payload=payload,
369 replace=replace,
370 partial=partial,
371 language=language,
372 no_create=no_create,
373 **fields,
374 )
375
376 @deprecated_function(
377 version="2.0.0", reason="deprecated since valkeyearch 2.0, call hset instead"
378 )
379 def add_document_hash(self, doc_id, score=1.0, language=None, replace=False):
380 """
381 Add a hash document to the index.
382
383 ### Parameters
384
385 - **doc_id**: the document's id. This has to be an existing HASH key
386 in Valkey that will hold the fields the index needs.
387 - **score**: the document ranking, between 0.0 and 1.0
388 - **replace**: if True, and the document already is in the index, we
389 perform an update and reindex the document
390 - **language**: Specify the language used for document tokenization.
391 """ # noqa
392 return self._add_document_hash(
393 doc_id, conn=None, score=score, language=language, replace=replace
394 )
395
396 def delete_document(self, doc_id, conn=None, delete_actual_document=False):
397 """
398 Delete a document from index
399 Returns 1 if the document was deleted, 0 if not
400
401 ### Parameters
402
403 - **delete_actual_document**: if set to True, RediSearch also delete
404 the actual document if it is in the index
405 """ # noqa
406 args = [DEL_CMD, self.index_name, doc_id]
407 if delete_actual_document:
408 args.append("DD")
409
410 if conn is not None:
411 return conn.execute_command(*args)
412
413 return self.execute_command(*args)
414
415 def load_document(self, id):
416 """
417 Load a single document by id
418 """
419 fields = self.client.hgetall(id)
420 f2 = {to_string(k): to_string(v) for k, v in fields.items()}
421 fields = f2
422
423 try:
424 del fields["id"]
425 except KeyError:
426 pass
427
428 return Document(id=id, **fields)
429
430 def get(self, *ids):
431 """
432 Returns the full contents of multiple documents.
433
434 ### Parameters
435
436 - **ids**: the ids of the saved documents.
437
438 """
439
440 return self.execute_command(MGET_CMD, self.index_name, *ids)
441
442 def info(self):
443 """
444 Get info an stats about the the current index, including the number of
445 documents, memory consumption, etc
446
447 For more information see `FT.INFO <https://valkey.io/commands/ft.info>`_.
448 """
449
450 res = self.execute_command(INFO_CMD, self.index_name)
451 return self._parse_results(INFO_CMD, res)
452
453 def get_params_args(
454 self, query_params: Union[Dict[str, Union[str, int, float, bytes]], None]
455 ):
456 if query_params is None:
457 return []
458 args = []
459 if len(query_params) > 0:
460 args.append("params")
461 args.append(len(query_params) * 2)
462 for key, value in query_params.items():
463 args.append(key)
464 args.append(value)
465 return args
466
467 def _mk_query_args(
468 self, query, query_params: Union[Dict[str, Union[str, int, float, bytes]], None]
469 ):
470 args = [self.index_name]
471
472 if isinstance(query, str):
473 # convert the query from a text to a query object
474 query = Query(query)
475 if not isinstance(query, Query):
476 raise ValueError(f"Bad query type {type(query)}")
477
478 args += query.get_args()
479 args += self.get_params_args(query_params)
480
481 return args, query
482
483 def search(
484 self,
485 query: Union[str, Query],
486 query_params: Union[Dict[str, Union[str, int, float, bytes]], None] = None,
487 ):
488 """
489 Search the index for a given query, and return a result of documents
490
491 ### Parameters
492
493 - **query**: the search query. Either a text for simple queries with
494 default parameters, or a Query object for complex queries.
495 See RediSearch's documentation on query format
496
497 For more information see `FT.SEARCH <https://valkey.io/commands/ft.search>`_.
498 """ # noqa
499 args, query = self._mk_query_args(query, query_params=query_params)
500 st = time.time()
501 res = self.execute_command(SEARCH_CMD, *args)
502
503 if isinstance(res, Pipeline):
504 return res
505
506 return self._parse_results(
507 SEARCH_CMD, res, query=query, duration=(time.time() - st) * 1000.0
508 )
509
510 def explain(
511 self,
512 query: Union[str, Query],
513 query_params: Dict[str, Union[str, int, float]] = None,
514 ):
515 """Returns the execution plan for a complex query.
516
517 For more information see `FT.EXPLAIN <https://valkey.io/commands/ft.explain>`_.
518 """ # noqa
519 args, query_text = self._mk_query_args(query, query_params=query_params)
520 return self.execute_command(EXPLAIN_CMD, *args)
521
522 def explain_cli(self, query: Union[str, Query]): # noqa
523 raise NotImplementedError("EXPLAINCLI will not be implemented.")
524
525 def aggregate(
526 self,
527 query: Union[str, Query],
528 query_params: Dict[str, Union[str, int, float]] = None,
529 ):
530 """
531 Issue an aggregation query.
532
533 ### Parameters
534
535 **query**: This can be either an `AggregateRequest`, or a `Cursor`
536
537 An `AggregateResult` object is returned. You can access the rows from
538 its `rows` property, which will always yield the rows of the result.
539
540 For more information see `FT.AGGREGATE <https://valkey.io/commands/ft.aggregate>`_.
541 """ # noqa
542 if isinstance(query, AggregateRequest):
543 has_cursor = bool(query._cursor)
544 cmd = [AGGREGATE_CMD, self.index_name] + query.build_args()
545 elif isinstance(query, Cursor):
546 has_cursor = True
547 cmd = [CURSOR_CMD, "READ", self.index_name] + query.build_args()
548 else:
549 raise ValueError("Bad query", query)
550 cmd += self.get_params_args(query_params)
551
552 raw = self.execute_command(*cmd)
553 return self._parse_results(
554 AGGREGATE_CMD, raw, query=query, has_cursor=has_cursor
555 )
556
557 def _get_aggregate_result(
558 self, raw: List, query: Union[str, Query, AggregateRequest], has_cursor: bool
559 ):
560 if has_cursor:
561 if isinstance(query, Cursor):
562 query.cid = raw[1]
563 cursor = query
564 else:
565 cursor = Cursor(raw[1])
566 raw = raw[0]
567 else:
568 cursor = None
569
570 if isinstance(query, AggregateRequest) and query._with_schema:
571 schema = raw[0]
572 rows = raw[2:]
573 else:
574 schema = None
575 rows = raw[1:]
576
577 return AggregateResult(rows, cursor, schema)
578
579 def profile(
580 self,
581 query: Union[str, Query, AggregateRequest],
582 limited: bool = False,
583 query_params: Optional[Dict[str, Union[str, int, float]]] = None,
584 ):
585 """
586 Performs a search or aggregate command and collects performance
587 information.
588
589 ### Parameters
590
591 **query**: This can be either an `AggregateRequest`, `Query` or string.
592 **limited**: If set to True, removes details of reader iterator.
593 **query_params**: Define one or more value parameters.
594 Each parameter has a name and a value.
595
596 """
597 st = time.time()
598 cmd = [PROFILE_CMD, self.index_name, ""]
599 if limited:
600 cmd.append("LIMITED")
601 cmd.append("QUERY")
602
603 if isinstance(query, AggregateRequest):
604 cmd[2] = "AGGREGATE"
605 cmd += query.build_args()
606 elif isinstance(query, Query):
607 cmd[2] = "SEARCH"
608 cmd += query.get_args()
609 cmd += self.get_params_args(query_params)
610 else:
611 raise ValueError("Must provide AggregateRequest object or Query object.")
612
613 res = self.execute_command(*cmd)
614
615 return self._parse_results(
616 PROFILE_CMD, res, query=query, duration=(time.time() - st) * 1000.0
617 )
618
619 def spellcheck(self, query, distance=None, include=None, exclude=None):
620 """
621 Issue a spellcheck query
622
623 Args:
624
625 query: search query.
626 distance: the maximal Levenshtein distance for spelling
627 suggestions (default: 1, max: 4).
628 include: specifies an inclusion custom dictionary.
629 exclude: specifies an exclusion custom dictionary.
630
631 For more information see `FT.SPELLCHECK <https://valkey.io/commands/ft.spellcheck>`_.
632 """ # noqa
633 cmd = [SPELLCHECK_CMD, self.index_name, query]
634 if distance:
635 cmd.extend(["DISTANCE", distance])
636
637 if include:
638 cmd.extend(["TERMS", "INCLUDE", include])
639
640 if exclude:
641 cmd.extend(["TERMS", "EXCLUDE", exclude])
642
643 res = self.execute_command(*cmd)
644
645 return self._parse_results(SPELLCHECK_CMD, res)
646
647 def dict_add(self, name: str, *terms: List[str]):
648 """Adds terms to a dictionary.
649
650 ### Parameters
651
652 - **name**: Dictionary name.
653 - **terms**: List of items for adding to the dictionary.
654
655 For more information see `FT.DICTADD <https://valkey.io/commands/ft.dictadd>`_.
656 """ # noqa
657 cmd = [DICT_ADD_CMD, name]
658 cmd.extend(terms)
659 return self.execute_command(*cmd)
660
661 def dict_del(self, name: str, *terms: List[str]):
662 """Deletes terms from a dictionary.
663
664 ### Parameters
665
666 - **name**: Dictionary name.
667 - **terms**: List of items for removing from the dictionary.
668
669 For more information see `FT.DICTDEL <https://valkey.io/commands/ft.dictdel>`_.
670 """ # noqa
671 cmd = [DICT_DEL_CMD, name]
672 cmd.extend(terms)
673 return self.execute_command(*cmd)
674
675 def dict_dump(self, name: str):
676 """Dumps all terms in the given dictionary.
677
678 ### Parameters
679
680 - **name**: Dictionary name.
681
682 For more information see `FT.DICTDUMP <https://valkey.io/commands/ft.dictdump>`_.
683 """ # noqa
684 cmd = [DICT_DUMP_CMD, name]
685 return self.execute_command(*cmd)
686
687 def config_set(self, option: str, value: str) -> bool:
688 """Set runtime configuration option.
689
690 ### Parameters
691
692 - **option**: the name of the configuration option.
693 - **value**: a value for the configuration option.
694
695 For more information see `FT.CONFIG SET <https://valkey.io/commands/ft.config-set>`_.
696 """ # noqa
697 cmd = [CONFIG_CMD, "SET", option, value]
698 raw = self.execute_command(*cmd)
699 return raw == "OK"
700
701 def config_get(self, option: str) -> str:
702 """Get runtime configuration option value.
703
704 ### Parameters
705
706 - **option**: the name of the configuration option.
707
708 For more information see `FT.CONFIG GET <https://valkey.io/commands/ft.config-get>`_.
709 """ # noqa
710 cmd = [CONFIG_CMD, "GET", option]
711 res = self.execute_command(*cmd)
712 return self._parse_results(CONFIG_CMD, res)
713
714 def tagvals(self, tagfield: str):
715 """
716 Return a list of all possible tag values
717
718 ### Parameters
719
720 - **tagfield**: Tag field name
721
722 For more information see `FT.TAGVALS <https://valkey.io/commands/ft.tagvals>`_.
723 """ # noqa
724
725 return self.execute_command(TAGVALS_CMD, self.index_name, tagfield)
726
727 def aliasadd(self, alias: str):
728 """
729 Alias a search index - will fail if alias already exists
730
731 ### Parameters
732
733 - **alias**: Name of the alias to create
734
735 For more information see `FT.ALIASADD <https://valkey.io/commands/ft.aliasadd>`_.
736 """ # noqa
737
738 return self.execute_command(ALIAS_ADD_CMD, alias, self.index_name)
739
740 def aliasupdate(self, alias: str):
741 """
742 Updates an alias - will fail if alias does not already exist
743
744 ### Parameters
745
746 - **alias**: Name of the alias to create
747
748 For more information see `FT.ALIASUPDATE <https://valkey.io/commands/ft.aliasupdate>`_.
749 """ # noqa
750
751 return self.execute_command(ALIAS_UPDATE_CMD, alias, self.index_name)
752
753 def aliasdel(self, alias: str):
754 """
755 Removes an alias to a search index
756
757 ### Parameters
758
759 - **alias**: Name of the alias to delete
760
761 For more information see `FT.ALIASDEL <https://valkey.io/commands/ft.aliasdel>`_.
762 """ # noqa
763 return self.execute_command(ALIAS_DEL_CMD, alias)
764
765 def sugadd(self, key, *suggestions, **kwargs):
766 """
767 Add suggestion terms to the AutoCompleter engine. Each suggestion has
768 a score and string.
769 If kwargs["increment"] is true and the terms are already in the
770 server's dictionary, we increment their scores.
771
772 For more information see `FT.SUGADD <https://valkey.io/commands/ft.sugadd/>`_.
773 """ # noqa
774 # If Transaction is not False it will MULTI/EXEC which will error
775 pipe = self.pipeline(transaction=False)
776 for sug in suggestions:
777 args = [SUGADD_COMMAND, key, sug.string, sug.score]
778 if kwargs.get("increment"):
779 args.append("INCR")
780 if sug.payload:
781 args.append("PAYLOAD")
782 args.append(sug.payload)
783
784 pipe.execute_command(*args)
785
786 return pipe.execute()[-1]
787
788 def suglen(self, key: str) -> int:
789 """
790 Return the number of entries in the AutoCompleter index.
791
792 For more information see `FT.SUGLEN <https://valkey.io/commands/ft.suglen>`_.
793 """ # noqa
794 return self.execute_command(SUGLEN_COMMAND, key)
795
796 def sugdel(self, key: str, string: str) -> int:
797 """
798 Delete a string from the AutoCompleter index.
799 Returns 1 if the string was found and deleted, 0 otherwise.
800
801 For more information see `FT.SUGDEL <https://valkey.io/commands/ft.sugdel>`_.
802 """ # noqa
803 return self.execute_command(SUGDEL_COMMAND, key, string)
804
805 def sugget(
806 self,
807 key: str,
808 prefix: str,
809 fuzzy: bool = False,
810 num: int = 10,
811 with_scores: bool = False,
812 with_payloads: bool = False,
813 ) -> List[SuggestionParser]:
814 """
815 Get a list of suggestions from the AutoCompleter, for a given prefix.
816
817 Parameters:
818
819 prefix : str
820 The prefix we are searching. **Must be valid ascii or utf-8**
821 fuzzy : bool
822 If set to true, the prefix search is done in fuzzy mode.
823 **NOTE**: Running fuzzy searches on short (<3 letters) prefixes
824 can be very
825 slow, and even scan the entire index.
826 with_scores : bool
827 If set to true, we also return the (refactored) score of
828 each suggestion.
829 This is normally not needed, and is NOT the original score
830 inserted into the index.
831 with_payloads : bool
832 Return suggestion payloads
833 num : int
834 The maximum number of results we return. Note that we might
835 return less. The algorithm trims irrelevant suggestions.
836
837 Returns:
838
839 list:
840 A list of Suggestion objects. If with_scores was False, the
841 score of all suggestions is 1.
842
843 For more information see `FT.SUGGET <https://valkey.io/commands/ft.sugget>`_.
844 """ # noqa
845 args = [SUGGET_COMMAND, key, prefix, "MAX", num]
846 if fuzzy:
847 args.append(FUZZY)
848 if with_scores:
849 args.append(WITHSCORES)
850 if with_payloads:
851 args.append(WITHPAYLOADS)
852
853 res = self.execute_command(*args)
854 results = []
855 if not res:
856 return results
857
858 parser = SuggestionParser(with_scores, with_payloads, res)
859 return [s for s in parser]
860
861 def synupdate(self, groupid: str, skipinitial: bool = False, *terms: List[str]):
862 """
863 Updates a synonym group.
864 The command is used to create or update a synonym group with
865 additional terms.
866 Only documents which were indexed after the update will be affected.
867
868 Parameters:
869
870 groupid :
871 Synonym group id.
872 skipinitial : bool
873 If set to true, we do not scan and index.
874 terms :
875 The terms.
876
877 For more information see `FT.SYNUPDATE <https://valkey.io/commands/ft.synupdate>`_.
878 """ # noqa
879 cmd = [SYNUPDATE_CMD, self.index_name, groupid]
880 if skipinitial:
881 cmd.extend(["SKIPINITIALSCAN"])
882 cmd.extend(terms)
883 return self.execute_command(*cmd)
884
885 def syndump(self):
886 """
887 Dumps the contents of a synonym group.
888
889 The command is used to dump the synonyms data structure.
890 Returns a list of synonym terms and their synonym group ids.
891
892 For more information see `FT.SYNDUMP <https://valkey.io/commands/ft.syndump>`_.
893 """ # noqa
894 res = self.execute_command(SYNDUMP_CMD, self.index_name)
895 return self._parse_results(SYNDUMP_CMD, res)
896
897
898 class AsyncSearchCommands(SearchCommands):
899 async def info(self):
900 """
901 Get info an stats about the the current index, including the number of
902 documents, memory consumption, etc
903
904 For more information see `FT.INFO <https://valkey.io/commands/ft.info>`_.
905 """
906
907 res = await self.execute_command(INFO_CMD, self.index_name)
908 return self._parse_results(INFO_CMD, res)
909
910 async def search(
911 self,
912 query: Union[str, Query],
913 query_params: Dict[str, Union[str, int, float]] = None,
914 ):
915 """
916 Search the index for a given query, and return a result of documents
917
918 ### Parameters
919
920 - **query**: the search query. Either a text for simple queries with
921 default parameters, or a Query object for complex queries.
922 See RediSearch's documentation on query format
923
924 For more information see `FT.SEARCH <https://valkey.io/commands/ft.search>`_.
925 """ # noqa
926 args, query = self._mk_query_args(query, query_params=query_params)
927 st = time.time()
928 res = await self.execute_command(SEARCH_CMD, *args)
929
930 if isinstance(res, Pipeline):
931 return res
932
933 return self._parse_results(
934 SEARCH_CMD, res, query=query, duration=(time.time() - st) * 1000.0
935 )
936
937 async def aggregate(
938 self,
939 query: Union[str, Query],
940 query_params: Dict[str, Union[str, int, float]] = None,
941 ):
942 """
943 Issue an aggregation query.
944
945 ### Parameters
946
947 **query**: This can be either an `AggregateRequest`, or a `Cursor`
948
949 An `AggregateResult` object is returned. You can access the rows from
950 its `rows` property, which will always yield the rows of the result.
951
952 For more information see `FT.AGGREGATE <https://valkey.io/commands/ft.aggregate>`_.
953 """ # noqa
954 if isinstance(query, AggregateRequest):
955 has_cursor = bool(query._cursor)
956 cmd = [AGGREGATE_CMD, self.index_name] + query.build_args()
957 elif isinstance(query, Cursor):
958 has_cursor = True
959 cmd = [CURSOR_CMD, "READ", self.index_name] + query.build_args()
960 else:
961 raise ValueError("Bad query", query)
962 cmd += self.get_params_args(query_params)
963
964 raw = await self.execute_command(*cmd)
965 return self._parse_results(
966 AGGREGATE_CMD, raw, query=query, has_cursor=has_cursor
967 )
968
969 async def spellcheck(self, query, distance=None, include=None, exclude=None):
970 """
971 Issue a spellcheck query
972
973 ### Parameters
974
975 **query**: search query.
976 **distance***: the maximal Levenshtein distance for spelling
977 suggestions (default: 1, max: 4).
978 **include**: specifies an inclusion custom dictionary.
979 **exclude**: specifies an exclusion custom dictionary.
980
981 For more information see `FT.SPELLCHECK <https://valkey.io/commands/ft.spellcheck>`_.
982 """ # noqa
983 cmd = [SPELLCHECK_CMD, self.index_name, query]
984 if distance:
985 cmd.extend(["DISTANCE", distance])
986
987 if include:
988 cmd.extend(["TERMS", "INCLUDE", include])
989
990 if exclude:
991 cmd.extend(["TERMS", "EXCLUDE", exclude])
992
993 res = await self.execute_command(*cmd)
994
995 return self._parse_results(SPELLCHECK_CMD, res)
996
997 async def config_set(self, option: str, value: str) -> bool:
998 """Set runtime configuration option.
999
1000 ### Parameters
1001
1002 - **option**: the name of the configuration option.
1003 - **value**: a value for the configuration option.
1004
1005 For more information see `FT.CONFIG SET <https://valkey.io/commands/ft.config-set>`_.
1006 """ # noqa
1007 cmd = [CONFIG_CMD, "SET", option, value]
1008 raw = await self.execute_command(*cmd)
1009 return raw == "OK"
1010
1011 async def config_get(self, option: str) -> str:
1012 """Get runtime configuration option value.
1013
1014 ### Parameters
1015
1016 - **option**: the name of the configuration option.
1017
1018 For more information see `FT.CONFIG GET <https://valkey.io/commands/ft.config-get>`_.
1019 """ # noqa
1020 cmd = [CONFIG_CMD, "GET", option]
1021 res = {}
1022 res = await self.execute_command(*cmd)
1023 return self._parse_results(CONFIG_CMD, res)
1024
1025 async def load_document(self, id):
1026 """
1027 Load a single document by id
1028 """
1029 fields = await self.client.hgetall(id)
1030 f2 = {to_string(k): to_string(v) for k, v in fields.items()}
1031 fields = f2
1032
1033 try:
1034 del fields["id"]
1035 except KeyError:
1036 pass
1037
1038 return Document(id=id, **fields)
1039
1040 async def sugadd(self, key, *suggestions, **kwargs):
1041 """
1042 Add suggestion terms to the AutoCompleter engine. Each suggestion has
1043 a score and string.
1044 If kwargs["increment"] is true and the terms are already in the
1045 server's dictionary, we increment their scores.
1046
1047 For more information see `FT.SUGADD <https://valkey.io/commands/ft.sugadd>`_.
1048 """ # noqa
1049 # If Transaction is not False it will MULTI/EXEC which will error
1050 pipe = self.pipeline(transaction=False)
1051 for sug in suggestions:
1052 args = [SUGADD_COMMAND, key, sug.string, sug.score]
1053 if kwargs.get("increment"):
1054 args.append("INCR")
1055 if sug.payload:
1056 args.append("PAYLOAD")
1057 args.append(sug.payload)
1058
1059 pipe.execute_command(*args)
1060
1061 return (await pipe.execute())[-1]
1062
1063 async def sugget(
1064 self,
1065 key: str,
1066 prefix: str,
1067 fuzzy: bool = False,
1068 num: int = 10,
1069 with_scores: bool = False,
1070 with_payloads: bool = False,
1071 ) -> List[SuggestionParser]:
1072 """
1073 Get a list of suggestions from the AutoCompleter, for a given prefix.
1074
1075 Parameters:
1076
1077 prefix : str
1078 The prefix we are searching. **Must be valid ascii or utf-8**
1079 fuzzy : bool
1080 If set to true, the prefix search is done in fuzzy mode.
1081 **NOTE**: Running fuzzy searches on short (<3 letters) prefixes
1082 can be very
1083 slow, and even scan the entire index.
1084 with_scores : bool
1085 If set to true, we also return the (refactored) score of
1086 each suggestion.
1087 This is normally not needed, and is NOT the original score
1088 inserted into the index.
1089 with_payloads : bool
1090 Return suggestion payloads
1091 num : int
1092 The maximum number of results we return. Note that we might
1093 return less. The algorithm trims irrelevant suggestions.
1094
1095 Returns:
1096
1097 list:
1098 A list of Suggestion objects. If with_scores was False, the
1099 score of all suggestions is 1.
1100
1101 For more information see `FT.SUGGET <https://valkey.io/commands/ft.sugget>`_.
1102 """ # noqa
1103 args = [SUGGET_COMMAND, key, prefix, "MAX", num]
1104 if fuzzy:
1105 args.append(FUZZY)
1106 if with_scores:
1107 args.append(WITHSCORES)
1108 if with_payloads:
1109 args.append(WITHPAYLOADS)
1110
1111 ret = await self.execute_command(*args)
1112 results = []
1113 if not ret:
1114 return results
1115
1116 parser = SuggestionParser(with_scores, with_payloads, ret)
1117 return [s for s in parser]