IZj ddlmZddlZddlmZmZddlmZddlm Z ddl m Z ddl m Z mZmZmZmZmZmZmZmZmZddlZddlZddlZddlmZddlZddl m!Z!dd l"m#Z#dd l$m%Z%dd l&m'Z'd d l(m)Z)d dl*m+Z+d dl,m-Z.d dl/m0Z0d dl1m2Z2d dl3m4Z4d dl5m6Z6d dl7m8Z8e rZddl9Z9ddl:Z:ddl;ZZ?d dl=m@ZAd dl=mBZBd dl=mCZDd dl=mEZFd dl=mGZHd dlImJZJd dlmKZKd dlLmMZMe9jNdkrddl mOZOnddl mOZOed d!"ZPd^d'ZQGd(d)ejRZSGd*d+eTe ZUGd,d-eTe ZVGd.d/eTe ZWejXjYGd0d1eZZejXjYGd2d3eZZ[ejXjYGd4d5eZZ\ejXjYGd6d7eZZ]ejXjYGd8d9eZZ^ejXjYGd:d;eZZ_Gd<d=ejRZ`Gd>d?ejRZCGd@dAeZaGdBdCeaZbGdDdEeaZcGdFdGeaZdGdHdIeaZeGdJdKefZgGdLdMegZhGdNdOehZiGdPdQehZjGdRdSZkGdTdUehekZlGdVdWehekZmGdXdYegZnGdZd[efZoGd\d]eoZpdS)_) annotationsN)ABCabstractmethod)ThreadPoolExecutor) timedelta)Enum) TYPE_CHECKINGAnyDictListLiteralOptionalTupleTypeTypeVarUnion) Annotatedfts_query_to_json)LOOP)PYDANTIC_VERSION) __version__)AsyncRecordBatchReader)pandas)Expr)Reranker) RRFReranker)check_reranker_result)flatten_columns)FTSQuery) HybridQuery)PyQueryRequest)Query) TakeQuery) VectorQuery)VEC) LanceModel)Table) )SelfTr()boundvalr return?Union[List[float], List[List[float]], pa.Array, List[pa.Array]]ct|tr+t|dkrtd|d}n&t|trtd|}t|t jr|St|tr?t|dkrtdt|dtr|St|tr|SdS)Nrz%Vector query must be a non-empty listzBVector query must be a list of floats or a list of lists of floats) isinstancelistlen ValueErrorfloatpaArray)r/samples Y/Users/jameslopez/projects/MentorCore/.venv/lib/python3.11/site-packages/lancedb/query.pyensure_vector_queryr<Es#t  s88q==DEE EQ c5 ! ! T &"(## &$ v;;!  DEE E fQi ' ' J&%   c6eZdZUded<dZded<dZded<dS) ColumnOrderingstr column_nameTbool ascendingF nulls_firstN)__name__ __module__ __qualname____annotations__rCrDr=r;r?r?`s@IKr=r?c"eZdZdZdZdZdZdZdS)FullTextQueryTypematch match_phraseboost multi_matchbooleanN)rErFrGMATCH MATCH_PHRASEBOOST MULTI_MATCHBOOLEANrIr=r;rKrKfs' E!L EKGGGr=rKceZdZdZdZdS)FullTextOperatorANDORN)rErFrGrXrYrIr=r;rWrWns C BBBr=rWceZdZdZdZdZdS)OccurSHOULDMUSTMUST_NOTN)rErFrGr\r]r^rIr=r;r[r[ss F DHHHr=r[c>eZdZed dZd dZd dZd d Zd S) FullTextQueryr0rKcdS)z Get the query type of the query. Returns ------- str The type of the query. NrIselfs r; query_typezFullTextQuery.query_type{s  r=r@c t|S)a Convert the query to a JSON string. Returns ------- str A JSON string representation of the query. Examples -------- >>> from lancedb.query import MatchQuery >>> query = MatchQuery("puppy", "text", fuzziness=2) >>> query.to_json() '{"match":{"column":"text","terms":"puppy","boost":1.0,"fuzziness":2,"max_expansions":50,"operator":"Or","prefix_length":0}}' rrbs r;to_jsonzFullTextQuery.to_jsons !&&&r=other'FullTextQuery'cTttj|ftj|fgS)a) Combine two queries with a logical AND operation. Parameters ---------- other : FullTextQuery The other query to combine with. Returns ------- FullTextQuery A new query that combines both queries with AND. ) BooleanQueryr[r]rcrgs r;__and__zFullTextQuery.__and__s%ej$/%*e1DEFFFr=cTttj|ftj|fgS)a' Combine two queries with a logical OR operation. Parameters ---------- other : FullTextQuery The other query to combine with. Returns ------- FullTextQuery A new query that combines both queries with OR. )rjr[r\rks r;__or__zFullTextQuery.__or__s%elD1EL%3HIJJJr=Nr0rKr0r@)rgrhr0rh)rErFrGrrdrfrlrnrIr=r;r`r`ysx    ^  ''''$GGGG KKKKKKr=r`c eZdZUdZded<ded<ejddZded <ejd dZd ed <ejd dZ d ed<eje j dZ ded<ejd dZ d ed<ddZdS) MatchQuerya Match query for full-text search. Parameters ---------- query : str The query string to match against. column : str The name of the column to match against. boost : float, default 1.0 The boost factor for the query. The score of each matching document is multiplied by this value. fuzziness : int, optional The maximum edit distance for each term in the match query. Defaults to 0 (exact match). If None, fuzziness is applied automatically by the rules: - 0 for terms with length <= 2 - 1 for terms with length <= 5 - 2 for terms with length > 5 max_expansions : int, optional The maximum number of terms to consider for fuzzy matching. Defaults to 50. operator : FullTextOperator, default OR The operator to use for combining the query results. Can be either `AND` or `OR`. If `AND`, all terms in the query must match. If `OR`, at least one term in the query must match. prefix_length : int, optional The number of beginning characters being unchanged for fuzzy matching. This is useful to achieve prefix matching. r@querycolumng?Tkw_onlyr7rNrint fuzziness2max_expansionsrWoperator prefix_lengthr0rKctjSN)rKrQrbs r;rdzMatchQuery.query_type  &&r=Nro)rErFrG__doc__rHpydanticFieldrNrxrzrWrYr{r|rdrIr=r;rrrrs@JJJKKK!8>#t444E4444#X^At444I4444((.T:::N::::!/0@0CT!R!R!RHRRRR'4888M8888''''''r=rrc^eZdZUdZded<ded<ejddZded <dd Zd S) PhraseQueryz Phrase query for full-text search. Parameters ---------- query : str The query string to match against. column : str The name of the column to match against. r@rsrtrTrurwslopr0rKctjSr~)rKrRrbs r;rdzPhraseQuery.query_types  --r=Nro) rErFrGrrHrrrrdrIr=r;rrsj  JJJKKKq$///D////......r=rc^eZdZUdZded<ded<ejddZded <dd Zd S) BoostQuerya Boost query for full-text search. Parameters ---------- positive : dict The positive query object. negative : dict The negative query object. negative_boost : float, default 0.5 The boost factor for the negative query. r`positivenegativeg?Trur7negative_boostr0rKctjSr~)rKrSrbs r;rdzBoostQuery.query_typerr=Nro) rErFrGrrHrrrrdrIr=r;rrsp  *HN3===N====''''''r=rceZdZUdZded<ded<ejddZd ed <ejej dZ d ed <ddZ dS)MultiMatchQuerya Multi-match query for full-text search. Parameters ---------- query : str | list[Query] If a string, the query string to match against. columns : list[str] The list of columns to match against. boosts : list[float], optional The list of boost factors for each column. If not provided, all columns will have the same boost factor. operator : FullTextOperator, default OR The operator to use for combining the query results. Can be either `AND` or `OR`. It would be applied to all columns individually. For example, if the operator is `AND`, then the query "hello world" is equal to `match("hello AND world", column1) OR match("hello AND world", column2)`. r@rsz list[str]columnsNTruzOptional[list[float]]boostsrWr{r0rKctjSr~)rKrTrbs r;rdzMultiMatchQuery.query_type0s  ,,r=ro) rErFrGrrHrrrrWrYr{rdrIr=r;rrs*JJJ$2HN4$F$F$FFFFFF!/0@0CT!R!R!RHRRRR------r=rc&eZdZUdZded<ddZdS) rja) Boolean query for full-text search. Parameters ---------- queries : list[tuple(Occur, FullTextQuery)] The list of queries with their occurrence requirements. Each tuple contains an Occur value (MUST, SHOULD, or MUST_NOT) and a FullTextQuery to apply. z!list[tuple[Occur, FullTextQuery]]queriesr0rKctjSr~)rKrUrbs r;rdzBooleanQuery.query_typeCs  ((r=Nro)rErFrGrrHrdrIr=r;rjrj4sB  /...))))))r=rjc,eZdZUdZdZded<ded<dS)FullTextSearchQueryaMA LanceDB Full Text Search Query Attributes ---------- columns: List[str] The columns to search If None, then the table should select the column automatically. query: str | FullTextQuery If a string, it is treated as a MatchQuery. If a FullTextQuery object, it is used directly. NzOptional[List[str]]rzUnion[str, FullTextQuery]rs)rErFrGrrrHrIr=r;rrGs;  $(G''''$$$$$$r=rcreZdZUdZdZded<dZded<dZded<dZd ed <dZ d ed <dZ d ed<dZ ded<dZ ded<dZ d ed<dZd ed<dZded<dZded<dZd ed<dZd ed<dZd ed<dZd ed<dZd ed<dZd ed<dZded<ed)d#Zejd$krGd%d&ZdSd'd(iZdS)*r$aA LanceDB Query Queries are constructed by the `Table.search` method. This class is a python representation of the query. Normally you will not need to interact with this class directly. You can build up a query and execute it using collection methods such as `to_batches()`, `to_arrow()`, `to_pandas()`, etc. However, you can use the `to_query()` method to get the underlying query object. This can be useful for serializing a query or using it in a different context. Attributes ---------- filter : Optional[str] sql filter to refine the query with limit : Optional[int] The limit on the number of results to return. If this is a vector or FTS query, then this is required. If this is a plain SQL query, then this is optional. offset: Optional[int] The offset to start fetching results from This is ignored for vector / FTS search (will be None). columns : Optional[Union[List[str], Dict[str, str]]] which columns to return in the results This can be a list of column names or a dictionary. If it is a dictionary, then the keys are the column names and the values are sql expressions to use to calculate the result. If this is None then all columns are returned. This can be expensive. with_row_id : Optional[bool] if True then include the row id in the results vector : Optional[Union[List[float], List[List[float]], pa.Array, List[pa.Array]]] the vector to search for, if this a vector search or hybrid search. It will be None for full text search and plain SQL filtering. vector_column : Optional[str] the name of the vector column to use for vector search If this is None then a default vector column will be used. distance_type : Optional[str] the distance type to use for vector search This can be l2 (default), cosine and dot. See [metric definitions][search] for more details. If this is not a vector search this will be None. postfilter : bool if True then apply the filter after vector / FTS search. This is ignored for plain SQL filtering. nprobes : Optional[int] The number of IVF partitions to search. If this is None then a default number of partitions will be used. - A higher number makes search more accurate but also slower. - See discussion in [Querying an ANN Index][querying-an-ann-index] for tuning advice. Will be None if this is not a vector search. refine_factor : Optional[int] Refine the results by reading extra elements and re-ranking them in memory. - A higher number makes search more accurate but also slower. - See discussion in [Querying an ANN Index][querying-an-ann-index] for tuning advice. Will be None if this is not a vector search. lower_bound : Optional[float] The lower bound for distance search Only results with a distance greater than or equal to this value will be returned. This will only be set on vector search. upper_bound : Optional[float] The upper bound for distance search Only results with a distance less than or equal to this value will be returned. This will only be set on vector search. ef : Optional[int] The size of the nearest neighbor list maintained during HNSW search This will only be set on vector search. full_text_query : Optional[Union[str, dict]] The full text search query This can be a string or a dictionary. A dictionary will be used to search multiple columns. The keys are the column names and the values are the search queries. This will only be set on FTS or hybrid queries. fast_search: Optional[bool] Skip a flat search of unindexed data. This will improve search performance but search results will not include unindexed data. The default is False N Optional[str] vector_columnziAnnotated[Optional[Union[List[float], List[List[float]], pa.Array, List[pa.Array]]], ensure_vector_query]vectorzOptional[Union[str, Expr]]filterOptional[bool] postfilterzOptional[FullTextSearchQuery]full_text_query Optional[int]limit distance_typez7Optional[Union[List[str], Dict[str, Union[str, Expr]]]]rminimum_nprobesmaximum_nprobesOptional[float] lower_bound upper_bound refine_factor with_row_idoffset fast_searchefbypass_vector_indexOptional[List[ColumnOrdering]]order_byreqr#r0r,c0|}|j|_|j|_|j|_|j|_|j|_|j|_|j|_ |j |_ |j |_ |j |_ |j|_|j|_|j|_|j|_|j|_|j|_|j|_|jd|jD|_|jt-d|j|_|S)Nc&g|]}tdi|SrI)r?.0os r; z$Query.from_inner..s&HHHan11q11HHHr=)rrs)rrrfull_text_searchrselectrrrtr query_vectorrrrrrrrrrrrr)clsrrss r; from_innerzQuery.from_innersi z z # 4  O!j' !/ # 3 # 3OO6!/$'$;!> < #HH3<HHHEN   +$7*%%%E ! r=ceZdZdZdS) Query.ConfigTN)rErFrGarbitrary_types_allowedrIr=r;Configr%s&* # # #r=rrT)rr#r0r,)rErFrGrrrHrrrrrrrrrrrrrrrrrr classmethodrrmajorr model_configrIr=r;r$r$YsccL$(M''''      *.F----"&J%%%%6:O9999 E$(M''''HLGKKKK &*O))))&*O))))$(K''''$(K''''$(M''''#'K&&&&!F    #'K&&&&B+/..../3H3333[<!! + + + + + + + + + +248 r=r$ceZdZdZe dSdTdZedZedZdUdZe j dde ddVdZ dWdddXd!Z edddYd#Ze dWdddZd'Zddd[d)Zddd\d-Zddd]d/Zd^d2Zd_d5Zd`d8Zdadbd=Zdcd?ZdddedCZdfdFZdgdGZdhdJZdidMZedjdPZedkdRZdS)lLanceQueryBuilderzAn abstract query builder. Subclasses are defined for vector search, full text search, hybrid, and plain SQL filtering. Ntable'Table'rs:Optional[Union[np.ndarray, str, 'PIL.Image.Image', Tuple]]rdr@vector_column_nameordering_field_namer fts_columnsOptional[Union[str, List[str]]]rrBr0r,c|!ddl}|dtd|dkrt||||S|t |St |t r|nd} |||||\}}|dkrt||||St |t tfrt|||||St |tr!tj |tj }nYt |tjr |tj }nt!d t#|t%|||| |S) a Create a query builder based on the given query and query type. Parameters ---------- table: Table The table to query. query: Optional[Union[np.ndarray, str, "PIL.Image.Image", Tuple]] The query to use. If None, an empty query builder is returned which performs simple SQL filtering. query_type: str The type of query to perform. One of "vector", "fts", "hybrid", or "auto". If "auto", the query type is inferred based on the query. vector_column_name: str The name of the vector column to use for vector search. ordering_field_name: Optional[str] .. deprecated:: 0.27.0 Use ``order_by()`` method instead. fts_columns: Optional[Union[str, List[str]]] The columns to search in for full text search. fast_search: bool Skip flat search of unindexed data. NrzBordering_field_name is deprecated, use .order_by() method instead.r) stacklevelhybridr)rrr)dtypezUnsupported query type: )warningswarnDeprecationWarningLanceHybridQueryBuilderLanceEmptyQueryBuilderr3r@_resolve_queryr`LanceFtsQueryBuilderr4nparrayfloat32ndarrayastype TypeErrortypeLanceVectorQueryBuilder) rrrsrdrrrrr str_querys r;createzLanceQueryBuilder.create0sD  * OOO MMT"      ! !*u0k  =)%00 0(s33=EE  .. 5*&8  z  ! !*u0k  ec=1 2 2 '$7''   eT " " FHU"*555EE rz * * FLL,,EEDtE{{DDEE E& 5,i   r=c|dkr?t|ttfstdt |||fS|dkr||||}||fS|dkrit|t tjfr|dfS|j |}|$|j |d}|dfS|dfStd|)Nftsz/'fts' query must be a string or FullTextQuery: rautorz8Invalid query_type, must be 'vector', 'fts', or 'auto': )r3r@r`rr_query_to_vectorr4rrembedding_functionsgetfunction#compute_query_embeddings_with_retryr6)rrrsrdrconfs r;rz LanceQueryBuilder._resolve_querys   ec=%9:: Sd5kkSS*$ $ 8 # #((7IJJE*$ $ 6 ! !%$ !344 (h&0445GHH# MMMeTTUVWE (?* %<'W:WW r=ct|ttjfr|S|j|}| |j|dSd|}t|)NrzNo embedding function for ) r3r4rrrrrrr6)rrrsrrmsgs r;rz"LanceQueryBuilder._query_to_vectorsr edBJ/ 0 0 L(,,-?@@  =DDUKKAN NC/ACCCS// !r=c||_d|_d|_d|_d|_d|_d|_d|_d|_d|_ d|_ d|_ dSr~) _table_limit_offset_columns_where _postfilter _with_row_id_vector_text_ef_bypass_vector_index _order_by)rcrs r;__init__zLanceQueryBuilder.__init__s]        $(!r=z0.3.1z0.4.0zUse to_pandas() instead) deprecated_in removed_incurrent_versiondetails'pd.DataFrame'c*|S)ae *Deprecated alias for `to_pandas()`. Please use `to_pandas()` instead.* Execute the query and return the results as a pandas DataFrame. In addition to the selected columns, LanceDB also returns a vector and also the "_distance" column which is the distance between the query vector and the returned vector. ) to_pandasrbs r;to_dfzLanceQueryBuilder.to_dfs~~r=timeoutflattenOptional[Union[int, bool]]rOptional[timedelta]c dt|||}|jdi|S)aT Execute the query and return the results as a pandas DataFrame. In addition to the selected columns, LanceDB also returns a vector and also the "_distance" column which is the distance between the query vector and the returned vector. Parameters ---------- flatten: Optional[Union[int, bool]] If flatten is True, flatten all nested columns. If flatten is an integer, flatten the nested columns up to the specified depth. If unspecified, do not flatten the nested columns. timeout: Optional[timedelta] The maximum time to wait for the query to complete. If None, wait indefinitely. **kwargs Forwarded to pyarrow.Table.to_pandas after query execution and optional flattening. rrIr to_arrowr)rcrrkwargstbls r;rzLanceQueryBuilder.to_pandass96dmmGm<.4s%SSS  SSSr=rrrcrrs ` r; to_pydanticzLanceQueryBuilder.to_pydantic#s:"TSSS g (F(F(P(P(R(RSSSSr='pl.DataFrame'cRddl}|j||S)a Execute the query and return the results as a Polars DataFrame. In addition to the selected columns, LanceDB also returns a vector and also the "_distance" column which is the distance between the query vector and the returned vector. Parameters ---------- timeout: Optional[timedelta] The maximum time to wait for the query to complete. If None, wait indefinitely. rNrpolars from_arrowr rcrpls r; to_polarszLanceQueryBuilder.to_polars6s0 r}T]]7];;<<Vq[[DLL!DL r=r-Union[list[str], dict[str, Union[str, Expr]]]ct|tst|tr||_nt d|S)aSet the columns to return. Parameters ---------- columns: list of str, or dict of str to str or Expr List of column names to be fetched. Or a dictionary of column names to SQL expressions or :class:`~lancedb.expr.Expr` objects. All columns are fetched if None or unspecified. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. z&columns must be a list or a dictionary)r3r4dictrr6rcrs r;rzLanceQueryBuilder.selectxsF gt $ $ G 7D(A(A G#DMMEFF F r=TwhereUnion[str, Expr] prefilterc$||_| |_|S)aSet the where clause. Parameters ---------- where: str or :class:`~lancedb.expr.Expr` The filter condition. Can be a SQL string or a type-safe :class:`~lancedb.expr.Expr` built with :func:`~lancedb.expr.col` and :func:`~lancedb.expr.lit`. prefilter: bool, default True If True, apply the filter before vector search, otherwise the filter is applied on the result of vector search. This feature is **EXPERIMENTAL** and may be removed and modified without warning in the future. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. rrrcr8r:s r;r8zLanceQueryBuilder.wheres( (= r=rc||_|S)aSet whether to return row ids. Parameters ---------- with_row_id: bool If True, return _rowid column in the results. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. )r)rcrs r;rzLanceQueryBuilder.with_row_ids( r=Fverboserc^|j||S)Return the execution plan for this query. Examples -------- >>> import lancedb >>> db = lancedb.connect("./.lancedb") >>> table = db.create_table("my_table", [{"vector": [99.0, 99]}]) >>> query = [100, 100] >>> plan = table.search(query).explain_plan(True) >>> print(plan) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE ProjectionExec: expr=[vector@0 as vector, _distance@2 as _distance] GlobalLimitExec: skip=0, fetch=10 FilterExec: _distance@2 IS NOT NULL SortExec: TopK(fetch=10), expr=[_distance@2 ASC NULLS LAST, _rowid@1 ASC NULLS LAST], preserve_partitioning=[false] KNNVectorDistance: metric=l2 LanceRead: uri=..., projection=[vector], ... Parameters ---------- verbose : bool, default False Use a verbose output format. Returns ------- plan : str r?)r _explain_planto_query_objectrcr?s r; explain_planzLanceQueryBuilder.explain_plans+6{(()=)=)?)?(QQQr=orderingrc||_|S)a_ Set the ordering for the results. Parameters ---------- ordering: Optional[List[ColumnOrdering]] The ordering to use for the results. If None, then the default ordering will be used. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. )rrcrGs r;rzLanceQueryBuilder.order_bys" r=cZ|j|S)aG Run the query and return its execution plan with runtime metrics. This returns detailed metrics for each step, such as elapsed time, rows processed, bytes read, and I/O stats. It is useful for debugging and performance tuning. Examples -------- >>> import lancedb >>> db = lancedb.connect("./.lancedb") >>> table = db.create_table("my_table", [{"vector": [99.0, 99]}]) >>> query = [100, 100] >>> plan = table.search(query).analyze_plan() >>> print(plan) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE AnalyzeExec verbose=true, elapsed=..., metrics=... TracedExec, elapsed=..., metrics=... ProjectionExec: elapsed=..., expr=[...], metrics=[output_rows=..., elapsed_compute=..., output_bytes=...] GlobalLimitExec: elapsed=..., skip=0, fetch=10, metrics=[output_rows=..., elapsed_compute=..., output_bytes=...] FilterExec: elapsed=..., _distance@2 IS NOT NULL, metrics=[...] SortExec: elapsed=..., TopK(fetch=10), expr=[...], preserve_partitioning=[...], metrics=[output_rows=..., elapsed_compute=..., output_bytes=..., row_replacements=...] KNNVectorDistance: elapsed=..., metric=l2, metrics=[output_rows=..., elapsed_compute=..., output_bytes=..., output_batches=...] LanceRead: elapsed=..., uri=..., projection=[vector], num_fragments=..., range_before=None, range_after=None, row_id=true, row_addr=false, full_filter=--, refine_filter=--, metrics=[output_rows=..., elapsed_compute=..., output_bytes=..., fragments_scanned=..., ranges_scanned=1, rows_scanned=1, bytes_read=..., iops=..., requests=..., task_wait_time=...] Returns ------- plan : str The physical query execution plan with runtime metrics. )r _analyze_planrDrbs r; analyze_planzLanceQueryBuilder.analyze_plans'V{(()=)=)?)?@@@r=rUnion[np.ndarray, list]ct)zSet the vector to search for. Parameters ---------- vector: np.ndarray or list The vector to search for. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. rrcrs r;rzLanceQueryBuilder.vectors "!r=textstr | FullTextQueryct)aFSet the text to search for. Parameters ---------- text: str | FullTextQuery If a string, it is treated as a MatchQuery. If a FullTextQuery object, it is used directly. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. rrcrPs r;rPzLanceQueryBuilder.text! "!r=rerankerrct)zRerank the results using the specified reranker. Parameters ---------- reranker: Reranker The reranker to use. Returns ------- The LanceQueryBuilder object. rrcrUs r;rerankzLanceQueryBuilder.rerank1rTr=r$ct)zReturn a serializable representation of the query Returns ------- Query The serializable representation of the query rrbs r;rDz!LanceQueryBuilder.to_query_objectAs "!r=NNN)rrrsrrdr@rr@rrrrrrBr0r,)rr)r0rr~rrrrr0rrrr0rrrrrr0rrrr0r)rrrrr0r rrr0r')rr/r0r,rrwr0r,)rr4r0r,T)r8r9r:rBr0r,)rrBr0r,Fr?rr0r@rGrr0r,rp)rrMr0r,)rPrQr0r,)rUrr0r,r0r$) rErFrGrrrrrr deprecation deprecatedrrrrr rrr&r.rrrr8rrFrrLrrPrXrDrIr=r;rr+s.27; T T T T [T l[6""["    [#)       /3'(, ''''''<9="""""^""%)" (, """""^"*9=::::::"AETTTTTT&;?======"<&,0 RRRRR:$+A+A+A+AZ " " " """""  " " "^ """"^"""r=rceZdZdZ d;d<fd Zd=dZd>dZd?dZd@dZdAdZ d;dBdZ dCd!Z dDd#Z dEd%Z dd&dFd*ZdGd,Z dHdd&dId0Z dHdJd4Z dHdKd8ZdLd9ZdLd:ZxZS)Mra| Examples -------- >>> import lancedb >>> data = [{"vector": [1.1, 1.2], "b": 2}, ... {"vector": [0.5, 1.3], "b": 4}, ... {"vector": [0.4, 0.4], "b": 6}, ... {"vector": [0.4, 0.4], "b": 10}] >>> db = lancedb.connect("./.lancedb") >>> table = db.create_table("my_table", data=data) >>> (table.search([0.4, 0.4]) ... .distance_type("cosine") ... .where("b < 10") ... .select(["b", "vector"]) ... .limit(2) ... .to_pandas()) b vector _distance 0 6 [0.4, 0.4] 0.000000 1 2 [1.1, 1.2] 0.000944 Nrrrs*Union[np.ndarray, list, 'PIL.Image.Image']rr@rrrrBct|||_d|_d|_d|_d|_d|_d|_||_ d|_ d|_ ||_ ||_ dSr~)superr_query_distance_type_minimum_nprobes_maximum_nprobes _lower_bound _upper_bound_refine_factor_vector_columnr _reranker _str_query _fast_search)rcrrsrrr __class__s r;rz LanceVectorQueryBuilder.__init__cs  " $ $  "+#'r=metricLiteral['l2', 'cosine', 'dot']r0c,||SaSet the distance metric to use. This is an alias for distance_type() and may be deprecated in the future. Please use distance_type() instead. Parameters ---------- metric: "l2" or "cosine" or "dot" The distance metric to use. By default "l2" is used. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. rrcrxs r;rxzLanceVectorQueryBuilder.metricy !!&)))r=r'LanceVectorQueryBuilder'c8||_|SaSet the distance metric to use. When performing a vector search we try and find the "nearest" vectors according to some kind of distance metric. This parameter controls which distance metric to use. Note: if there is a vector index then the distance type used MUST match the distance type used to train the vector index. If this is not done then the results will be invalid. Parameters ---------- distance_type: "l2" or "cosine" or "dot" The distance metric to use. By default "l2" is used. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. lowerrmrcrs r;rz%LanceVectorQueryBuilder.distance_type.,1133 r=nprobesrwc"||_||_|S)aSet the number of probes to use. Higher values will yield better recall (more likely to find vectors if they exist) at the expense of latency. See discussion in [Querying an ANN Index][querying-an-ann-index] for tuning advice. This method sets both the minimum and maximum number of probes to the same value. See `minimum_nprobes` and `maximum_nprobes` for more fine-grained control. Parameters ---------- nprobes: int The number of probes to use. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. rnrorcrs r;rzLanceVectorQueryBuilder.nprobess.!( ' r=rc||_|S)zSet the minimum number of probes to use. See `nprobes` for more details. These partitions will be searched on every vector query and will increase recall at the expense of latency. rnrcrs r;rz'LanceVectorQueryBuilder.minimum_nprobess!0 r=rc||_|SaSet the maximum number of probes to use. See `nprobes` for more details. If this value is greater than `minimum_nprobes` then the excess partitions will be searched only if we have not found enough results. This can be useful when there is a narrow filter to allow these queries to spend more time searching and avoid potential false negatives. If this value is 0 then no limit will be applied and all partitions could be searched if needed to satisfy the limit. rorcrs r;rz'LanceVectorQueryBuilder.maximum_nprobess!0 r=rrrc"||_||_|S)aSet the distance range to use. Only rows with distances within range [lower_bound, upper_bound) will be returned. Parameters ---------- lower_bound: Optional[float] The lower bound of the distance range. upper_bound: Optional[float] The upper bound of the distance range. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. rprqrcrrs r;distance_rangez&LanceVectorQueryBuilder.distance_ranges((' r=rc||_|S)aSet the number of candidates to consider during search. Higher values will yield better recall (more likely to find vectors if they exist) at the expense of latency. This only applies to the HNSW-related index. The default value is 1.5 * limit. Parameters ---------- ef: int The number of candidates to consider during search. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. rrcrs r;rzLanceVectorQueryBuilder.efs& r=rc||_|S)a)Set the refine factor to use, increasing the number of vectors sampled. As an example, a refine factor of 2 will sample 2x as many vectors as requested, re-ranks them, and returns the top half most relevant results. See discussion in [Querying an ANN Index][querying-an-ann-index] for tuning advice. Parameters ---------- refine_factor: int The refine factor to use. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. rrrcrs r;rz%LanceVectorQueryBuilder.refine_factor s&, r= pa.SchemacZ|j|Sb Return the output schema for the query This does not execute the query. r_output_schemarDrbs r; output_schemaz%LanceVectorQueryBuilder.output_schema & {))$*>*>*@*@AAAr=rrrrcR||S)rrrread_allrs r;r z LanceVectorQueryBuilder.to_arrow(s$w//88:::r=r$ct|jtr|jn|j}t|dtjr d|D}t did|d|jd|jd|j d|j d|j d |j d |j d |jd |jd |jd|jd|jd|jd|jd|jd|jd|jS)zU Build a Query object This can be used to serialize a query rc6g|]}|SrItolistrvs r;rz;LanceVectorQueryBuilder.to_query_object..A 111Qahhjj111r=rrrrrrrrrrrrrrrrrrrI)r3rlr4rrrr$rrrrmrrnrorprqrrrsrrrvrrrrOs r;rDz'LanceVectorQueryBuilder.to_query_object9s| !+4; = =W4;CUCUCWCW fQi , , 211&111F   6 ;; '' ++  --  MM  !11 !11 )) )) -- -- )) << )) xx! "!% 9 9# $^^%  r=rrrc6t|jtr|jn|j}t|dtjr d|D}|}|j|||}|j z| }|j |j |}t|tj|j|}|S)a Execute the query and return the result as a RecordBatchReader object. Parameters ---------- batch_size: int The maximum number of selected records in a RecordBatch object. timeout: timedelta, default None The maximum time to wait for the query to complete. If None, wait indefinitely. Returns ------- pa.RecordBatchReader rc6g|]}|SrIrrs r;rz6LanceVectorQueryBuilder.to_batches..orr=rr)r3rlr4rrrrDr_execute_queryrtr rerank_vectorrurr8RecordBatchReader from_batchesschemar)rcrrrrs result_setrs_tables r;rz"LanceVectorQueryBuilder.to_batchesWs,!+4; = =W4;CUCUCWCW fQi , , 211&111F$$&&[// j'0   > %!**,,H55doxPPJ !* - - --::!:#8#8#:#:Jr=r8r9r:c(||_|| |_|S)aHSet the where clause. Parameters ---------- where: str or :class:`~lancedb.expr.Expr` The filter condition. Can be a SQL string or a type-safe :class:`~lancedb.expr.Expr` built with :func:`~lancedb.expr.col` and :func:`~lancedb.expr.lit`. prefilter: bool, default True If True, apply the filter before vector search, otherwise the filter is applied on the result of vector search. Returns ------- LanceQueryBuilder The LanceQueryBuilder object. r<r=s r;r8zLanceVectorQueryBuilder.wheres (  #,}D  r=rUr query_stringc||_|j|td|$t|tstd||n|j|_|jdkr|d|S)aRerank the results using the specified reranker. Parameters ---------- reranker: Reranker The reranker to use. query_string: Optional[str] The query to use for reranking. This needs to be specified explicitly here as the query used for vector search may already be vectorized and the reranker requires a string query. This is only required if the query used for vector search is not a string. Note: This doesn't yet support the case where the query is multimodal or a list of vectors. Returns ------- LanceVectorQueryBuilder The LanceQueryBuilder object. Nz The query used for vector search is not a string. In this case, the reranker query needs to be specified explicitly. z0Reranking currently only supports string queriesallT)rtrur6r3r@scorerrcrUrs r;rXzLanceVectorQueryBuilder.reranks." ? "|';   #J|S,I,I #OPP P*6*B,, >U " "   T " " " r=cd|_|S)a< If this is called then any vector index is skipped An exhaustive (flat) search will be performed. The query vector will be compared to every vector in the table. At high scales this can be expensive. However, this is often still useful. For example, skipping the vector index can give you ground truth results which you can use to calculate your recall to select an appropriate value for nprobes. Returns ------- LanceVectorQueryBuilder The LanceVectorQueryBuilder object. Trrbs r;rz+LanceVectorQueryBuilder.bypass_vector_index%)! r=cd|_|S)a  Skip a flat search of unindexed data. This will improve search performance but search results will not include unindexed data. Returns ------- LanceVectorQueryBuilder The LanceVectorQueryBuilder object. Trvrbs r;rz#LanceVectorQueryBuilder.fast_search! r=NN) rrrsrirr@rrrrB)rxryr0r)rryr0r)rrwr0r)rrwr0r)rrwr0r)rrrrr0r)rrwr0r)rrwr0rr0rr\rer~r])r8r9r:rBr0r)rUrrrr0r)r0r)rErFrGrrrxrrrrrrrrr rDrr8rXrr __classcell__rws@r;rrMs4$( (((((((,****$46    $SW0,,BBBB:>;;;;;;"    B%)& (, &&&&&&R:>4AE$$$$$L$        r=rcpeZdZdZ d"d#fd Zd$d%dZd&dZd'dZd(dZddd)dZ d*d+dZ d,d!Z xZ S)-rz+A builder for full text search for LanceDB.NrrrsrQrrrrrrBct|||_d|_|}d|_||_t |tr|g}||_dS)NF) rkrrl _phrase_queryrtrvr3r@ _fts_columns)rcrrsrrr_rws r;rzLanceFtsQueryBuilder.__init__si  " ' k3 ' ' (&-K'r=T phrase_queryr0c||_|S)a[Set whether to use phrase query. Parameters ---------- phrase_query: bool, default True If True, then the query will be wrapped in quotes and double quotes replaced by single quotes. Returns ------- LanceFtsQueryBuilder The LanceFtsQueryBuilder object. rrcrs r;rz!LanceFtsQueryBuilder.phrase_query* r=cd|_|S)a Skip a flat search of unindexed data. This will improve search performance but search results will not include unindexed data. Returns ------- LanceFtsQueryBuilder The LanceFtsQueryBuilder object. Trrbs r;rz LanceFtsQueryBuilder.fast_searchrr=r$c t|j|j|j|j|jt |j|j|j |j |j  S)Nrsr) rrrrrrrrr) r$rrrrrrrlrrrvrrbs r;rDz$LanceFtsQueryBuilder.to_query_objectsbM;+')/k4+<<)^    r=rcZ|j|Srrrbs r;rz"LanceFtsQueryBuilder.output_schema"rr=rrrrcP|j|j}|jrt |t r6|dr|ds d|d|_n9t |tr$t |tstd| }|j ||}| }|j/|j|j|}t!||S)N"z*Please use PhraseQuery for phrase queries.r)r_ensure_no_legacy_fts_indexrlrr3r@ startswithendswithr`rrrDrrrt rerank_ftsr)rcrrsresultss r;r zLanceFtsQueryBuilder.to_arrow*s  //111    N%%% N'',,/ENN34G4G/".e,,,DKE=11 N*{;; N LMMM$$&&+,,UG,DD""$$ > %n// WEEG !' * * *r=rrc td)Nzto_batches on an FTS queryrrs r;rzLanceFtsQueryBuilder.to_batches>s"">???r=rUrcT||_|jdkr|d|S)aRerank the results using the specified reranker. Parameters ---------- reranker: Reranker The reranker to use. Returns ------- LanceFtsQueryBuilder The LanceQueryBuilder object. rT)rtrrrWs r;rXzLanceFtsQueryBuilder.rerankCs1" >U " "   T " " " r=rZ) rrrsrQrrrrrrBra)rrBr0r)r0rrerr\rrrrr)rUrr0r) rErFrGrrrrrDrr rrXrrs@r;rrs55 .27; (((((((("         BBBB:>*SW@@@@@ r=rc@eZdZddddZdd Zdd Z dddZddZdS)rNrrrr0rcR||S)Nrrrs r;r zLanceEmptyQueryBuilder.to_arrowWs"w//88:::r=r$cht|j|j|j|j|j|jS)N)rrrrrr)r$rrrrrrrbs r;rDz&LanceEmptyQueryBuilder.to_query_objectZs8M;+)<^     r=rc^|}|j|Sr~)rDrr)rcrss r;rz$LanceEmptyQueryBuilder.output_schemads)$$&&{))%000r=rrrcd|}|j|||S)Nr)rDrr)rcrrrss r;rz!LanceEmptyQueryBuilder.to_batcheshs3$$&&{))%JPW)XXXr=rUrc td)aRerank the results using the specified reranker. Parameters ---------- reranker: Reranker The reranker to use. Returns ------- LanceEmptyQueryBuilder The LanceQueryBuilder object. zReranking is not yet supported.rrWs r;rXzLanceEmptyQueryBuilder.rerankns""CDDDr=r\rerrr])rUrr0r)rErFrGr rDrrrXrIr=r;rrVs9=;;;;;;    1111 SWYYYYY E E E E E Er=rc<eZdZdZ dRdSfd ZdTd ZdUdVdZdWdZdddXdZe dYd Z dTdZd#Z e d[d\d(Z e d]d^d,Z ed-fd_d1Zd`d3Zdad5Zdbd7Z dTdcd;Zddd=Zded@ZdfdCZdgdEZdhdHZdidKZdjdLZd]dkdOZdPZdQZxZS)lr A query builder that performs hybrid vector and full text search. Results are combined and reranked based on the specified reranker. By default, the results are reranked using the RRFReranker, which uses reciprocal rank fusion score for reranking. To make the vector and fts results comparable, the scores are normalized. Instead of normalizing scores, the `normalize` parameter can be set to "rank" in the `rerank` method to convert the scores to ranks and then normalize them. Nrrrs#Optional[Union[str, FullTextQuery]]rrrrct|||_||_||_d|_d|_d|_d|_d|_ d|_ d|_ d|_ d|_ dSr~)rkrrlrsr_normrtrnrorrrmrrprq)rcrrsrrrws r;rz LanceHybridQueryBuilder.__init__s  +'  $ $""!  r=c,|||td||n|}t|tttjfstd|p|}|tdt|tt fstd||fS)NzYou can either provide a string query in search() method or set `vector()` and `text()` explicitly for hybrid search.But not both.z0Vector query must be either a string or a vectorz.Text query must be provided for hybrid search.z,Text query must be a string or FullTextQuery)r6r3r@r4rrr`)rcrsrrP vector_query text_querys r;_validate_queryz'LanceHybridQueryBuilder._validate_querys  &"48H   "(!3vv ,dBJ(?@@ QOPP P]U  MNN N*sM&:;; MKLL LZ''r=rrBr0c||_|S)aaSet whether to use phrase query. Parameters ---------- phrase_query: bool, default True If True, then the query will be wrapped in quotes and double quotes replaced by single quotes. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rrs r;rz$LanceHybridQueryBuilder.phrase_queryrr=r$c td)Nz3to_query_object not yet supported on a hybrid queryrrbs r;rDz'LanceHybridQueryBuilder.to_query_objects!"WXXXr=rrrrc  |t5}||jdj|}||jdj|}|}|}dddn #1swxYwY||||j |jj |j |j |j S)NTr fts_resultsvector_resultsnorm fts_queryrUr with_row_ids)_create_query_buildersrsubmit _fts_queryrr  _vector_queryresult_combine_hybrid_resultsrrlrtrr)rcrexecutor fts_future vector_futurerrs r;r z LanceHybridQueryBuilder.to_arrows; ##%%%  ! ! 4X!++D11:G)J%OO"..t44=w,M%++--K*1133N 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4++#)o,^+*,   sBCCCrrrr@rrrwrc|dkr6t|d}t|d}|jdkr|jdkrtj|j|jgtjfdjD}|dtj gtj }|sd|j vr| dg}|Sd}d} d} d} |jdkr|j d} || }|d} || || t|}|jdkr|j d} || } |d} || || t| }||||}t'|d|j vre|ct)j|d| d }t)j||}|j d} || d|}d|j vre| ct)j|d| d }t)j| |} |j d} || d| }|| }|s| dg}|S) Nrank _distance_scorerc ni|]1}|tjg|j2S)r)r8rfieldr)rcolcombined_schemas r; zCLanceHybridQueryBuilder._combine_hybrid_results..sK"?+@+@+E+E+JKKKr=_relevance_scorer_rowidT) skip_nulls)length)r_ranknum_rowsr8 unify_schemasrrnames append_columnrr column_namesdropindexrt set_columnr_normalize_scores rerank_hybridrpcindex_intakeslice)rrrrrUrremptyoriginal_distancesoriginal_scoresoriginal_distance_row_idsoriginal_score_row_ids distance_iscore_irindicesrs @r;rz/LanceHybridQueryBuilder._combine_hybrid_resultss 6>>4::>;WWN177 XNNK  "a ' 'K,@A,E,E .& (:;OH.4E ''"BHRbjll$C$C$CE  /H0B$B$B H:..L!$(!!%  "Q & &'4::;GGJ!/!6!6z!B!B (6(=(=h(G(G %+66$$Z00'99:LMMN  ! # #!.44X>>G)0099O%0%7%7%A%A "%00!!'**'99/JJK ((NKPPg&&& '. . .3E3Qk!#<G"$);W!E!E  -33K@@J(([BTUUG w+ + +0Kk!#9dG!gow??O*00::G(((OLLG--u--- /llH:..Gr=rrc td)Nz.to_batches not yet supported on a hybrid queryrrs r;rz"LanceHybridQueryBuilder.to_batches9s""RSSSr=TrrtrCc t|dkr|S||}tj|}|s |ddd}tj|}tjt|dz||<|j|}| ||tj |tj }|S)Nrrr) r5rtto_numpyrargsort empty_likearangerrrr8rr)rrtrCscores sort_indicesranks _score_idxs r;rzLanceHybridQueryBuilder._rank>s w<<1  N''0022z&))  .'"-L l++ iF 44q8l)//77 $$ RZ\\ B B B  r=Fr,pa.Arrayc:t|dkr|Stj|\}}tj||}tj|t jds)tj tj|||}nNtj|t jdstj||}|rtjd|}|S)Nrgr) r5rmin_maxvaluessubtractequalr8scalaras_pydivide)r,invertminmaxrngs r;rz)LanceHybridQueryBuilder._normalize_scoresPs v;;!  M:f%%,,..Sk#s##xRYs^^,,2244 .Yr{6377==FF#ry~~..4466 .[--F  ,[F++F r=rrUr normalizec|dvrtd|r$t|tstd||_||_|jdkr|d|S)a Rerank the hybrid search results using the specified reranker. The reranker must be an instance of Reranker class. Parameters ---------- reranker: Reranker, default RRFReranker() The reranker to use. Must be an instance of Reranker class. normalize: str, default "score" The method to normalize the scores. Can be "rank" or "score". If "rank", the scores are converted to ranks and then normalized. If "score", the scores are normalized directly. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rr$normalize must be 'rank' or 'score'./reranker must be an instance of Reranker class.rT)r6r3rrrtrrrcrUr=s r;rXzLanceHybridQueryBuilder.rerankcs}, - - -CDD D  PJx:: PNOO O ! >U " "   T " " " r=rc"||_||_|S)a Set the number of probes to use for vector search. Higher values will yield better recall (more likely to find vectors if they exist) at the expense of latency. Parameters ---------- nprobes: int The number of probes to use. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rrs r;rzLanceHybridQueryBuilder.nprobess"!( ' r=rc||_|S)zZSet the minimum number of probes to use. See `nprobes` for more details. rrs r;rz'LanceHybridQueryBuilder.minimum_nprobes !0 r=rc||_|S)zZSet the maximum number of probes to use. See `nprobes` for more details. rrs r;rz'LanceHybridQueryBuilder.maximum_nprobesrEr=rrrc"||_||_|S)a Set the distance range to use. Only rows with distances within range [lower_bound, upper_bound) will be returned. Parameters ---------- lower_bound: Optional[float] The lower bound of the distance range. upper_bound: Optional[float] The upper bound of the distance range. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rrs r;rz&LanceHybridQueryBuilder.distance_ranges*(' r=rc||_|S)a Set the number of candidates to consider during search. Higher values will yield better recall (more likely to find vectors if they exist) at the expense of latency. This only applies to the HNSW-related index. The default value is 1.5 * limit. Parameters ---------- ef: int The number of candidates to consider during search. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rrs r;rzLanceHybridQueryBuilder.efs( r=rxryc,||Sr{r|r}s r;rxzLanceHybridQueryBuilder.metricr~r=r'LanceHybridQueryBuilder'c8||_|Srrrs r;rz%LanceHybridQueryBuilder.distance_typerr=rc||_|S)aL Refine the vector search results by reading extra elements and re-ranking them in memory. Parameters ---------- refine_factor: int The refine factor to use. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. rrs r;rz%LanceHybridQueryBuilder.refine_factors, r=rrMc||_|Sr~)rrOs r;rzLanceHybridQueryBuilder.vectors  r=rPrQc||_|Sr~)rrSs r;rPzLanceHybridQueryBuilder.texts  r=cd|_|S)a< If this is called then any vector index is skipped An exhaustive (flat) search will be performed. The query vector will be compared to every vector in the table. At high scales this can be expensive. However, this is often still useful. For example, skipping the vector index can give you ground truth results which you can use to calculate your recall to select an appropriate value for nprobes. Returns ------- LanceHybridQueryBuilder The LanceHybridQueryBuilder object. Trrbs r;rz+LanceHybridQueryBuilder.bypass_vector_index rr=r?rc||jrt|jnd}|j|j|}|j|j|}dd| D}dd| D}|d|d|S)rAz No rerankerrB c3 K|] }d|zV dSz NrIrlines r; z7LanceHybridQueryBuilder.explain_plan..W&#U#UDD4K#U#U#U#U#U#Ur=c3 K|] }d|zV dSrSrIrTs r;rVz7LanceHybridQueryBuilder.explain_plan..X& O O O O O O O Or= ) rrtr@rrCrrDrjoin splitlines)rcr?reranker_label vector_planfts_planindented_vector indented_ftss r;rFz$LanceHybridQueryBuilder.explain_plan2s6 ##%%%04QT^,,,Mk//   . . 0 0'0  ;,, O + + - -w-  ))#U#UK|j |j |j |j |jr>|j |j|j|j|jrL|j |j|j |j|j|j |jr4|j d|jd|jr|jd|jr|j |j|jr|j |j|j|j |j|jr|j |j|jr|j |j|j!r|j "|j#s|j$r&|j %|j#|j$|j&tO|_&dSdS)z7Set up and configure the vector and FTS query builders.rTN)rr)(rrlrrrrrrrrsrrrrrrrr8rrrrrrmrxrnrrorrrrrrrrrprqrrtr)rcrrs r;rz.LanceHybridQueryBuilder._create_query_buildersjs"&"6"6 Ktz# #  i/ K0A   ,, Kt':  5 Kt':   ; /   $ $T[ 1 1 1 O ! !$+ . . . = 2   % %dm 4 4 4 O " "4= 1 1 1 ; E   $ $T[d6F2F G G G O ! !$+43C/C D D D   .   * *4 0 0 0 O ' ' - - -   / O ( ( . . .   ;   % %d&9 : : :   F   . .t/D E E E  ,   . .t/D E E E   B   , ,T-@ A A A 8 ,   ! !$( + + +  $ 5   2 2 4 4 4    1    - - -4;L .    > !(]]DNNN " !r=rZ)rrrsrrrrrrr~)rrBr0rrer\)rrrrrr@rr@rrwrrBr0rrra)rrrtr@rCrBrb)r,r0r0r0)rUrr=r@r0r)rrwr0r)rrwr0r)rrwr0r)rrrrr0r)rrwr0r)rxryr0r)rryr0rJ)rrwr0r)rrMr0r)rPrQr0r)r0rrc)rErFrGrrrrrDr  staticmethodrrrrrrXrrrrrrxrrrrPrrFrLrrrs@r;rr~s  6:'+7; !!!!!!!*((((("YYYY:>      ,YYY\YxSWTTTTT \"\()[]]      D*SW2.****$4$$'J'J'J'J'JR " " "0+0+0+0+0+0+0+r=rceZdZdZd+dZd,dZd-d Zd.d Zd d dd/dZd0dZ d1d2dZ d1d3dZ d4d5dZ d1d6d Z d d!d7d%Zd8d9d)Zd*Zd S):AsyncQueryBasezL Base class for all async queries (take, scan, vector, fts, hybrid) inner3Union[LanceQuery, LanceVectorQuery, LanceTakeQuery]c||_dS)z Construct an AsyncQueryBase This method is not intended to be called directly. Instead, use the [AsyncTable.query][lancedb.table.AsyncTable.query] method to create a query. N_innerrcrjs r;rzAsyncQueryBase.__init__s r=r0r$cdt|jS)z Convert the query into a query object This is currently experimental but can be useful as the query object is pure python and more easily serializable. )r$rrnto_query_requestrbs r;rDzAsyncQueryBase.to_query_objects& < < > >???r=r Union[List[str], dict[str, str]]r,c2t|tr5td|Dr|j|nKt|t r&td|Dr t d|DrAddlm fd| D}|j |ntd|Dr:|j t| nJtdtd | Dztd |S) ` Return only the specified columns. By default a query will return all columns from the table. However, this can have a very significant impact on latency. LanceDb stores data in a columnar fashion. This means we can finely tune our I/O to select exactly the columns we need. As a best practice you should always limit queries to the columns that you need. If you pass in a list of column names then only those columns will be returned. You can also use this method to create new "dynamic" columns based on your existing columns. For example, you may not care about "a" or "b" but instead simply want "a + b". This is often seen in the SELECT clause of an SQL query (e.g. `SELECT a+b FROM my_table`). To create dynamic columns you can pass in a dict[str, str]. A column will be returned for each entry in the map. The key provides the name of the column. The value is an SQL string used to specify how the column is calculated. For example, an SQL query might state `SELECT a + b AS combined, c`. The equivalent input to this method would be `{"combined": "a + b", "c": "c"}`. Columns will always be returned in the order given, even if that order is different than the order used when adding the data. c3@K|]}t|tVdSr~r3r@)rcs r;rVz(AsyncQueryBase.select..s,,Q,QAZ3-?-?,Q,Q,Q,Q,Q,Qr=c3@K|]}t|tVdSr~rv)rks r;rVz(AsyncQueryBase.select..s,.S.Saz!S/A/A.S.S.S.S.S.Sr=c3@K|]}t|tVdSr~)r3rrs r;rVz(AsyncQueryBase.select..s,AA1:a&&AAAAAAr=r)_coercec:g|]\}}||jfSrIrm)rryrr{s r;rz)AsyncQueryBase.select..s-LLLDAq!WWQZZ./LLLr=c3@K|]}t|tVdSr~rvrs r;rVz(AsyncQueryBase.select..s,BBAZ3''BBBBBBr=z%dict values must be str or Expr, got c4i|]\}}|t|SrIr)rryrs r;r z)AsyncQueryBase.select..s$BBB$!Q1d1ggBBBr=z0columns must be a list of column names or a dict)r3r4rrnselect_columnsr6anyr3exprr{items select_exprrrr@)rcrpairsr{s @r;rzAsyncQueryBase.selects8 gt $ $ P,Q,Q,Q,Q,Q)Q)Q P K & &w / / / /  & & P3.S.S7.S.S.S+S+S PAA0@0@AAAAA ))))))LLLLGMMOOLLL ''....BB1A1ABBBBB  ""4 #8#89999;BB'--//BBBCCD NOO O r=c8|j|Sz; Include the _rowid column in the results. rnrrbs r;rzAsyncQueryBase.with_row_id !!! r=Nmax_batch_lengthrrrrrrcdKt|j||d{VS) Execute the query and return the results as an Apache Arrow RecordBatchReader. Parameters ---------- max_batch_length: Optional[int] The maximum number of selected records in a single RecordBatch object. If not specified, a default batch length is used. It is possible for batches to be smaller than the provided length if the underlying data is stored in smaller chunks. timeout: Optional[timedelta] The maximum time to wait for the query to complete. If not specified, no timeout is applied. If the query does not complete within the specified time, an error will be raised. rN)rrnexecute)rcrrs r;rzAsyncQueryBase.to_batchessW,&+%%!17&         r=rcDK|jd{VS)rN)rnrrbs r;rzAsyncQueryBase.output_schema s. [..000000000r=rcK||d{V}tj|d{V|jS)G Execute the query and collect the results into an Apache Arrow Table. This method will collect all results into memory before returning. If you expect a large number of results, you may want to use [to_batches][lancedb.query.AsyncQueryBase.to_batches] Parameters ---------- timeout: Optional[timedelta] The maximum time to wait for the query to complete. If not specified, no timeout is applied. If the query does not complete within the specified time, an error will be raised. rN)r)rr8r)rrr)rcr batch_iters r;r zAsyncQueryBase.to_arrow sr ??7?;;;;;;;; x$$%%'' ' ' ' ' ' ' 0A%   r=rcbK||d{VS)e Execute the query and return the results as a list of dictionaries. Each list entry is a dictionary with the selected column names as keys, or all table columns if `select` is not called. The vector and the "_distance" fields are returned whether or not they're explicitly selected. Parameters ---------- timeout: Optional[timedelta] The maximum time to wait for the query to complete. If not specified, no timeout is applied. If the query does not complete within the specified time, an error will be raised. rNrrs r;rzAsyncQueryBase.to_list# s:mmGm44444444??AAAr=rrrcpKt||d{V|jdi|S) Execute the query and collect the results into a pandas DataFrame. This method will collect all results into memory before returning. If you expect a large number of results, you may want to use [to_batches][lancedb.query.AsyncQueryBase.to_batches] and convert each batch to pandas separately. Examples -------- >>> import asyncio >>> from lancedb import connect_async >>> async def doctest_example(): ... conn = await connect_async("./.lancedb") ... table = await conn.create_table("my_table", data=[{"a": 1, "b": 2}]) ... async for batch in await table.query().to_batches(): ... batch_df = batch.to_pandas() >>> asyncio.run(doctest_example()) Parameters ---------- flatten: Optional[Union[int, bool]] If flatten is True, flatten all nested columns. If flatten is an integer, flatten the nested columns up to the specified depth. If unspecified, do not flatten the nested columns. timeout: Optional[timedelta] The maximum time to wait for the query to complete. If not specified, no timeout is applied. If the query does not complete within the specified time, an error will be raised. **kwargs Forwarded to pyarrow.Table.to_pandas after query execution and optional flattening. rNrIr rcrrr s r;rzAsyncQueryBase.to_pandas4 sXR $---"@"@@@@@@@' J J  r=r'cbKddl}|j||d{VS)a Execute the query and collect the results into a Polars DataFrame. This method will collect all results into memory before returning. If you expect a large number of results, you may want to use [to_batches][lancedb.query.AsyncQueryBase.to_batches] and convert each batch to polars separately. Parameters ---------- timeout: Optional[timedelta] The maximum time to wait for the query to complete. If not specified, no timeout is applied. If the query does not complete within the specified time, an error will be raised. Examples -------- >>> import asyncio >>> import polars as pl >>> from lancedb import connect_async >>> async def doctest_example(): ... conn = await connect_async("./.lancedb") ... table = await conn.create_table("my_table", data=[{"a": 1, "b": 2}]) ... async for batch in await table.query().to_batches(): ... batch_df = pl.from_arrow(batch) >>> asyncio.run(doctest_example()) rNrr)r,s r;r.zAsyncQueryBase.to_polarsa sG@ r}4===#A#AAAAAAABBBr=rrType[LanceModel]List[LanceModel]c|Kfd||d{VDS)av Convert results to a list of pydantic models. Parameters ---------- model : Type[LanceModel] The pydantic model to use. timeout : timedelta, optional The maximum time to wait for the query to complete. If None, wait indefinitely. Returns ------- list[LanceModel] c g|] }di| SrrIr#s r;rz.AsyncQueryBase.to_pydantic.. s2    EELLCLL   r=rNrr%s ` r;r&zAsyncQueryBase.to_pydantic s^$    +/===+I+I%I%I%I%I%I%I$T$T$V$V    r=Fr?rcFK|j|d{VS)tReturn the execution plan for this query. Examples -------- >>> import asyncio >>> from lancedb import connect_async >>> async def doctest_example(): ... conn = await connect_async("./.lancedb") ... table = await conn.create_table("my_table", [{"vector": [99.0, 99.0]}]) ... plan = await table.query().nearest_to([1.0, 2.0]).explain_plan(True) ... print(plan) >>> asyncio.run(doctest_example()) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE ProjectionExec: expr=[vector@0 as vector, _distance@2 as _distance] GlobalLimitExec: skip=0, fetch=10 FilterExec: _distance@2 IS NOT NULL SortExec: TopK(fetch=10), expr=[_distance@2 ASC NULLS LAST, _rowid@1 ASC NULLS LAST], preserve_partitioning=[false] KNNVectorDistance: metric=l2 LanceRead: uri=..., projection=[vector], ... Parameters ---------- verbose : bool, default False Use a verbose output format. Returns ------- plan : str N)rnrFrEs r;rFzAsyncQueryBase.explain_plan s0<[--g666666666r=cDK|jd{VS)rcN)rnrLrbs r;rLzAsyncQueryBase.analyze_plan s.[--/////////r=)rjrkrerrrr0r,r0r,rrrrr0rrr~r\r^rr[r_)rrrrr0rrbr?r)rErFrGrrrDrrrrr rrr.r&rFrLrIr=r;ririsx@@@@....`+/'+       81111     (BBBBB&/3'++++++^(,"C"C"C"C"CJJN      ,77777@00000r=ricTeZdZdZdfd Zdd Zdd ZddZddZddZ ddZ xZ S)AsyncStandardQueryzJ Base class for "standard" async queries (all but take currently) rj#Union[LanceQuery, LanceVectorQuery]cJt|dS)z Construct an AsyncStandardQuery This method is not intended to be called directly. Instead, use the [AsyncTable.query][lancedb.table.AsyncTable.query] method to create a query. Nrkrrcrjrws r;rzAsyncStandardQuery.__init__ s# r= predicater9r0r,ct|tr |j|jn|j||S)a Only return rows matching the given predicate The predicate can be a SQL string or a type-safe :class:`~lancedb.expr.Expr` built with :func:`~lancedb.expr.col` and :func:`~lancedb.expr.lit`. Examples -------- >>> predicate = "x > 10" >>> predicate = "y > 0 AND y < 100" >>> predicate = "x > 5 OR y = 'test'" Filtering performance can often be improved by creating a scalar index on the filter column(s). )r3rrn where_exprr8)rcrs r;r8zAsyncStandardQuery.where sM$ i & & ) K " "9#3 4 4 4 4 K  i ( ( ( r=rrwc:|j||S)z Set the maximum number of results to return. By default, a plain search has no limit. If this method is not called then every valid row from the table will be returned. )rnrr1s r;rzAsyncStandardQuery.limit s %    r=rc:|j||S)z Set the offset for the results. Parameters ---------- offset: int The offset to start fetching results from. )rnrr3s r;rzAsyncStandardQuery.offset s 6""" r=rGrc||jdn$|jd|D|S)z Set the ordering for the results. Parameters ---------- ordering: Optional[List[ColumnOrdering]] The ordering to use for the results. If None, then the default ordering will be used. Nc~g|]:}t|dr|n|;S) model_dump)hasattrrr6rs r;rz/AsyncStandardQuery.order_by.. sK'.a&>&>LALLNNNAFFHHr=)rnrrIs r;rzAsyncStandardQuery.order_by s`   K  & & & & K %     r=c8|j|S)a, Skip searching un-indexed data. This can make queries faster, but will miss any data that has not been indexed. !!! tip You can add new data into an existing index by calling [AsyncTable.optimize][lancedb.table.AsyncTable.optimize]. )rnrrbs r;rzAsyncStandardQuery.fast_search s !!! r=c8|j|S)ax If this is called then filtering will happen after the search instead of before. By default filtering will be performed before the search. This is how filtering is typically understood to work. This prefilter step does add some additional latency. Creating a scalar index on the filter column(s) can often improve this latency. However, sometimes a filter is too complex or scalar indices cannot be applied to the column. In these cases postfiltering can be used instead of prefiltering to improve latency. Post filtering applies the filter to the results of the search. This means we only run the filter on a much smaller set of data. However, it can cause the query to return fewer than `limit` results (or even no results) if none of the nearest results match the filter. Post filtering happens during the "refine stage" (described in more detail in @see {@link VectorQuery#refineFactor}). This means that setting a higher refine factor can often help restore some of the results lost by post filtering. )rnrrbs r;rzAsyncStandardQuery.postfilter$ s$     r=)rjr)rr9r0r,)rrwr0r,r`rdr) rErFrGrrr8rrrrrrrs@r;rr s      0    *    r=rcLeZdZdfd ZeddZdd Z dddZxZS) AsyncQueryrj LanceQuerycXt|||_dS)z Construct an AsyncQuery This method is not intended to be called directly. Instead, use the [AsyncTable.query][lancedb.table.AsyncTable.query] method to create a query. N)rkrrnrs r;rzAsyncQuery.__init__; s(  r=vecUnion[VEC, Tuple]ct|trtj|St|tjrtj|St|tjr|St|tjr|St|trtj|Stj|Sr~) r3r4r8rrrr9 ChunkedArraycombine_chunkstuple)rcrs r;_query_vec_to_arrayzAsyncQuery._query_vec_to_arrayE s c4  !8C== c2: & & !8C== c28 $ $ J c2? + + (%%'' ' c5 ! ! !8C== x}}r=rUnion[VEC, Tuple, List[VEC]]r0AsyncVectorQueryc>|tdt|ttjt jfrt|dkrt|dttjt jfr]d|D}|j |d}|ddD]}| |t|St|j t |S)aC Find the nearest vectors to the given query vector. This converts the query from a plain query to a vector query. This method will attempt to convert the input to the query vector expected by the embedding model. If the input cannot be converted then an error will be thrown. By default, there is no embedding model, and the input should be something that can be converted to a pyarrow array of floats. This includes lists, numpy arrays, and tuples. If there is only one vector column (a column whose data type is a fixed size list of floats) then the column does not need to be specified. If there is more than one vector column you must use [AsyncVectorQuery.column][lancedb.query.AsyncVectorQuery.column] to specify which column you would like to compare with. If no index has been created on the vector column then a vector query will perform a distance comparison between the query vector and every vector in the database and then sort the results. This is sometimes called a "flat search" For small databases, with tens of thousands of vectors or less, this can be reasonably fast. In larger databases you should create a vector index on the column. If there is a vector index then an "approximate" nearest neighbor search (frequently called an ANN search) will be performed. This search is much faster, but the results will be approximate. The query can be further parameterized using the returned builder. There are various ANN search parameters that will let you fine tune your recall accuracy vs search latency. Vector searches always have a [limit][]. If `limit` has not been called then a default `limit` of 10 will be used. Typically, a single vector is passed in as the query. However, you can also pass in multiple vectors. When multiple vectors are passed in, if the vector column is with multivector type, then the vectors will be treated as a single query. Or the vectors will be treated as multiple queries, this can be useful if you want to find the nearest vectors to multiple query vectors. This is not expected to be faster than making multiple queries concurrently; it is just a convenience method. If multiple vectors are passed in then an additional column `query_index` will be added to the results. This column will contain the index of the query vector that the result is nearest to. Nquery_vector can not be NonercBg|]}t|SrIrrrs r;rz)AsyncQuery.nearest_to.. &UUU1Z;;A>>UUUr=r)r6r3r4rrr8r9r5rn nearest_toadd_query_vectorrrrrcr query_vectorsnew_selfrs r;rzAsyncQuery.nearest_toV s f  ;<< < |dBJ%A B B L!!A%%<?T2:rx,HII&VU UUUM{--mA.>??H"122& - -))!,,,,#H-- -# &&z'E'El'S'STT r=NrsrQrUnion[str, List[str], None] AsyncFTSQueryc t|tr|g}|g}t|tr*t|j||dSt|jd|iS)a Find the documents that are most relevant to the given text query. This method will perform a full text search on the table and return the most relevant documents. The relevance is determined by BM25. The columns to search must be with native FTS index (Tantivy-based can't work with this method). By default, all indexed columns are searched, now only one column can be searched at a time. Parameters ---------- query: str The text query to search for. columns: str or list of str, default None The columns to search in. If None, all indexed columns are searched. For now only one column can be searched at a time. Nrrs)r3r@rrnnearest_to_textrcrsrs r;rzAsyncQuery.nearest_to_text s. gs # # iG ?G eS ! !   ++e,P,PQQ T[88'59IJJKKKr=)rjr)rr)rrr0rr~)rsrQrrr0r) rErFrGrrrrrrrs@r;rr: s[ DDDDNRV!L!L!L!L!L!L!L!L!Lr=rcdeZdZdZdfd ZddZefdd ZddZddddfdZ xZ S)rz)A query for full text search for LanceDB.rj LanceFTSQuerycft|||_d|_dSr~)rkrrnrtrs r;rzAsyncFTSQuery.__init__ s-  r=r0r@c4|jSr~)rn get_queryrbs r;rzAsyncFTSQuery.get_query s{$$&&&r=rUrc`|r$t|tstd||_|S)NrA)r3rr6rtrWs r;rXzAsyncFTSQuery.rerank s:  PJx:: PNOO O! r=rrAsyncHybridQueryc|tdt|trt|dkrt|dtt fs]d|D}|j|d}|ddD]}||t|St|jt |S)a In addition doing text search on the LanceDB Table, also find the nearest vectors to the given query vector. This converts the query from a FTS Query to a Hybrid query. Results from the vector search will be combined with results from the FTS query. This method will attempt to convert the input to the query vector expected by the embedding model. If the input cannot be converted then an error will be thrown. By default, there is no embedding model, and the input should be something that can be converted to a pyarrow array of floats. This includes lists, numpy arrays, and tuples. If there is only one vector column (a column whose data type is a fixed size list of floats) then the column does not need to be specified. If there is more than one vector column you must use [AsyncVectorQuery.column][lancedb.query.AsyncVectorQuery.column] to specify which column you would like to compare with. If no index has been created on the vector column then a vector query will perform a distance comparison between the query vector and every vector in the database and then sort the results. This is sometimes called a "flat search" For small databases, with tens of thousands of vectors or less, this can be reasonably fast. In larger databases you should create a vector index on the column. If there is a vector index then an "approximate" nearest neighbor search (frequently called an ANN search) will be performed. This search is much faster, but the results will be approximate. The query can be further parameterized using the returned builder. There are various ANN search parameters that will let you fine tune your recall accuracy vs search latency. Hybrid searches always have a [limit][]. If `limit` has not been called then a default `limit` of 10 will be used. Typically, a single vector is passed in as the query. However, you can also pass in multiple vectors. This can be useful if you want to find the nearest vectors to multiple query vectors. This is not expected to be faster than making multiple queries concurrently; it is just a convenience method. If multiple vectors are passed in then an additional column `query_index` will be added to the results. This column will contain the index of the query vector that the result is nearest to. NrrcBg|]}t|SrIrrs r;rz,AsyncFTSQuery.nearest_to.. rr=r) r6r3r4r5r7rwrnrrrrrrs r;rzAsyncFTSQuery.nearest_to sf  ;<< < |T * * L!!A%%|A ==&VU UUUM{--mA.>??H"122& - -))!,,,,#H-- -# &&z'E'El'S'STT r=Nrrrrrrc\Kt|d{V}tj|d{V|j}|jr-|j| |}t||SNrr) rkrr8r)rrrrtrrrrcrrreaderrrws r;rzAsyncFTSQuery.to_batches s ww))')::::::::(''foo.?.?(?(?(?(?(?(?OO > Kn//0@0@'JJG%g@PQQQQr=)rjrrp)rUrr0r)rrr0rr) rErFrGrrrrrXrrrrs@r;rr s33 '''' )[]]     DDDDR+/'+ R R R R R R R R R R R Rr=rcZeZdZddZddZdd Zdd Z dddZddZd dZ d!dZ d"dZ d S)#AsyncVectorQueryBasertr@r0r,c:|j||S)aZ Set the vector column to query This controls which column is compared to the query vector supplied in the call to [AsyncQuery.nearest_to][lancedb.query.AsyncQuery.nearest_to]. This parameter must be specified if the table has more than one column whose data type is a fixed-size-list of floats. )rnrt)rcrts r;rtzAsyncVectorQueryBase.column* s 6""" r=rrwc:|j||S)a Set the number of partitions to search (probe) This argument is only used when the vector column has an IVF-based index. If there is no index then this value is ignored. The IVF stage of IVF PQ divides the input into partitions (clusters) of related values. The partition whose centroids are closest to the query vector will be exhaustiely searched to find matches. This parameter controls how many partitions should be searched. Increasing this value will increase the recall of your query but will also increase the latency of your query. The default value is 20. This default is good for many cases but the best value to use will depend on your data and the recall that you need to achieve. For best results we recommend tuning this parameter with a benchmark against your actual data to find the smallest possible value that will still give you the desired recall. )rnrrs r;rzAsyncVectorQueryBase.nprobes7 s. G$$$ r=rc:|j||S)zSet the minimum number of probes to use. See `nprobes` for more details. These partitions will be searched on every indexed vector query and will increase recall at the expense of latency. )rnrrs r;rz$AsyncVectorQueryBase.minimum_nprobesQ s ##O444 r=rc:|j||Sr)rnrrs r;rz$AsyncVectorQueryBase.maximum_nprobes\ s ##O444 r=Nrrrc<|j|||S)aSet the distance range to use. Only rows with distances within range [lower_bound, upper_bound) will be returned. Parameters ---------- lower_bound: Optional[float] The lower bound of the distance range. upper_bound: Optional[float] The upper bound of the distance range. Returns ------- AsyncVectorQuery The AsyncVectorQuery object. )rnrrs r;rz#AsyncVectorQueryBase.distance_rangem s!( ""; <<< r=rc:|j||S)a Set the number of candidates to consider during search This argument is only used when the vector column has an HNSW index. If there is no index then this value is ignored. Increasing this value will increase the recall of your query but will also increase the latency of your query. The default value is 1.5 * limit. This default is good for many cases but the best value to use will depend on your data and the recall that you need to achieve. )rnrrs r;rzAsyncVectorQueryBase.ef s r r=rc:|j||S)a A multiplier to control how many additional rows are taken during the refine step This argument is only used when the vector column has an IVF PQ index. If there is no index then this value is ignored. An IVF PQ index stores compressed (quantized) values. They query vector is compared against these values and, since they are compressed, the comparison is inaccurate. This parameter can be used to refine the results. It can improve both improve recall and correct the ordering of the nearest results. To refine results LanceDb will first perform an ANN search to find the nearest `limit` * `refine_factor` results. In other words, if `refine_factor` is 3 and `limit` is the default (10) then the first 30 results will be selected. LanceDb then fetches the full, uncompressed, values for these 30 results. The results are then reordered by the true distance and only the nearest 10 are kept. Note: there is a difference between calling this method with a value of 1 and never calling this method at all. Calling this method with any value will have an impact on your search latency. When you call this method with a `refine_factor` of 1 then LanceDb still needs to fetch the full, uncompressed, values so that it can potentially reorder the results. Note: if this method is NOT called then the distances returned in the _distance column will be approximate distances based on the comparison of the quantized query vector and the quantized result vectors. This can be considerably different than the true distance between the query vector and the actual uncompressed vector. )rnrrs r;rz"AsyncVectorQueryBase.refine_factor s B !!-000 r=rc:|j||S)aO Set the distance metric to use When performing a vector search we try and find the "nearest" vectors according to some kind of distance metric. This parameter controls which distance metric to use. See @see {@link IvfPqOptions.distanceType} for more details on the different distance metrics available. Note: if there is a vector index then the distance type used MUST match the distance type used to train the vector index. If this is not done then the results will be invalid. By default "l2" is used. )rnrrs r;rz"AsyncVectorQueryBase.distance_type s !!-000 r=c8|j|S)a If this is called then any vector index is skipped An exhaustive (flat) search will be performed. The query vector will be compared to every vector in the table. At high scales this can be expensive. However, this is often still useful. For example, skipping the vector index can give you ground truth results which you can use to calculate your recall to select an appropriate value for nprobes. )rnrrbs r;rz(AsyncVectorQueryBase.bypass_vector_index s ''))) r=)rtr@r0r,)rrwr0r,)rrwr0r,)rrwr0r,r)rrrrr0r,)rrwr0r,)rrwr0r,)rr@r0r,r) rErFrGrtrrrrrrrrrIr=r;rr) s    4    $SW.    """"H$      r=rc^eZdZdfd Zedfdd Z dddZddddfdZxZS)rrjLanceVectorQueryctt|||_d|_d|_dS)a Construct an AsyncVectorQuery This method is not intended to be called directly. Instead, create a query first with [AsyncTable.query][lancedb.table.AsyncTable.query] and then use [AsyncQuery.nearest_to][lancedb.query.AsyncQuery.nearest_to]] to convert to a vector query. Or you can use [AsyncTable.vector_search][lancedb.table.AsyncTable.vector_search] N)rkrrnrt _query_stringrs r;rzAsyncVectorQuery.__init__ s9  !r=NrUrrrr0rc|r$t|tstd||_|js|std||_|S)NrAz4query_string must be provided to rerank the results.)r3rr6rtrrs r;rXzAsyncVectorQuery.rerank se  PJx:: PNOO O!! U, USTT T) r=rsrQrrc t|tr|g}|g}t|tr*t|j||dSt|jd|iS)a Find the documents that are most relevant to the given text query, in addition to vector search. This converts the vector query into a hybrid query. This search will perform a full text search on the table and return the most relevant documents, combined with the vector query results. The text relevance is determined by BM25. The columns to search must be with native FTS index (Tantivy-based can't work with this method). By default, all indexed columns are searched, now only one column can be searched at a time. Parameters ---------- query: str The text query to search for. columns: str or list of str, default None The columns to search in. If None, all indexed columns are searched. For now only one column can be searched at a time. Nrrs)r3r@rrnrrs r;rz AsyncVectorQuery.nearest_to_text s6 gs # # iG ?G eS ! ! # ++e,P,PQQ   ; ;We Pn2243EwOOG%g@PQQQQr=)rjr)rUrrrr0rr~)rsrQrrr0rr) rErFrGrrrXrrrrs@r;rr s " " " " " " $/;==PT      RV%O%O%O%O%OT+/'+ R R R R R R R R R R R Rr=rcbeZdZdZdfd Zedfdd Zd d d ddZdddZdZ xZ S)rrrjLanceHybridQueryct|||_d|_t |_dS)Nr)rkrrnrrrtrs r;rzAsyncHybridQuery.__init__6 s8   $r=rrUrr=r@r0c|dvrtd|r$t|tstd||_||_|S)a Rerank the hybrid search results using the specified reranker. The reranker must be an instance of Reranker class. Parameters ---------- reranker: Reranker, default RRFReranker() The reranker to use. Must be an instance of Reranker class. normalize: str, default "score" The method to normalize the scores. Can be "rank" or "score". If "rank", the scores are converted to ranks and then normalized. If "score", the scores are normalized directly. Returns ------- AsyncHybridQuery The AsyncHybridQuery object. r?r@rA)r6r3rrrtrBs r;rXzAsyncHybridQuery.rerank< s\( - - -CDD D  PJx:: PNOO O ! r=Nrrrrrrc vKt|j}t|j}|j}||tj| || |d{V\}}t |||j | |j|j|}t!||S)Nrrr)rrn to_fts_queryrto_vector_queryget_with_row_idrasynciogatherr rrrrrt get_limitr) rcrrr vec_queryrrrrs r;rzAsyncHybridQuery.to_batchesZ s9 "$+":":"<"<== $T[%@%@%B%BCC {2244 ,3N   w  / /   w  / /- - ' ' ' ' ' ' # ^ )@@#)))++^+''))%A  &f?OPPPPr=Fr?rcK|j|d{V}|j|d{V}dd|D}dd|D}|jd|d|S)acReturn the execution plan for this query. The output includes both the vector and FTS search plans. Examples -------- >>> import asyncio >>> from lancedb import connect_async >>> from lancedb.index import FTS >>> async def doctest_example(): ... conn = await connect_async("./.lancedb") ... table = await conn.create_table("my_table", [{"vector": [99.0, 99.0], "text": "hello world"}]) ... await table.create_index("text", config=FTS(with_position=False)) ... plan = await table.query().nearest_to([1.0, 2.0]).nearest_to_text("hello").explain_plan(True) ... print(plan) >>> asyncio.run(doctest_example()) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE RRFReranker(K=60) ProjectionExec: expr=[vector@0 as vector, text@3 as text, _distance@2 as _distance] Take: columns="vector, _rowid, _distance, (text)" CoalesceBatchesExec: target_batch_size=1024 GlobalLimitExec: skip=0, fetch=10 FilterExec: _distance@2 IS NOT NULL SortExec: TopK(fetch=10), expr=[_distance@2 ASC NULLS LAST, _rowid@1 ASC NULLS LAST], preserve_partitioning=[false] KNNVectorDistance: metric=l2 LanceRead: uri=..., projection=[vector], ... ProjectionExec: expr=[vector@2 as vector, text@3 as text, _score@1 as _score] Take: columns="_rowid, _score, (vector), (text)" CoalesceBatchesExec: target_batch_size=1024 GlobalLimitExec: skip=0, fetch=10 MatchQuery: column=text, query=hello Parameters ---------- verbose : bool, default False Use a verbose output format. Returns ------- plan : str NrQc3 K|] }d|zV dSrSrIrTs r;rVz0AsyncHybridQuery.explain_plan.. rWr=c3 K|] }d|zV dSrSrIrTs r;rVz0AsyncHybridQuery.explain_plan.. rYr=rZ)rnrrFrr[r\rt)rcr?r^r_r`ras r;rFzAsyncHybridQuery.explain_planz sT!K7799FFwOOOOOOOO 1133@@IIIIIIII))#U#UK.iter_sync sZ =(<#9#9#;#;<<<<<=%    s */ ==)rrrnrr8rrr)rcrrrrs @r;rzBaseQueryBuilder.to_batches sl,x K " "4Dg " V V       #001DiikkRRRr=rcZtj|j|S)r)rrrnr rs r;r zBaseQueryBuilder.to_arrow% s$x ,,W55666r=rcZtj|j|S)r)rrrnrrs r;rzBaseQueryBuilder.to_list6 s$x ++G44555r=rrrc Ntj|jj||fi|S)r)rrrnrrs r;rzBaseQueryBuilder.to_pandasG s/Rx- -gwII&IIJJJr=r'cZtj|j|S)r)rrrnr.rs r;r.zBaseQueryBuilder.to_polarsr s%@x --g66777r=Fr?rcZtj|j|S)r)rrrnrFrEs r;rFzBaseQueryBuilder.explain_plan s$<x 0099:::r=cXtj|jS)rc)rrrnrLrbs r;rLzBaseQueryBuilder.analyze_plan s"x 0022333r=)rjrirerrr)rrrrr0rr~r\r^rr[r_rbr)rErFrGrrrDrrrrr rrr.rFrLrIr=r;r r  sP---->5555+/'+ !S!S!S!S!S!SF77777"66666&/3'+)K)K)K)K)KZ(, 8 8 8 8 8D;;;;;@44444r=r c$eZdZdZdfd ZxZS)LanceTakeQueryBuilderrrjrcJt|dSr~rrs r;rzLanceTakeQueryBuilder.__init__ rr=)rjrrrs@r;rr rr=r)r/r r0r1)q __future__rrabcrrconcurrent.futuresrdatetimerenumrtypingr r r r r rrrrrrfnumpyrpyarrowr8pyarrow.computecomputerrtyping_extensionsrlancedb._lancedbrlancedb.background_looprlancedb.pydanticrrarrowr dependenciesrpdrrrerankers.baser rerankers.rrfrrerankers.utilrutilr sysPILr*r-_lancedbr!rr"rr#r$rr%rr&rcommonr'r(rr) version_infor,r-r< BaseModelr?r@rKrWr[ dataclasses dataclassr`rrrrrrjrrrrrrobjectrirrrrrrrr rrIr=r;r?s#"""""########111111                        ''''''......((((((------))))))&&&&&&$$$$$$&&&&&&111111!!!!!!+JJJJJJ333333999999((((((------555555999999$$$$$$ 7""****** GC|$$$6X' TsD C  =K=K=K=K=KC=K=K =K@ *'*'*'*'*'*'*' *'Z .....-.. .( ''''''' ', -----m-- -> )))))=)) )$%%%%%(,%%%$O9O9O9O9O9H O9O9O9d_"_"_"_"_"_"_"_"DNNNNN/NNNb uuuuu,uuup%E%E%E%E%E.%E%E%EP\+\+\+\+\+/\+\+\+~e0e0e0e0e0Ve0e0e0P rrrrrrrrjCLCLCLCLCL#CLCLCLLfRfRfRfRfR&fRfRfRRkkkkkkkk\PRPRPRPRPR)+?PRPRPRfS"S"S"S"S")+?S"S"S"l     ^   r4r4r4r4r4vr4r4r4j     ,     r=