Q i ddlmZddlmZmZmZmZmZmZm Z ddl m Z ddl mZddlmZddlmZddlmZddlmZmZeeZed Zed Ze eeeefee eeeefffZGd d e ZGd deZGddeZ GddZ!GddeeZ"Gdde!eZ#Gdde!eZ$Gdde$Z%GddeZ&dS))Enum)AnyDictListOptionalSetTupleUnion)Query)FilterExpression)array_to_buffer) get_logger) TokenEscaper)denorm_cosine_distance lazy_importnltkznltk.corpus.stopwordscDeZdZUdZiZeeefed<e dZ e ee fed<dZ e eed<ddeffd Zd efd Zd efd Zed e ed eeeeffd Z dd e eded dffd Z dde e ee ffdZed e ee ffdZeddZed eeeffdZed efdZejde efdZddde e eeefffdZxZ S) BaseQuerya Base query class used to subclass many query types. NOTE: In the base class, the `_query_string` field is set once on initialization, and afterward, redis-py expects to be able to read it. By contrast, our query subclasses allow users to call methods that alter the query string at runtime. To avoid having to rebuild `_query_string` every time one of these methods is called, we lazily build the query string when a user calls `query()` or accesses the property `_query_string`, when the underlying `_built_query_string` field is None. Any method that alters the query string should set `_built_query_string` to None so that the next time the query string is accessed, it is rebuilt. _params*_filter_expressionN_built_query_string query_stringc~t|d|_t|_dS)z Initialize the BaseQuery class. Args: query_string (str, optional): The query string to use. Defaults to '*'. N)super__init__rset_skip_decode_fields)selfr __class__s C:\Users\Dell Inspiron 16\Desktop\tws\AgrotaPowerBi\back-agrota-powerbi\mcp-client-agrota\venv\Lib\site-packages\redisvl/query/query.pyrzBaseQuery.__init__,s; &&& $( .1UU   returncddd|DS)z.Return the string representation of the query. c,g|]}t|S)str).0xs r! z%BaseQuery.__str__..As999AQ999r")joinget_argsrs r!__str__zBaseQuery.__str__?s+xx99999:::r"c td)z"Build the full Redis query string.z!Must be implemented by subclasses)NotImplementedErrorr.s r!_build_query_stringzBaseQuery._build_query_stringCs!"EFFFr" sort_speccB||gkrgSg}t|tr||dfndt|trt |dkrt dt ||\}}t|tst dt|t|tst dt||}|dvrt d|d |||d kfnit|tr5|D]1}t |}| |2nt d t||S) ahParse sort specification into list of (field, ascending) tuples. Args: sort_spec: Sort specification in various formats: - str: single field name (defaults to ASC) - Tuple[str, str]: (field_name, "ASC"|"DESC") - List: list of strings or tuples Returns: List of (field_name, ascending) tuples where ascending is a boolean. Raises: TypeError: If sort_spec is not a valid type. ValueError: If direction is not "ASC" or "DESC". Examples: >>> BaseQuery._parse_sort_spec("price") [("price", True)] >>> BaseQuery._parse_sort_spec(("price", "DESC")) [("price", False)] >>> BaseQuery._parse_sort_spec(["price", ("rating", "DESC")]) [("price", True), ("rating", False)] NTz@Sort tuple must have exactly 2 elements (field, direction), got !Field name must be a string, got z Direction must be a string, got )ASCDESCz-Sort direction must be 'ASC' or 'DESC', got ''r7z.sort_by must be a string, tuple, or list, got ) isinstancer(appendtuplelen ValueError TypeErrortypeupperlistr_parse_sort_specextend)r3resultfield directiondirection_upperitemparseds r!rCzBaseQuery._parse_sort_specGs2   RI)+ i % %!  MM9d+ , , , , 5 ) ) 9~~"" gWZ[dWeWegg ) E9eS)) S QDKK Q QRRRi-- V T4 ?? T TUUU'oo//Oo55 PIPPP MM5/U":; < < < < 4 ( ( ! & &"33D99 f%%%% & RiRR  r"Tascc||gkr d|_|St|tr |dur||fg}n||}|s d|_|S|d\}}t |dkr+t dd|Dd|dt|| |S) aSet the sort order for query results. This method supports sorting by single or multiple fields. Note that Redis Search natively supports only a single SORTBY field. When multiple fields are specified, only the FIRST field is used for the Redis SORTBY clause. Args: sort_spec: Sort specification in various formats: - str: single field name - Tuple[str, str]: (field_name, "ASC"|"DESC") - List: list of field names or tuples asc: Default sort direction when not specified (only used when sort_spec is a string). Defaults to True (ascending). Returns: self: Returns the query object for method chaining. Raises: TypeError: If sort_spec is not a valid type. ValueError: If direction is not "ASC" or "DESC". Examples: >>> query.sort_by("price") # Single field, ascending >>> query.sort_by(("price", "DESC")) # Single field, descending >>> query.sort_by(["price", "rating"]) # Multiple fields (only first used) >>> query.sort_by([("price", "DESC"), ("rating", "ASC")]) Note: When multiple fields are specified, only the first field is used for sorting in Redis. Future versions may support multi-field sorting through post-query sorting in Python. NTrz Multiple sort fields specified: cg|] }|d S)rr')r)fs r!r+z%BaseQuery.sort_by..s3I3I3IQAaD3I3I3Ir"zG. Redis Search only supports single-field sorting. Using first field: 'z!'. Additional fields are ignored.)rK) _sortbyr:r(rCr=loggerwarningrsort_by)rr3rKrJ first_field first_ascr s r!rSzBaseQuery.sort_bysF   RDLK i % % 6#T// #&'FF**955F DLK"( Y v;;?? NN13I3I&3I3I3I11Xc111     333 r"filter_expressionc|td|_n3t|ttfr||_nt dd|_dS)aESet the filter expression for the query. Args: filter_expression (Optional[Union[str, FilterExpression]], optional): The filter expression or query string to use on the query. Raises: TypeError: If filter_expression is not a valid FilterExpression or string. NrzDfilter_expression must be of type FilterExpression or string or None)r rr:r(r?r)rrVs r! set_filterzBaseQuery.set_filtersf  $&6s&;&;D # # ),-B$C2222222222r"rceZdZ ddeeeefdeeededed ee d e d ee ee fffd Z d efdZxZS) FilterQueryN r5FrVri num_resultsdialectrSin_orderr^ct|||r||_||_tdd|_|r |j||d|j||r| ||r| dSdS)a5A query for running a filtered search with a filter expression. Args: filter_expression (Optional[Union[str, FilterExpression]]): The optional filter expression to query with. Defaults to '*'. return_fields (Optional[List[str]], optional): The fields to return. num_results (Optional[int], optional): The number of results to return. Defaults to 10. dialect (int, optional): The query dialect. Defaults to 2. sort_by (Optional[SortSpec], optional): The field(s) to order the results by. Can be: - str: single field name (e.g., "price") - Tuple[str, str]: (field_name, "ASC"|"DESC") (e.g., ("price", "DESC")) - List: list of fields or tuples (e.g., ["price", ("rating", "DESC")]) Note: Redis Search only supports single-field sorting, so only the first field is used. Defaults to None. in_order (bool, optional): Requires the terms in the field to have the same order as the terms in the query filter. Defaults to False. params (Optional[Dict[str, Any]], optional): The parameters for the query. Defaults to None. Raises: TypeError: If filter_expression is not of type redisvl.query.FilterExpression rNr) rXr _num_resultsrrrripagingr~rSr) rrVrir}r~rSrr^r s r!rzFilterQuery.__init__;s> )***  "!DL' #'   / D  . . At())11':::  " LL ! ! !   MMOOOOO  r"r#clt|jtrt|jS|jSzEBuild the full query string based on the filter and other components.r:rr r(r.s r!r2zFilterQuery._build_query_stringp2 d-/? @ @ 0t.// /&&r")NNr|r5NFN)rnrorprr r(r rintrtrurrrr2rxrys@r!r{r{:sEI-1&*+/33#E#/?*?$@A3 S *3 3  3 (# 33c3h(333333j'S''''''''r"r{c xeZdZ d deeeefdedeeee fffd Z defdZ xZ S) CountQueryNr5rVr~r^c |||r||_tdd|_|dd|dS)aA query for a simple count operation provided some filter expression. Args: filter_expression (Optional[Union[str, FilterExpression]]): The filter expression to query with. Defaults to None. params (Optional[Dict[str, Any]], optional): The parameters for the query. Defaults to None. Raises: TypeError: If filter_expression is not of type redisvl.query.FilterExpression .. code-block:: python from redisvl.query import CountQuery from redisvl.query.filter import Tag t = Tag("brand") == "Nike" query = CountQuery(filter_expression=t) count = index.query(query) rNr)rXrrrr no_contentrr~)rrVr~r^r s r!rzCountQuery.__init__xs4 )***  "!DL #'    A&&..w77777r"r#clt|jtrt|jS|jSrrr.s r!r2zCountQuery._build_query_stringrr")Nr5N) rnrorprr r(r rrrrr2rxrys@r!rrwsEI+/ $8$8#E#/?*?$@A$8$8c3h( $8$8$8$8$8$8L'S''''''''r"rceZdZUdZeed<dZeed<dZeed<dZeed<dZ eed <d Z eed <d Z eed <d Z eed <d Z eed <dZeed<dZeed<dZeed<dS)BaseVectorQueryvector_distance DISTANCE_IDvector VECTOR_PARAM EF_RUNTIMEEFEF_RUNTIME_PARAMEPSILON EPSILON_PARAMSEARCH_WINDOW_SIZESEARCH_WINDOW_SIZE_PARAMUSE_SEARCH_HISTORYUSE_SEARCH_HISTORY_PARAMSEARCH_BUFFER_CAPACITYSEARCH_BUFFER_CAPACITY_PARAMF_normalize_vector_distanceN)rnrorprr(rrrrrrrrrrrrrrur'r"r!rrs(K((( L#   #J""" c   "M3"""3222$8c8882222$8c888":C:::(@ #@@@',,,,,,r"rceZdZdZdZdZdS) HybridPolicyz7Enum for valid hybrid policy options in vector queries.BATCHESADHOC_BFN)rnrorprqrrr'r"r!rrsAAGHHHr"rc%eZdZ d+deeeefded eeed eeee fd ed e d e de dee de deedee dee deedee deedee de f$fd Z defdZdefdZde fdZde fdZdefdZde fd Zdefd!Zde fd"Zedeefd#Zedee fd$Zedee fd%Zedeefd&Zedee fd'Zedeefd(Zedee fd)Zedeeeffd*Z xZ!S), VectorQueryNfloat32r|Tr5Frvector_field_namerirVdtyper} return_scorer~rSr hybrid_policy batch_size ef_runtimeepsilonsearch_window_sizeuse_search_historysearch_buffer_capacitynormalize_vector_distancec||_||_||_||_d|_d|_d|_d|_d|_d|_ d|_ ||_ | |tdd|_|r |j||d|j||r||j| r|| n||j| r|| || | || | || ||||||||||||dSdS)aA query for running a vector search along with an optional filter expression. Args: vector (List[float]): The vector to perform the vector search with. vector_field_name (str): The name of the vector field to search against in the database. return_fields (List[str]): The declared fields to return with search results. filter_expression (Union[str, FilterExpression], optional): A filter to apply along with the vector search. Defaults to None. dtype (str, optional): The dtype of the vector. Defaults to "float32". num_results (int, optional): The top k results to return from the vector search. Defaults to 10. return_score (bool, optional): Whether to return the vector distance. Defaults to True. dialect (int, optional): The RediSearch query dialect. Defaults to 2. sort_by (Optional[SortSpec]): The field(s) to order the results by. Can be: - str: single field name - Tuple[str, str]: (field_name, "ASC"|"DESC") - List: list of fields or tuples Note: Only the first field is used for Redis sorting. Defaults to None. Results will be ordered by vector distance. in_order (bool): Requires the terms in the field to have the same order as the terms in the query filter, regardless of the offsets between them. Defaults to False. hybrid_policy (Optional[str]): Controls how filters are applied during vector search. Options are "BATCHES" (paginates through small batches of nearest neighbors) or "ADHOC_BF" (computes scores for all vectors passing the filter). "BATCHES" mode is typically faster for queries with selective filters. "ADHOC_BF" mode is better when filters match a large portion of the dataset. Defaults to None, which lets Redis auto-select the optimal policy. batch_size (Optional[int]): When hybrid_policy is "BATCHES", controls the number of vectors to fetch in each batch. Larger values may improve performance at the cost of memory usage. Only applies when hybrid_policy="BATCHES". Defaults to None, which lets Redis auto-select an appropriate batch size. ef_runtime (Optional[int]): Controls the size of the dynamic candidate list for HNSW algorithm at query time. Higher values improve recall at the expense of slower search performance. Defaults to None, which uses the index-defined value. epsilon (Optional[float]): The range search approximation factor for HNSW and SVS-VAMANA indexes. Sets boundaries for candidates within radius * (1 + epsilon). Higher values allow more extensive search and more accurate results at the expense of run time. Defaults to None, which uses the index-defined value (typically 0.01). search_window_size (Optional[int]): The size of the search window for SVS-VAMANA KNN searches. Increasing this value generally yields more accurate but slower search results. Defaults to None, which uses the index-defined value (typically 10). use_search_history (Optional[str]): For SVS-VAMANA indexes, controls whether to use the search buffer or entire search history. Options are "OFF", "ON", or "AUTO". "AUTO" is always evaluated internally as "ON". Using the entire history may yield a slightly better graph at the cost of more search time. Defaults to None, which uses the index-defined value (typically "AUTO"). search_buffer_capacity (Optional[int]): Tuning parameter for SVS-VAMANA indexes using two-level compression (LVQx or LeanVec types). Determines the number of vector candidates to collect in the first level of search before the re-ranking level. Defaults to None, which uses the index-defined value (typically SEARCH_WINDOW_SIZE). normalize_vector_distance (bool): Redis supports 3 distance metrics: L2 (euclidean), IP (inner product), and COSINE. By default, L2 distance returns an unbounded value. COSINE distance returns a value between 0 and 2. IP returns a value determined by the magnitude of the vector. Setting this flag to true converts COSINE and L2 distance to a similarity score between 0 and 1. Note: setting this flag to true for IP will throw a warning since by definition COSINE similarity is normalized IP. Raises: TypeError: If filter_expression is not of type redisvl.query.FilterExpression Note: Learn more about vector queries in Redis: https://redis.io/docs/latest/develop/ai/search-and-query/vectors/#knn-vector-search Nrr)_vector_vector_field_name_dtyper_hybrid_policy _batch_size _ef_runtime_epsilon_search_window_size_use_search_history_search_buffer_capacityrrXrrrrirr~rrSrset_hybrid_policyset_batch_sizeset_ef_runtime set_epsilonset_search_window_sizeset_use_search_historyset_search_buffer_capacity)rrrrirVrr}rr~rSrrrrrrrrrr s r!rzVectorQuery.__init__sx "3 '6:*.*.)- 26 26 6:$*C' )*** #'   / D  . . At())11':::  1   t/ 0 0 0  + LL ! ! ! ! LL) * * *   MMOOO  $  " "= 1 1 1  !    + + +  !    + + +     W % % %  )  ' '(: ; ; ;  )  ' '(: ; ; ; ! -  + +,B C C C C C . -r"r#cB|j}t|trt|}d|jd|jd|j}|jr;|d|jjz }|jtj kr|j r |d|j z }|j r|d|j d|jz }|j |d|jz }|j|d|jd|jz }|j|d|jd|jz }|j|d|jd|jz }|d |jz }|d |d S) zFBuild the full query string for vector search with optional filtering.zKNN z @ $z HYBRID_POLICY z BATCH_SIZE r%Nz EPSILON $z AS z=>[])rr:r r(rrrrrarrrrrrrrrrrrrrrrrr)rrV knn_querys r!r2zVectorQuery._build_query_stringUs 3 ')9 : : 7 #$5 6 6  W4$ V V(? V V4CT V V    ? F4+>+DFF FI"l&:::t?O:>D,<>>>    H GT_GG0EGG GI = $ :d&8:: :I  # / WT4WW8UWW WI  # / WT4WW8UWW WI  ' 3 VD/VV43TVV I .D,... #44 4444r"c t||_nB#t$r5tdddtDwxYwd|_dS)Set the hybrid policy for the query. Args: hybrid_policy (str): The hybrid policy to use. Options are "BATCHES" or "ADHOC_BF". Raises: ValueError: If hybrid_policy is not one of the valid options hybrid_policy must be one of , cg|] }|j Sr'rar)ps r!r+z1VectorQuery.set_hybrid_policy..:Y:Y:Yq17:Y:Y:Yr"Nrrr>r,rrrs r!rzVectorQuery.set_hybrid_policy} ".}"="=D     \ :Y:YL:Y:Y:Y0Z0Z\\   $(   ?Act|tstd|dkrtd||_d|_dSa Set the batch size for the query. Args: batch_size (int): The batch size to use when hybrid_policy is "BATCHES". Raises: TypeError: If batch_size is not an integer ValueError: If batch_size is not positive zbatch_size must be an integerrzbatch_size must be positiveNr:rr?r>rrrrs r!rzVectorQuery.set_batch_sizeU*c** =;<< < ??:;; ;%$(   r"ct|tstd|dkrtd||_d|_dS)a]Set the EF_RUNTIME parameter for the query. Args: ef_runtime (int): The EF_RUNTIME value to use for HNSW algorithm. Higher values improve recall at the expense of slower search. Raises: TypeError: If ef_runtime is not an integer ValueError: If ef_runtime is not positive zef_runtime must be an integerrzef_runtime must be positiveN)r:rr?r>rr)rrs r!rzVectorQuery.set_ef_runtimesU*c** =;<< < ??:;; ;%$(   r"ct|ttfstd|dkrt d||_d|_dS)aSet the epsilon parameter for the query. Args: epsilon (float): The range search approximation factor for HNSW and SVS-VAMANA indexes. Sets boundaries for candidates within radius * (1 + epsilon). Higher values allow more extensive search and more accurate results at the expense of run time. Raises: TypeError: If epsilon is not a float or int ValueError: If epsilon is negative $epsilon must be of type float or intrepsilon must be non-negativeNr:floatrr?r>rrrrs r!rzVectorQuery.set_epsilonsY'E3<00 DBCC C Q;;;<< < $(   r"ct|tstd|dkrtd||_d|_dS)aSet the SEARCH_WINDOW_SIZE parameter for the query. Args: search_window_size (int): The size of the search window for SVS-VAMANA KNN searches. Increasing this value generally yields more accurate but slower search results. Raises: TypeError: If search_window_size is not an integer ValueError: If search_window_size is not positive %search_window_size must be an integerr#search_window_size must be positiveNr:rr?r>rrrrs r!rz"VectorQuery.set_search_window_sizesY,c22 ECDD D  " "BCC C#5 $(   r"ct|tstdgd}||vr%tdd|||_d|_dS)aSet the USE_SEARCH_HISTORY parameter for the query. Args: use_search_history (str): For SVS-VAMANA indexes, controls whether to use the search buffer or entire search history. Options are "OFF", "ON", or "AUTO". Raises: TypeError: If use_search_history is not a string ValueError: If use_search_history is not one of "OFF", "ON", or "AUTO" #use_search_history must be a stringOFFONAUTO"use_search_history must be one of rNr:r(r?r>r,rrrr valid_optionss r!rz"VectorQuery.set_use_search_history,c22 CABB B--- ] 2 2OTYY}5M5MOO $6 $(   r"ct|tstd|dkrtd||_d|_dS)aSet the SEARCH_BUFFER_CAPACITY parameter for the query. Args: search_buffer_capacity (int): Tuning parameter for SVS-VAMANA indexes using two-level compression. Determines the number of vector candidates to collect in the first level of search before the re-ranking level. Raises: TypeError: If search_buffer_capacity is not an integer ValueError: If search_buffer_capacity is not positive )search_buffer_capacity must be an integerr'search_buffer_capacity must be positiveNr:rr?r>rrrrs r!rz&VectorQuery.set_search_buffer_capacitysY0#66 IGHH H !Q & &FGG G'=$$(   r"c,|jr |jjndSz~Return the hybrid policy for the query. Returns: Optional[str]: The hybrid policy for the query. Nrrar.s r!rzVectorQuery.hybrid_policy-1,?It"((TIr"c|jSzxReturn the batch size for the query. Returns: Optional[int]: The batch size for the query. rr.s r!rzVectorQuery.batch_size r"c|jS)zReturn the EF_RUNTIME parameter for the query. Returns: Optional[int]: The EF_RUNTIME value for the query. )rr.s r!rzVectorQuery.ef_runtime&rr"c|jS)zReturn the epsilon parameter for the query. Returns: Optional[float]: The epsilon value for the query. rr.s r!rzVectorQuery.epsilon/ }r"c|jSzReturn the SEARCH_WINDOW_SIZE parameter for the query. Returns: Optional[int]: The SEARCH_WINDOW_SIZE value for the query. rr.s r!rzVectorQuery.search_window_size8 ''r"c|jSzReturn the USE_SEARCH_HISTORY parameter for the query. Returns: Optional[str]: The USE_SEARCH_HISTORY value for the query. rr.s r!rzVectorQuery.use_search_historyArr"c|jSzReturn the SEARCH_BUFFER_CAPACITY parameter for the query. Returns: Optional[int]: The SEARCH_BUFFER_CAPACITY value for the query. rr.s r!rz"VectorQuery.search_buffer_capacityJ ++r"cnt|jtr|j}nt|j|j}|j|i}|j|j||j<|j|j||j <|j |j ||j <|j |j ||j <|j|j||j<|SzyReturn the parameters for the query. Returns: Dict[str, Any]: The parameters for the query. )r)r:rbytesr rrrrrrrrrrrrrrr^s r!r^zVectorQuery.paramsSs dlE * * F\FF$T\EEEF"&"3V!<   ',0,x or LeanVec types). Determines the number of vector candidates to collect in the first level of search before the re-ranking level. Defaults to None, which uses the index-defined value (typically SEARCH_WINDOW_SIZE). num_results (int): The MAX number of results to return. Defaults to 10. return_score (bool, optional): Whether to return the vector distance. Defaults to True. dialect (int, optional): The RediSearch query dialect. Defaults to 2. sort_by (Optional[SortSpec]): The field(s) to order the results by. Can be: - str: single field name - Tuple[str, str]: (field_name, "ASC"|"DESC") - List: list of fields or tuples Note: Only the first field is used for Redis sorting. Defaults to None. Results will be ordered by vector distance. in_order (bool): Requires the terms in the field to have the same order as the terms in the query filter, regardless of the offsets between them. Defaults to False. hybrid_policy (Optional[str]): Controls how filters are applied during vector search. Options are "BATCHES" (paginates through small batches of nearest neighbors) or "ADHOC_BF" (computes scores for all vectors passing the filter). "BATCHES" mode is typically faster for queries with selective filters. "ADHOC_BF" mode is better when filters match a large portion of the dataset. Defaults to None, which lets Redis auto-select the optimal policy. batch_size (Optional[int]): When hybrid_policy is "BATCHES", controls the number of vectors to fetch in each batch. Larger values may improve performance at the cost of memory usage. Only applies when hybrid_policy="BATCHES". Defaults to None, which lets Redis auto-select an appropriate batch size. normalize_vector_distance (bool): Redis supports 3 distance metrics: L2 (euclidean), IP (inner product), and COSINE. By default, L2 distance returns an unbounded value. COSINE distance returns a value between 0 and 2. IP returns a value determined by the magnitude of the vector. Setting this flag to true converts COSINE and L2 distance to a similarity score between 0 and 1. Note: setting this flag to true for IP will throw a warning since by definition COSINE similarity is normalized IP. Raises: TypeError: If filter_expression is not of type redisvl.query.FilterExpression Note: Learn more about vector range queries: https://redis.io/docs/interact/search-and-query/search/vectors/#range-query rNrr)rrrr_distance_thresholdrrrrrrrrrrrrrrrrset_distance_thresholdrXrirr~rrSr)rrrrirVrrrrrrr}rr~rSrrrrr s r!rzVectorRangeQuery.__init__~sz "3 '*- )- 26 26 6:$6:*.*C' #'     W % % %  )  ' '(: ; ; ;  )  ' '(: ; ; ; ! -  + +,B C C C  $  " "= 1 1 1  !    + + + ##$6777 )***  / D  . . At())11':::  1   t/ 0 0 0  + LL ! ! ! ! LL) * * *   MMOOOOO  r"ct|ttfstd|dkrt d|jr$|dkrt dt |}||_d|_dS)aSet the distance threshold for the query. Args: distance_threshold (float): Vector distance threshold. Raises: TypeError: If distance_threshold is not a float or int ValueError: If distance_threshold is negative z/distance_threshold must be of type float or intrz'distance_threshold must be non-negativerMzXdistance_threshold must be between 0 and 1 when normalize_vector_distance is set to TrueN) r:rrr?r>rrrr)rrs r!rz'VectorRangeQuery.set_distance_thresholds,ucl;; OMNN N  ! !FGG G  * L!A%% n "88J!K!K #5 $(   r"ct|ttfstd|dkrt d||_d|_dS)aZSet the epsilon parameter for the range query. Args: epsilon (float): The relative factor for vector range queries, setting boundaries for candidates within radius * (1 + epsilon). Raises: TypeError: If epsilon is not a float or int ValueError: If epsilon is negative rrrNrrs r!rzVectorRangeQuery.set_epsilon-sY'E3<00 DBCC C Q;;;<< < $(   r"ct|tstd|dkrtd||_d|_dS)aBSet the SEARCH_WINDOW_SIZE parameter for the range query. Args: search_window_size (int): The size of the search window for SVS-VAMANA range searches. Raises: TypeError: If search_window_size is not an integer ValueError: If search_window_size is not positive rrrNrrs r!rz'VectorRangeQuery.set_search_window_sizeAsY,c22 ECDD D  " "BCC C#5 $(   r"ct|tstdgd}||vr%tdd|||_d|_dS)aSet the USE_SEARCH_HISTORY parameter for the range query. Args: use_search_history (str): Controls whether to use the search buffer or entire history. Must be one of "OFF", "ON", or "AUTO". Raises: TypeError: If use_search_history is not a string ValueError: If use_search_history is not one of the valid options rrrrNrrs r!rz'VectorRangeQuery.set_use_search_historyTrr"ct|tstd|dkrtd||_d|_dS)ajSet the SEARCH_BUFFER_CAPACITY parameter for the range query. Args: search_buffer_capacity (int): Tuning parameter for SVS-VAMANA indexes using two-level compression. Raises: TypeError: If search_buffer_capacity is not an integer ValueError: If search_buffer_capacity is not positive rrrNrrs r!rz+VectorRangeQuery.set_search_buffer_capacityksY0#66 IGHH H !Q & &FGG G'=$$(   r"c t||_nB#t$r5tdddtDwxYwd|_dS)rrrcg|] }|j Sr'rrs r!r+z6VectorRangeQuery.set_hybrid_policy..rr"Nrrs r!rz"VectorRangeQuery.set_hybrid_policyrrct|tstd|dkrtd||_d|_dSrrrs r!rzVectorRangeQuery.set_batch_sizerr"r#cLd|jd|jd|jd}g}|d|j|j|d|j|j|d|j|j|d |j|j|d |jd d |d }|j }t|trt|}|dkr||Sd||d|dS)zLBuild the full query string for vector range queries with optional filtering@z:[VECTOR_RANGE $rrz$YIELD_DISTANCE_AS: Nz $EPSILON: z$SEARCH_WINDOW_SIZE: z$USE_SEARCH_HISTORY: z$SEARCH_BUFFER_CAPACITY: z=>{z; }r(r%))rrrr;rrrrrr,rr:r r()r base_query attr_parts attr_sectionrVs r!r2z$VectorRangeQuery._build_query_stringsx0ww$B_wwcgctwww  C1ACCDDD = $   :4=:: ; ; ;  # /   Pd6NPP Q Q Q  # /   Pd6NPP Q Q Q  ' 3   JD,HJJ    8dii 33777 !3 ')9 : : 7 #$5 6 6   # # 0,00 0B:B|BB.?BBBBr"c|jS)zReturn the distance threshold for the query. Returns: float: The distance threshold for the query. )rr.s r!rz#VectorRangeQuery.distance_thresholdrr"c|jS)zReturn the epsilon for the query. Returns: Optional[float]: The epsilon for the query, or None if not set. rr.s r!rzVectorRangeQuery.epsilonrr"c|jSrrr.s r!rz#VectorRangeQuery.search_window_sizerr"c|jSrrr.s r!rz#VectorRangeQuery.use_search_historyrr"c|jSr r r.s r!rz'VectorRangeQuery.search_buffer_capacityr r"c,|jr |jjndSrrr.s r!rzVectorRangeQuery.hybrid_policyrr"c|jSrrr.s r!rzVectorRangeQuery.batch_sizerr"c6t|jtr|j}nt|j|j}|j||j|ji}|j?|jj ||j <|jtj kr|j |j ||j<|Sr )r:rrr rrrrrrarrrrrrs r!r^zVectorRangeQuery.params s dlE * * F\FF$T\EEEF  v  )4+C    */3/B/HF4+ ,#|';;;$0040@t,- r")NNrrNNNNr|Tr5NFNNF)'rnrorprr(rrrrrr rrrrr rrurtrrrrrrrrr2rvrrrrrrrrrr^rxrys@r!rrxs$8c888"M3"""....(c((( .2DH$'#',0,004!&*'+$(*/'RRd5k5()RR S * R $E#/?*?$@A R  R"R%R%SMR%SMR!) RRRR(#R !R" }#R$SM%R&$('RRRRRRh(((((6(5((((((((((&(((((.(((((((s((((((((((&%CS%C%C%C%CN(E(((X(%X(HSM(((X((HSM(((X(, ,,,X,Jx}JJJXJ HSM   X S#XXr"rceZdZdS) RangeQueryN)rnrorpr'r"r!r5r5)sDr"r5ceZdZdZ d'd ed eeeeeffd ed eeee fd ee ede de de dee de deeeefdeeeeefdeeeefffd ZedZd(deeeeeffdZdedefdZdeeeeeffdeeeffdZdeeeeefffdZedeeeffd Zedeeeeefffd!Zd"eeeefdeeeffd#Zd"eeeffd$Zedeeeffd%Zdefd&ZxZS)) TextQueryav TextQuery is a query for running a full text search, along with an optional filter expression. .. code-block:: python from redisvl.query import TextQuery from redisvl.index import SearchIndex index = SearchIndex.from_yaml("index.yaml") query = TextQuery( text="example text", text_field_name="text_field", text_scorer="BM25STD", filter_expression=None, num_results=10, return_fields=["field1", "field2"], stopwords="english", dialect=2, ) results = index.query(query) BM25STDNr|Tr5Fenglishtexttext_field_name text_scorerrVrir}rr~rSrr^ stopwords text_weightscj||_|||_|| |_||_|| ||| r| |_t dd|_ | ||r |j ||d|j|| r|| | r||r|dSdS)a A query for running a full text search, along with an optional filter expression. Args: text (str): The text string to perform the text search with. text_field_name (Union[str, Dict[str, float]]): The name of the document field to perform text search on, or a dictionary mapping field names to their weights. text_scorer (str, optional): The text scoring algorithm to use. Defaults to BM25STD. Options are {TFIDF, BM25STD, BM25, TFIDF.DOCNORM, DISMAX, DOCSCORE}. See https://redis.io/docs/latest/develop/interact/search-and-query/advanced-concepts/scoring/ filter_expression (Union[str, FilterExpression], optional): A filter to apply along with the text search. Defaults to None. return_fields (List[str]): The declared fields to return with search results. num_results (int, optional): The top k results to return from the search. Defaults to 10. return_score (bool, optional): Whether to return the text score. Defaults to True. dialect (int, optional): The RediSearch query dialect. Defaults to 2. sort_by (Optional[SortSpec]): The field(s) to order the results by. Can be: - str: single field name - Tuple[str, str]: (field_name, "ASC"|"DESC") - List: list of fields or tuples Note: Only the first field is used for Redis sorting. Defaults to None. Results will be ordered by text score. in_order (bool): Requires the terms in the field to have the same order as the terms in the query filter, regardless of the offsets between them. Defaults to False. params (Optional[Dict[str, Any]], optional): The parameters for the query. Defaults to None. stopwords (Optional[Union[str, Set[str]]): The set of stop words to remove from the query text (client-side filtering). If a language like 'english' or 'spanish' is provided a default set of stopwords for that language will be used. Users may specify their own stop words by providing a List or Set of words. if set to None, then no words will be removed. Defaults to 'english'. Note: This parameter controls query-time stopword filtering (client-side). For index-level stopwords configuration (server-side), see IndexInfo.stopwords. Using query-time stopwords with index-level STOPWORDS 0 is counterproductive. text_weights (Optional[Dict[str, float]]): The importance weighting of individual words within the query text. Defaults to None, as no modifications will be made to the text_scorer score. Raises: ValueError: if stopwords language string cannot be loaded. TypeError: If stopwords is not a valid iterable set of strings. rNr)_text_parse_field_weights_field_weights_parse_text_weights _text_weightsr_set_stopwordsrXrrrrscorerrirr~rSr with_scores)rr:r;r<rVrir}rr~rSrr^r=r>r s r!rzTextQuery.__init__GsC| "77HH!55lCC' I&&& )***  "!DL #'  K    / D  . . At())11':::  " LL ! ! !   MMOOO            r"c|jSrm _stopwordsr.s r!r=zTextQuery.stopwordss r"c|st|_dSt|tr tt||_dS#t $rKtddtt||_YnwxYwdS#t$rtd|dt$r}td|d|d}~wwxYwt|tttfr/td |Drt||_dSt!d ) aASet the stopwords to use in the query. Args: stopwords (Optional[Union[str, Set[str]]]): The stopwords to use. If a string such as "english" "german" is provided then a default set of stopwords for that language will be used. if a list, set, or tuple of strings is provided then those will be used as stopwords. Defaults to "english". if set to "None" then no stopwords will be removed. Raises: TypeError: If the stopwords are not a set, list, or tuple of strings. r=T)quietzLoading stopwords for z failed: nltk is not installed.zError trying to load z from nltk. Nc3@K|]}t|tVdSrm)r:r()r)words r! z+TextQuery._set_stopwords..s=? ? &*JtS ! !? ? ? ? ? ? r"z2stopwords must be a set, list, or tuple of strings)rrJr:r(nltk_stopwordswords LookupErrorrdownload ImportErrorr> Exceptionrrr allr?)rr=es r!rEzTextQuery._set_stopwordss R!eeDOOO  3 ' ' R UK&).*>*>y*I*I&J&JDOOO"KKKMM+TM:::&).*>*>y*I*I&J&JDOOOK#O    WYWWW U U U !S!S!SPQ!S!STTT U  Cu#5 6 6 R3? ? .7? ? ? < <  R")nnDOOOPQQ Qs0,AAB2/B71B22B77&C7C22C7 user_queryr#ctfd|D}fd|D}t|D]$\}}|jvr|dj|d||<%d|S)aNConvert a raw user query to a redis full text query joined by ORs Args: user_query (str): The user query to tokenize and escape. Returns: str: The tokenized and escaped query string. Raises: ValueError: If the text string becomes empty after stopwords are removed. cg|]v}|dddddwS),u“u”)escapestripreplacelower)r)tokenescapers r!r+z8TextQuery._tokenize_and_escape_query..s~    NN ##C((00;;CCE2NNTTVV     r"c*g|]}|r |jv |Sr'rI)r)rars r!r+z8TextQuery._tokenize_and_escape_query..s4    383O3OE3O3O3Or"z =>{$weight:r& | )rsplit enumeraterDr,)rrXtokens token_listirarbs` @r!_tokenize_and_escape_queryz$TextQuery._tokenize_and_escape_querys..    $))++         %   "*-- T THAu***#( S Sd6H6O S S S 1 zz*%%%r" field_specc t|tr|diSt|tr|D]\}}t|tst dt |t|t tfs"t d|dt ||dkrtd|d||St d)zParse the field specification into a weights dictionary. Args: field_spec: Either a single field name or dictionary of field:weight mappings Returns: Dictionary mapping field names to their weights ?r6zWeight for field 'z' must be numeric, got rz' must be positive, got zGtext_field_name must be a string or dictionary of field:weight mappings) r:r(dictitemsr?r@rrr>)rrkrFweights r!rAzTextQuery._parse_field_weightss j# & & $ $  D ) ) !+!1!1!3!3   v!%--W#$UU $U$UVVV!&3,77#YUYY4PV<<YYQ;;$TUTTFTT Y r" field_weightscH|||_d|_dS)zSet or update the field weights for the query. Args: field_weights: Either a single field name or dictionary of field:weight mappings N)rArBr)rrqs r!set_field_weightszTextQuery.set_field_weightss( #77 FF#'   r"c4|jS)z{Get the field weights for the query. Returns: Dictionary mapping field names to their weights )rBcopyr.s r!rqzTextQuery.field_weightss"'')))r"ct|jdkr>tt|j\}}|dkr|S|jS)zGet the text field name(s) - for backward compatibility. Returns: Either a single field name string (if only one field with weight 1.0) or a dictionary of field:weight mappings. rMrm)r=rBnextiterroru)rrFrps r!r;zTextQuery.text_field_namese t" # #q ( ( d&9&?&?&A&A!B!BCCME6}} "'')))r"weightsc`i}|s|S|D]\}}|}|rd|vrtd|d|dt |t st |t r|dkrtd|d|d|||<|S)Nr%z-Only individual words may be weighted. Got { : }gz'Weights must be positive number. Got { )ror^r`r>r:rr)rryparsed_weightsrNrps r!rCzTextQuery._parse_text_weights(s,. "! !#MMOO * *LD&::<<%%''D 3$;; WTWWFWWW .. 2s( "55g>>#'   r"c|jS)z`Get the text weights. Returns: Dictionary of word:weight mappings. )rDr.s r!r>zTextQuery.text_weightsGs !!r"c |j}t|trt|}||j}g}|jD]G\}}|dkr|d|d|d(|d|d|d|dHt|dkr |d}nd d |zdz}|r|d kr|d |z }|S) zDBuild the full query string for text search with optional filtering.rmr%z:(r(z) => { $weight: r|rMrr'rdrz AND ) rr:r r(rjr@rBror;r=r,)rrV escaped_query field_queriesrFrpr:s r!r2zTextQuery._build_query_stringPsE 3 ')9 : : 7 #$5 6 6 77 CC  !06688  ME6}}$$%B%B%B-%B%B%BCCCC$$LLLLLLLL }   " " #DDM222S8D  0!2c!9!9 /-// /D r") r8NNr|Tr5NFNr9N)r9)rnrorprqr(r rrrr rrrurtrrrrvr=rErjrArsrqr;rCrr>r2rxrys@r!r7r7.s[8%DH-1!&*+/4=37[[[sDe$445[ [ $E#/?*?$@A [  S * [[[[(#[[c3h([E#s3x-01[tCJ/0[[[[[[zX"R"RsCH}1E(F"R"R"R"RH&S&S&&&&6T#u*%5 56 c5j @(uS$sEz:J5J/K((((*tCJ/***X* *sDe,<'rs??????????????????;;;;;;111111//////((((((444444CCCCCCCC H  {6455 eCHotE#uS#X2F,G'HH I^^^^^ ^^^B :':':':':'):':':'z+'+'+'+'+'+'+'+'\--------(3uuuuu/9uuup nnnnn nnnb      !   ~~~~~ ~~~~~r"