lQj zddlmZmZddlmZmZmZmZmZm Z m Z ddl m Z ddl ZddlmZddlmZmZmZmZmZmZmZmZmZmZddlmZmZmZeGdd Z eGd d Z!eGd d e!Z"eGdde!Z#eGdde!Z$eGdde!Z%eGdde!Z&eGdde!Z'eGdde!Z(eGdde!Z)eGdde!Z*eGdde!Z+eGd d!e!Z,eGd"d#e!Z-eGd$d%e!Z.eGd&d'e!Z/Gd(d)Z0e0d*e0_1e0d+e0_2e0d,e0_3e0d-e0_4e0d.e0_5e0Z6eGd/d0Z7eGd1d2Z8eGd3d4Z9eGd5d6Z:eGd7d8Z;eGd9d:e;Ze;Z>eGd?d@e;Z?eGdAdBe;Z@eGdCdDe;ZAeGdEdFe;ZBeGdGdHe;ZCeGdIdJe;ZDeGdKdLe;ZEeGdMdNe;ZFeGdOdPe;ZGeGdQdRZHdSee e0eIfdTeeIfdUZJdSe eeeKedVffdTee e0eIffdWZLdXeIdYeeIefdTeKee e0eIfeMffdZZNeGd[d\ZOeGd]d^eOZPeGd_d`eOZQeGdadbZRy)c) dataclassfield)OptionalListDictSetAnyUnioncast) LiteralValueN)NDArray) EmbeddingsIDsInclude OneOrMany SparseVectorTYPE_KEYSPARSE_VECTOR_TYPE_VALUEmaybe_cast_one_to_manynormalize_embeddingsvalidate_embeddings) CollectionRequestVersionContextSegmentcLeZdZUeed<eed<eed<eed<edefdZy)Scan collectionknnmetadatarecordreturnclt|jj|jjS)N)collection_version log_position)rrversionr$selfs k/home/oem/CyberBrain26-unified/.venv/lib/python3.12/site-packages/chromadb/execution/expression/operator.pyr%z Scan.version"s)$#6655  N) __name__ __module__ __qualname__r__annotations__rpropertyrr%r)r(rrs2 L O  .  r)rcZeZdZdZdeeeffdZedeeefddfdZ d dZ d dZ y) Wherea?Base class for Where expressions (algebraic data type). Supports logical operators for combining conditions: - AND: where1 & where2 - OR: where1 | where2 Examples: # Simple conditions where1 = Key("status") == "active" where2 = Key("score") > 0.5 # Combining with AND combined_and = where1 & where2 # Combining with OR combined_or = where1 | where2 # Complex expressions complex_where = (Key("status") == "active") & ((Key("score") > 0.5) | (Key("priority") == "high")) r!ctd)zCConvert the Where expression to a dictionary for JSON serialization#Subclasses must implement to_dict()NotImplementedErrorr&s r(to_dictz Where.to_dictB!"GHHr)datacd t|ts!tdt|j|s t dd|vrt|dt s$tdt|djt|ddk(r t dt|dkDr t d|dDcgc]}tj|}}t|dk(r|dS|d}|dd D]}||z} |Sd |vrt|d t s$td t|d jt|d dk(r t d t|dkDr t d |d Dcgc]}tj|}}t|dk(r|dS|d}|dd D]}||z} |St|dk7rt dt|tt|j\}}t|ts!tdt|jt|tr|st d|dt|dk7rt d|dtt|j\}}|dk(rt||k(S|dk(rt||k7S|dk(rt||kDS|dk(rt||k\S|dk(rt||kS|dk(rt||kS|dk(rKt|t s!tdt|jt|j|S|dk(rKt|t s!tdt|jt|j!|S|dk(r[t|tt"t$t&fs!tdt|jt|j)|S|dk(r[t|tt"t$t&fs!td t|jt|j+|S|d!k(rKt|ts!td"t|jt|j-|S|d#k(rKt|ts!td$t|jt|j/|St d%|t||k(Scc}wcc}w)&atCreate Where expression from dictionary. Supports MongoDB-style query operators: - {"field": "value"} -> Key("field") == "value" (shorthand for equality) - {"field": {"$eq": value}} -> Key("field") == value - {"field": {"$ne": value}} -> Key("field") != value - {"field": {"$gt": value}} -> Key("field") > value - {"field": {"$gte": value}} -> Key("field") >= value - {"field": {"$lt": value}} -> Key("field") < value - {"field": {"$lte": value}} -> Key("field") <= value - {"field": {"$in": [values]}} -> Key("field").is_in([values]) - {"field": {"$nin": [values]}} -> Key("field").not_in([values]) - {"field": {"$contains": "text"}} -> Key("field").contains("text") - {"field": {"$not_contains": "text"}} -> Key("field").not_contains("text") - {"field": {"$regex": "pattern"}} -> Key("field").regex("pattern") - {"field": {"$not_regex": "pattern"}} -> Key("field").not_regex("pattern") - {"$and": [conditions]} -> condition1 & condition2 & ... - {"$or": [conditions]} -> condition1 | condition2 | ... zExpected dict for Where, got zWhere dict cannot be empty$andz$and must be a list, got rz$$and requires at least one conditionz:$and cannot be combined with other fields in the same dictN$orz$or must be a list, got z#$or requires at least one conditionz9$or cannot be combined with other fields in the same dictz/Where dict must contain exactly one field, got z!Field name must be a string, got zOperator dict for field 'z' cannot be emptyz#' must contain exactly one operator$eq$ne$gt$gte$lt$lte$inz$in requires a list, got $ninz$nin requires a list, got $containsz3$contains requires a str, int, float, or bool, got $not_containsz7$not_contains requires a str, int, float, or bool, got $regexz&$regex requires a string pattern, got $not_regexz*$not_regex requires a string pattern, got zUnknown operator: ) isinstancedict TypeErrortyper* ValueErrorlistlenr1 from_dictnextiteritemsstrKeyis_innot_inintfloatboolcontains not_containsregex not_regex)r8c conditionsresultr conditionopvalues r(rPzWhere.from_dictFsT*$%;DJd6lD1/T&\0B0K0K/LM4< A% !GHH4y1} P7;6lC%//!,CJC:!#!!}$]F^ $! $M d]d5k40":4U ;L;U;U:V WXX4;1$ !FGG4y1} O7;5kB%//!,BJB:!#!!}$]F^ $! $M4yA~ Ec$i[Q $D$67 E9eS)7U 8L8L7MN)T* $3E7:KLy>Q&$3E7:]^!ioo&7!89 E;u:..5[u:..5[u:--6\u:..5[u:--6\u:..5[%eT2'7U 8L8L7MNu:++E226\%eT2'8e9M9M8NOu:,,U33;&%ec3t-DE'QRVW\R]RfRfQghu:..u55?*%ec3t-DE'UVZ[`VaVjVjUklu:225998^%eS1'DT%[EYEYDZ[u:++E22<'%eS1'HeI]I]H^_u://66$'9"%>??5zY..SD$Cs 6T(4T-c$t|trKt|tr"t|j|jzSt|j|gzSt|trt|g|jzSt||gS)zOverload & operator for AND)rIAndr`r'others r(__and__z Where.__and__sy dC %%4??U-=-==>>t%01 1 s #v 0 001 1D%=!!r)c$t|trKt|tr"t|j|jzSt|j|gzSt|trt|g|jzSt||gS)zOverload | operator for OR)rIOrr`rgs r(__or__z Where.__or__sy dB %$$//E,<,<<==doo/0 0 r "tfu///0 04-  r)N)rhr1r!rf)rhr1r!rk) r*r+r,__doc__rrTr r6 staticmethodrPrirlr/r)r(r1r1+sV*Ic3hIP/S#XP/7P/P/d " !r)r1c8eZdZUdZeeed<deee ffdZ y)rfz(Logical AND of multiple where conditionsr`r!c`d|jDcgc]}|jc}iScc}w)Nr:r`r6r'r_s r(r6z And.to_dicts%doo>>??>+N r*r+r,rmrr1r-rrTr r6r/r)r(rfrfs%2U @c3h@r)rfc8eZdZUdZeeed<deee ffdZ y)rkz'Logical OR of multiple where conditionsr`r!c`d|jDcgc]}|jc}iScc}w)Nr<rqrrs r(r6z Or.to_dicts%T__= =>>=rsNrtr/r)r(rkrks#1U ?c3h?r)rkc<eZdZUdZeed<eed<deeeffdZy)EqzEquality comparisonkeyrdr!c6|jd|jiiS)Nr=ryrdr&s r(r6z Eq.to_dict5$**-..r)N r*r+r,rmrTr-r rr6r/r)r(rxrx s# H J/c3h/r)rxc<eZdZUdZeed<eed<deeeffdZy)NezNot equal comparisonryrdr!c6|jd|jiiS)Nr>r{r&s r(r6z Ne.to_dictr|r)Nr}r/r)r(rr# H J/c3h/r)rc<eZdZUdZeed<eed<deeeffdZy)GtzGreater than comparisonryrdr!c6|jd|jiiS)Nr?r{r&s r(r6z Gt.to_dict'r|r)Nr}r/r)r(rr s#! H J/c3h/r)rc<eZdZUdZeed<eed<deeeffdZy)Gtez Greater than or equal comparisonryrdr!c6|jd|jiiS)Nr@r{r&s r(r6z Gte.to_dict264::.//r)Nr}r/r)r(rr+s#* H J0c3h0r)rc<eZdZUdZeed<eed<deeeffdZy)LtzLess than comparisonryrdr!c6|jd|jiiS)NrAr{r&s r(r6z Lt.to_dict=r|r)Nr}r/r)r(rr6rr)rc<eZdZUdZeed<eed<deeeffdZy)LtezLess than or equal comparisonryrdr!c6|jd|jiiS)NrBr{r&s r(r6z Lte.to_dictHrr)Nr}r/r)r(rrAs#' H J0c3h0r)rcBeZdZUdZeed<eeed<deeeffdZ y)Inz"In comparison - value is in a listryvaluesr!c6|jd|jiiS)NrCryrr&s r(r6z In.to_dictSs5$++.//r)N r*r+r,rmrTr-rr rr6r/r)r(rrLs(, H I0c3h0r)rcBeZdZUdZeed<eeed<deeeffdZ y)Ninz*Not in comparison - value is not in a listryrr!c6|jd|jiiS)NrDrr&s r(r6z Nin.to_dict^s64;;/00r)Nrr/r)r(rrWs(4 H I1c3h1r)rc<eZdZUdZeed<eed<deeeffdZ y)ContainszEContains comparison for document content or metadata array membershipryrdr!c6|jd|jiiS)NrEr{r&s r(r6zContains.to_dictis; 344r)N r*r+r,rmrTr-r rr r6r/r)r(rrbs$O H 5c3h5r)rc<eZdZUdZeed<eed<deeeffdZ y) NotContainszINot-contains comparison for document content or metadata array membershipryrdr!c6|jd|jiiS)NrFr{r&s r(r6zNotContains.to_dictts?DJJ788r)Nrr/r)r(rrms$S H 9c3h9r)rc<eZdZUdZeed<eed<deeeffdZy)RegexzRegular expression matchingrypatternr!c6|jd|jiiS)NrGryrr&s r(r6z Regex.to_dicts8T\\233r)N r*r+r,rmrTr-rr r6r/r)r(rrxs#% H L4c3h4r)rc<eZdZUdZeed<eed<deeeffdZy)NotRegexz$Negative regular expression matchingryrr!c6|jd|jiiS)NrHrr&s r(r6zNotRegex.to_dicts<677r)Nrr/r)r(rrs#. H L8c3h8r)rc(eZdZUdZded<ded<ded<ded<ded<defdZd efd Zd e d e fd Z d e d e fd Z d e d efdZd e d efdZd e d efdZd e d efdZdee d efdZdee d efdZded efdZded efdZd ed e fdZ!d ed e"fdZ#y)rUaField proxy for building Where filter expressions. The Key class allows for readable field references using either: 1. Predefined constants for special fields: K.EMBEDDING, K.DOCUMENT, K.SCORE, etc. 2. String literals with # prefix for special fields: Key("#embedding") 3. Metadata field names without # prefix: Key("my_metadata_field") Predefined field constants (special fields with # prefix): Key.ID - ID field (equivalent to Key("#id")) Key.DOCUMENT - Document field (equivalent to Key("#document")) Key.EMBEDDING - Embedding field (equivalent to Key("#embedding")) Key.METADATA - Metadata field (equivalent to Key("#metadata")) Key.SCORE - Score field (equivalent to Key("#score")) Note: K is an alias for Key, so you can use K.DOCUMENT or Key.DOCUMENT interchangeably. Examples: # Using predefined keys with K alias for special fields from chromadb.execution.expression import K K.DOCUMENT.contains("search text") # Searches document field # Custom metadata field names (without # prefix) K("status") == "active" # Metadata field named "status" K("category").is_in(["science", "tech"]) # Metadata field named "category" K("sparse_embedding") # Example: metadata field (could store anything) # Using with Knn for different fields Knn(query=[0.1, 0.2]) # Default: searches "#embedding" Knn(query=[0.1, 0.2], key=K.EMBEDDING) # Explicit: searches "#embedding" Knn(query=sparse, key="sparse_embedding") # Example: searches a metadata field # Combining conditions (K("status") == "active") & (K.SCORE > 0.5) IDDOCUMENT EMBEDDINGMETADATASCOREnamec||_y)N)r)r'rs r(__init__z Key.__init__s  r)r!c,t|jS)z!Make Key hashable for use in sets)hashrr&s r(__hash__z Key.__hash__sDIIr)rdc.t|j|S)zEquality: Key('field') == value)rxrr'rds r(__eq__z Key.__eq__$))U##r)c.t|j|S)z Not equal: Key('field') != value)rrrs r(__ne__z Key.__ne__rr)c.t|j|S)z"Greater than: Key('field') > value)rrrs r(__gt__z Key.__gt__rr)c.t|j|S)z,Greater than or equal: Key('field') >= value)rrrs r(__ge__z Key.__ge__499e$$r)c.t|j|S)zLess than: Key('field') < value)rrrs r(__lt__z Key.__lt__rr)c.t|j|S)z)Less than or equal: Key('field') <= value)rrrs r(__le__z Key.__le__rr)rc.t|j|S)z?Check if field value is in list: Key('field').is_in(['a', 'b']))rrr'rs r(rVz Key.is_ins$))V$$r)c.t|j|S)zDCheck if field value is not in list: Key('field').not_in(['a', 'b']))rrrs r(rWz Key.not_ins499f%%r)rc.t|j|S)z9Match field against regex: Key('field').regex('^pattern'))rrr'rs r(r]z Key.regexsTYY((r)c.t|j|S)z@Field should not match regex: Key('field').not_regex('^pattern'))rrrs r(r^z Key.not_regexs 7++r)c|jdk(rt|ts tdt |j|S)aCheck if field contains a value. On Key.DOCUMENT: substring search (value must be a string). On metadata fields: checks if the array field contains the scalar value. Examples: Key.DOCUMENT.contains("machine learning") # document substring Key("tags").contains("action") # metadata array contains Key("scores").contains(42) # metadata array contains #documentz0$contains on #document requires a string pattern)rrIrTrKrrs r(r[z Key.containss6 99 #Juc,BNO O 5))r)c|jdk(rt|ts tdt |j|S)aCheck if field does not contain a value. On Key.DOCUMENT: excludes documents containing the substring. On metadata fields: checks that the array field does not contain the scalar value. Examples: Key.DOCUMENT.not_contains("deprecated") # document substring exclusion Key("tags").not_contains("draft") # metadata array not-contains rz4$not_contains on #document requires a string pattern)rrIrTrKrrs r(r\zKey.not_containss6 99 #Juc,BRS S499e,,r)N)$r*r+r,rmr-rTrrXrr rxrrrrrrrrrrrrrrVrrWrr]rr^r rr[rr\r/r)r(rUrUs(!H IOO LS# $C$B$$C$B$$C$B$%C%C%$C$B$%C%C% %DI%"%&T#Y&3&)S)U),,, *l *x * -, -; -r)rU#idr #embedding #metadata#scorecJeZdZUdZeeed<dZeeed<dZ eeed<y)FilterNuser_idswherewhere_document) r*r+r,rrrr-rr rr/r)r(rrs,"Hhsm"E8C=$(NHSM(r)rc"eZdZUeed<eed<y)KNN embeddingsfetchN)r*r+r,rr-rXr/r)r(rrs  Jr)rcjeZdZUdZeed<dZeeed<dee e ffdZ e dee e fddfdZ y) LimitroffsetNlimitr!cXd|ji}|j|j|d<|S)z8Convert the Limit to a dictionary for JSON serializationrrrrr'ras r(r6z Limit.to_dict&s,DKK( :: !"jjF7O r)r8c8t|ts!tdt|j|j dd}t|t s!tdt|j|dkrtd||j d}|Dt|t s!tdt|j|dkrtd|ddh}t|j|z }|rtd |t|| S) zCreate Limit from dictionary. Examples: - {"offset": 10} -> Limit(offset=10) - {"offset": 10, "limit": 20} -> Limit(offset=10, limit=20) - {"limit": 20} -> Limit(offset=0, limit=20) zExpected dict for Limit, got rrz%Limit offset must be an integer, got z'Limit offset must be non-negative, got rz$Limit limit must be an integer, got z"Limit limit must be positive, got zUnexpected keys in Limit dict: r) rIrJrKrLr*getrXrMsetkeysr)r8rr allowed_keysunexpected_keyss r(rPzLimit.from_dict-s%$%;DJ>OPQ QF%00r))r*r+r,rrXr-rrrrTr r6rnrPr/r)r(rr!sWFCOE8C=c3h"1S#X"17"1"1r)rcjeZdZUdZeed<dZeed<dZeed<dZeed<dZ eed<e de fdZ y ) ProjectionFdocument embeddingrrankurir!c<t}|jr|jd|jr|jd|jr|jd|j r|jd|j r|jd|S)N documentsr metadatas distancesuris)rNrappendrrrr)r'includess r(includedzProjection.included[sm6 == OOK ( >> OOL ) == OOK ( 99 OOK ( 88 OOF #r)N) r*r+r,rrZr-rrrrr.rrr/r)r(rrSsMHdItHdD$C  '  r)rceZdZdZdeeeffdZedeeefddfdZ de de e fddfdZ de e e fddfd Zde de e fdd fd Zde e e fdd fd Zde de e fdd fdZde e e fdd fdZde de e fddfdZde e e fddfdZddZddZddZddZd dZde de e fddfdZde de e fddfdZy)!RankaBase class for rank expressions. Supports arithmetic operations for combining rank expressions: - Addition: rank1 + rank2, rank + 0.5 - Subtraction: rank1 - rank2, rank - 0.5 - Multiplication: rank1 * rank2, rank * 0.8 - Division: rank1 / rank2, rank / 2.0 - Negation: -rank - Absolute value: abs(rank) Supports mathematical functions: - Exponential: rank.exp() - Logarithm: rank.log() - Maximum: rank.max(other) - Minimum: rank.min(other) Examples: # Weighted combination Knn(query=[0.1, 0.2]) * 0.8 + Val(0.5) * 0.2 # Normalization Knn(query=[0.1, 0.2]) / Val(10.0) # Clamping Knn(query=[0.1, 0.2]).min(1.0).max(0.0) r!ctd)zCConvert the Score expression to a dictionary for JSON serializationr3r4r&s r(r6z Rank.to_dictr7r)r8ct|ts!tdt|j|s t dt |dk7rt dt |tt|j}|dk(rG|d}t|ttfs!tdt|jt|S|dk(r |d}t|ts!tdt|jd |vr t d |d }t|trN|jttk(rt!j"|}nt d td td |t|t$t&t(j*fr7t-|}|rt |dkDr t dt/||d}n!tdt|j|jdd}t|t0s!tdt|j|jdd}t|ts!tdt|j|dkrt d||jdd}t|t2s!tdt|jt5||||jd|S|dk(r|d} t| t$t&fs!tdt| jt | dkrt d t | | D cgc]} t6j#| } } | d} | dd!D]} | | z} | S|d"k(r~|d"} t| ts!td#t| jd$| vsd%| vr t d&t6j#| d$}t6j#| d%}||z S|d'k(r|d'} t| t$t&fs!td(t| jt | dkrt d)t | | D cgc]} t6j#| } } | d} | dd!D]} | | z} | S|d*k(r~|d*}t|ts!td+t|jd$|vsd%|vr t d,t6j#|d$}t6j#|d%}||z S|d-k(rT|d-}t|ts!td.t|jt9t6j#|S|d/k(rY|d/}t|ts!td0t|jt6j#|j;S|d1k(rY|d1}t|ts!td2t|jt6j#|j=S|d3k(r|d3} t| t$t&fs!td4t| jt | dkrt d5t | | D cgc]} t6j#| } } | d} | dd!D]} | j?| } | S|d6k(r|d6} t| t$t&fs!td7t| jt | dkrt d8t | | D cgc]} t6j#| } } | d} | dd!D]} | jA| } | St d9|cc} wcc} wcc} wcc} w):asCreate Rank expression from dictionary. Supports operators: - {"$val": number} -> Val(number) - {"$knn": {...}} -> Knn(...) - {"$sum": [ranks]} -> rank1 + rank2 + ... - {"$sub": {"left": ..., "right": ...}} -> left - right - {"$mul": [ranks]} -> rank1 * rank2 * ... - {"$div": {"left": ..., "right": ...}} -> left / right - {"$abs": rank} -> abs(rank) - {"$exp": rank} -> rank.exp() - {"$log": rank} -> rank.log() - {"$max": [ranks]} -> rank1.max(rank2).max(rank3)... - {"$min": [ranks]} -> rank1.min(rank2).min(rank3)... zExpected dict for Rank, got zRank dict cannot be emptyr;z1Rank dict must contain exactly one operator, got $valz$val requires a number, got $knnz$knn requires a dict, got queryz$knn requires 'query' fieldzExpected dict with z='z', got z)$knn requires exactly one query embeddingrzB$knn query must be a list, numpy array, or SparseVector dict, got ryrz$knn key must be a string, got rz#$knn limit must be an integer, got z!$knn limit must be positive, got return_rankFz($knn return_rank must be a boolean, got default)rryrrr$sumz$sum requires a list, got z$$sum requires at least 2 ranks, got N$subz2$sub requires a dict with 'left' and 'right', got leftrightz'$sub requires 'left' and 'right' fields$mulz$mul requires a list, got z$$mul requires at least 2 ranks, got $divz2$div requires a dict with 'left' and 'right', got z'$div requires 'left' and 'right' fields$absz$abs requires a rank dict, got $expz$exp requires a rank dict, got $logz$log requires a rank dict, got $maxz$max requires a list, got z$$max requires at least 2 ranks, got $minz$min requires a list, got z$$min requires at least 2 ranks, got zUnknown rank operator: )!rIrJrKrLr*rMrOrQrRrrXrYValrrrrrPrNtuplenpndarrayrrrTrZKnnrabsexplogmaxmin)r8rcrdknn_datar normalizedryrr ranks_datarranksrasub_datarrdiv_data child_datas r(rPzRank.from_dicts"$%:4:;N;N:OPQ Q89 9 t9>CCI;O $tyy{# $ <LEec5\2">tE{?S?S>T UVVu:  6\F|Hh-"??W%E%&99X&*BB(2259E%-hZr:R9SSZ[`ZabED%#<=1%8 !S_q%8$%PQQ$J/"1  XY]^cYdYmYmXno,,ul3Cc3'"A$s)BTBTAU VWWLL"-EeS)9$u+:N:N9OPz #DUG!LMM",,}etK?P?Y?Y>Z[ Y/'  6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y $! $M 6\F|Hh-HhI`I`HabX%)@ !JKK>>(6"23DNN8G#45E%<  6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y $! $M 6\F|Hh-HhI`I`HabX%)@ !JKK>>(6"23DNN8G#45E%<  6\fJj$/5d:6F6O6O5PQt~~j12 2 6\fJj$/5d:6F6O6O5PQ>>*-113 3 6\fJj$/5d:6F6O6O5PQ>>*-113 3 6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y 'A 'M 6\fJj4-80j1A1J1J0KL:" :3z?:KL1;;1T^^A&;E;1XF12Y 'A 'M6rd;< r)ct|S)zExponential: e^rank)Expr&s r(rzRank.expr>r)ct|S)zNatural logarithm: ln(rank))Logr&s r(rzRank.logr>r)Maxcjt|ttfr t|n|}t|trKt|tr"t |j |j zSt |j |gzSt|trt |g|j zSt ||gS)z1Maximum of this rank and another: rank.max(rank2))rIrXrYr rDrrs r(rzRank.max#-ec5\#BSZ  dC *c*4:: (8(8899tzzZL01 1  C (v 0 001 1D*%&&r)Mincjt|ttfr t|n|}t|trKt|tr"t |j |j zSt |j |gzSt|trt |g|j zSt ||gS)z1Minimum of this rank and another: rank.min(rank2))rIrXrYr rGrrs r(rzRank.minrFr)N)r!r-)r!r<)r!rA)r!rC)r*r+r,rmrrTr r6rnrPr rYrXr r$r(r+r/r1r4r6r9r=rrrrrr/r)r(rrls6Ic3hIX=S#XX=6X=X=v 'U65##56 '5 '!eE3J/!E!%U65##56%5% %eE3J/%E% 'U65##56 '5 '!eE3J/!E!%vuc'9!:%u% %%s "3%%$  'vuc12 'u ' 'vuc12 'u 'r)rc2eZdZUdZeed<deeeffdZ y)r<zAbsolute value of a rankrr!c:d|jjiS)Nrrr6r&s r(r6z Abs.to_dict ))+,,r)N r*r+r,rmrr-rrTr r6r/r)r(r<r<" J-c3h-r)r<c<eZdZUdZeed<eed<deeeffdZ y)r2zDivision of two ranksrrr!cpd|jj|jjdiS)Nrrrrr6rr&s r(r6z Div.to_dict,!2!2!4tzz?Q?Q?STUUr)NrMr/r)r(r2r2s% J KVc3hVr)r2c2eZdZUdZeed<deeeffdZ y)rAzExponentiation of a rankrr!c:d|jjiS)NrrKr&s r(r6z Exp.to_dictrLr)NrMr/r)r(rArArNr)rAc2eZdZUdZeed<deeeffdZ y)rCzLogarithm of a rankrr!c:d|jjiS)NrrKr&s r(r6z Log.to_dictrLr)NrMr/r)r(rCrCs J-c3h-r)rCc8eZdZUdZeeed<deee ffdZ y)rDzMaximum of multiple ranksrr!c`d|jDcgc]}|jc}iScc}w)Nrrr6r'rs r(r6z Max.to_dict%djj99::9rsN r*r+r,rmrrr-rrTr r6r/r)r(rDrD## :;c3h;r)rDc8eZdZUdZeeed<deee ffdZ y)rGzMinimum of multiple ranksrr!c`d|jDcgc]}|jc}iScc}w)Nr rZr[s r(r6z Min.to_dictr\rsNr]r/r)r(rGrGr^r)rGc8eZdZUdZeeed<deee ffdZ y)r-z Multiplication of multiple ranksrr!c`d|jDcgc]}|jc}iScc}w)NrrZr[s r(r6z Mul.to_dictr\rsNr]r/r)r(r-r-s#* :;c3h;r)r-ceZdZUdZeeeeedddfe d<e jZ ee efe d<dZee d<d Zeee d <d Zee d <d eeeffdZy )raKNN-based ranking expression. Args: query: The query for KNN search. Can be: - A string (will be automatically embedded using the collection's embedding function) - A dense vector (list or numpy array) - A sparse vector (SparseVector dict) key: The embedding key to search against. Can be: - Key.EMBEDDING (default) - searches the main embedding field - A metadata field name (e.g., "my_custom_field") - searches that metadata field limit: Maximum number of results to consider (default: 16) default: Default score for records not in KNN results (default: None) return_rank: If True, return the rank position (0, 1, 2, ...) instead of distance (default: False) Examples: # Search with string query (automatically embedded) Knn(query="hello world") # Will use collection's embedding function # Search main embeddings with vectors (equivalent forms) Knn(query=[0.1, 0.2]) # Uses default key="#embedding" Knn(query=[0.1, 0.2], key=K.EMBEDDING) Knn(query=[0.1, 0.2], key="#embedding") # Search sparse embeddings stored in metadata with string Knn(query="hello world", key="custom_embedding") # Will use schema's embedding function # Search sparse embeddings stored in metadata with vector Knn(query=my_vector, key="custom_embedding") # Example: searches a metadata field zNDArray[np.float32]zNDArray[np.float64]zNDArray[np.int32]rryrrNrFrr!c|j}t|tr|j}n*t|tj r|j }|j}t|tr |j}|||jd}|j|j|d<|jr|j|d<d|iS)N)rryrrrr) rrIrr6r r tolistryrUrrrr)r' query_value key_valueras r(r6z Knn.to_dict?sjj k< 0%--/K  RZZ 0%,,.KHH i %!I'y4::N << # $ F9    $($4$4F= !r))r*r+r,rmr rTrrYrr-KrryrUrrXrrrrZrr r6r/r)r(rrs~<   U    ;;CsCx&E3O#GXe_#K c3h r)rc<eZdZUdZeed<eed<deeeffdZ y)r&zSubtraction of two ranksrrr!cpd|jj|jjdiS)NrrQrRr&s r(r6z Sub.to_dict`rSr)NrMr/r)r(r&r&Ys%" J KVc3hVr)r&c8eZdZUdZeeed<deee ffdZ y)rzSummation of multiple ranksrr!c`d|jDcgc]}|jc}iScc}w)NrrZr[s r(r6z Sum.to_dictjr\rsNr]r/r)r(rrds#% :;c3h;r)rc2eZdZUdZeed<deeeffdZ y)r zConstant rank valuerdr!cd|jiS)Nr)rdr&s r(r6z Val.to_dictts ##r)N) r*r+r,rmrYr-rrTr r6r/r)r(r r ns L$c3h$r)r cneZdZUdZeeed<dZeed<dZ e ee ed<dZ e ed<d eeeffd Zy) RrfaReciprocal Rank Fusion for combining ranking strategies. RRF formula: score = -sum(weight_i / (k + rank_i)) for each ranking strategy The negative is used because RRF produces higher scores for better results, but Chroma uses ascending order (lower scores = better results). Args: ranks: List of Rank expressions to fuse (must have at least one) k: Smoothing constant (default: 60, standard in literature) weights: Optional weights for each ranking strategy. If not provided, all ranks are weighted equally (weight=1.0 each). normalize: If True, normalize weights to sum to 1.0 (default: False). When False, weights are used as-is for relative importance. When True, weights are scaled so they sum to 1.0. Examples: # Note: metadata fields (like "sparse_embedding" below) are user-defined and can store any data. # The field name is just an example - use whatever name matches your metadata structure. # Basic RRF combining KNN rankings (equal weight) Rrf([ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field ]) # Weighted RRF with relative weights (not normalized) Rrf( ranks=[ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field weights=[2.0, 1.0], # First ranking is 2x more important k=100 ) # Weighted RRF with normalized weights Rrf( ranks=[ Knn(query=[0.1, 0.2], return_rank=True), Knn(query=another_vector, key="custom_embedding", return_rank=True) # Example metadata field ], weights=[3.0, 1.0], # Will be normalized to [0.75, 0.25] normalize=True, k=100 ) r<kNweightsF normalizer!cN|js td|jdkrtd|j|jt |jt |jk7r8tdt |jdt |jdt d|jDr td |jr |jnd gt |jz}|j r-t|}|dk(r td |Dcgc]}||z  }}t||jDcgc]\}}||j|zz }}}|d}|d dD]}||z} | jScc}wcc}}w) zConvert RRF to a composition of existing expression operators. Builds: -sum(weight_i / (k + rank_i)) for each rank Using Python's overloaded operators for cleaner code. zRRF requires at least one rankrzk must be positive, got NzNumber of weights (z) must match number of ranks ()c3&K|] }|dk yw)gNr/).0ws r( zRrf.to_dict..s1q1s71sz All weights must be non-negativeg?z3Sum of weights must be positive when normalize=Truer;) rrMrrrsrOanyrtsumzipr6)r'rs weight_sumryrtermsrrf_sumterms r(r6z Rrf.to_dictszz=> > 66Q;7x@A A << #4<< C O3 )#dll*;)<>WJQ !VWW/67!q:~7G7584LMDdfftm$MMa!"I %DnG %!!##8Ns 1 FF!)r*r+r,rmrrr-rrrXrsrrYrtrZrrTr r6r/r)r(rprpxsN+Z : AsK%)GXd5k ")It($c3h($r)rpcxeZdZUdZeeZeee e fe d<de e e ffdZede e e fddfdZy) SelectaSelection configuration for search results. Fields can be: - Key.DOCUMENT - Select document key (equivalent to Key("#document")) - Key.EMBEDDING - Select embedding key (equivalent to Key("#embedding")) - Key.SCORE - Select score key (equivalent to Key("#score")) - Any other string - Select specific metadata property Note: You can use K as an alias for Key for more concise code. Examples: # Select predefined keys using K alias (K is shorthand for Key) from chromadb.execution.expression import K Select(keys={K.DOCUMENT, K.SCORE}) # Select specific metadata properties Select(keys={"title", "author", "date"}) # Mixed selection Select(keys={K.DOCUMENT, "title", "author"}) default_factoryrr!cg}|jD]?}t|tr|j|j/|j|Adt t j|iS)z9Convert the Select to a dictionary for JSON serializationr)rrIrUrrrNrJfromkeys)r' key_stringsrrs r(r6zSelect.to_dictsa  &A!S!""166*""1%  & T]];7899r)r8ct|ts!tdt|j|j dg}t|t ttfs!tdt|jg}|D]}t|ts!tdt|j|dk(r |jtjZ|dk(r |jtj|dk(r |jtj|dk(r |jtj|d k(r |jtj |jt| dh}t|j#|z }|rt%d |t't| S) zCreate Select from dictionary. Examples: - {"keys": ["#document", "#score"]} -> Select(keys={Key.DOCUMENT, Key.SCORE}) - {"keys": ["title", "author"]} -> Select(keys={"title", "author"}) zExpected dict for Select, got rz*Select keys must be a list/tuple/set, got z!Select key must be a string, got rrrrrz Unexpected keys in Select dict: )r)rIrJrKrLr*rrNr rrTrrUrrrrrrrMr)r8rkey_listrrrrs r(rPzSelect.from_dicts}$%AjC(CFa / >> >s$,rcr8c ||}t|ts#t|dt|jd|vrt |dd|vrt |d|d}t|t tfs#t|dt|j|st |d|d}t|ts#t|dt|j|d krt |d |t||fS) axParse common fields for MinK/MaxK from dict. Args: op: The operator name (e.g., "$min_k" or "$max_k") data: The dict containing the operator Returns: Tuple of (keys, k) where keys is List[Union[Key, str]] and k is int Raises: TypeError: If data types are invalid ValueError: If required fields are missing or invalid z requires a dict, got rz requires 'keys' fieldrrz requires 'k' fieldz keys must be a list, got z keys cannot be emptyz k must be an integer, got rz k must be positive, got ) rIrJrKrLr*rMrNr rXr)rcr8agg_datarrrs r(_parse_k_aggregater;s" BxH h %2$4T(^5L5L4MNOO XB45677 (B42344 F D dT5M *2$8d9L9L8MNOO B44566 A a 2$9$q':J:J9KLMMAvB48<== D !1 $$r)cJeZdZdZdeeeffdZedeeefddfdZ y) Aggregatea5Base class for aggregation expressions within groups. Aggregations determine which records to keep from each group: - MinK: Keep k records with minimum values (ascending order) - MaxK: Keep k records with maximum values (descending order) Examples: # Keep top 3 by score per group (single key) MinK(keys=Key.SCORE, k=3) # Keep top 5 by priority, then score as tiebreaker (multiple keys) MinK(keys=[Key("priority"), Key.SCORE], k=5) # Keep bottom 2 by score per group MaxK(keys=Key.SCORE, k=2) r!ctd)zGConvert the Aggregate expression to a dictionary for JSON serializationr3r4r&s r(r6zAggregate.to_dictur7r)r8ct|ts!tdt|j|s t dt |dk7rt dt |tt|j}|dk(rt||\}}t||S|dk(rt||\}}t||St d|) zCreate Aggregate expression from dictionary. Supports: - {"$min_k": {"keys": [...], "k": n}} -> MinK(keys=[...], k=n) - {"$max_k": {"keys": [...], "k": n}} -> MaxK(keys=[...], k=n) z!Expected dict for Aggregate, got zAggregate dict cannot be emptyr;z6Aggregate dict must contain exactly one operator, got $min_kr$max_kzUnknown aggregate operator: ) rIrJrKrLr*rMrOrQrRrrMinKMaxK)r8rcrrrs r(rPzAggregate.from_dictys$%?T @S@S?TUV V=> > t9>HT T $tyy{# $ >(T2GD!TQ' ' 8^(T2GD!TQ' ';B4@A Ar)N) r*r+r,rmrrTr r6rnrPr/r)r(rrbsK"Ic3hIBS#XB;BBr)rcLeZdZUdZeeeefed<e ed<de ee ffdZ y)rz:Keep k records with minimum aggregate key values per grouprrrr!cJdt|j|jdiS)Nrrrrrrr&s r(r6z MinK.to_dict #3DII#>TVVLMMr)N r*r+r,rmrr rUrTr-rXrr r6r/r)r(rr3D E#s(O $$ FNc3hNr)rcLeZdZUdZeeeefed<e ed<de ee ffdZ y)rz:Keep k records with maximum aggregate key values per grouprrrr!cJdt|j|jdiS)Nrrrr&s r(r6z MaxK.to_dictrr)Nrr/r)r(rrrr)rceZdZUdZeeZeee e fe d<dZ e ee d<dee effdZedee efddfd Zy) GroupByadGroup results by metadata keys and aggregate within each group. Groups search results by one or more metadata fields, then applies an aggregation (MinK or MaxK) to select records within each group. The final output is flattened and sorted by score. Args: keys: Metadata key(s) to group by. Can be a single key or a list of keys. E.g., Key("category") or [Key("category"), Key("author")] aggregate: Aggregation to apply within each group (MinK or MaxK) Note: Both keys and aggregate must be specified together. Examples: # Top 3 documents per category (single key) GroupBy( keys=Key("category"), aggregate=MinK(keys=Key.SCORE, k=3) ) # Top 2 per (year, category) combination (multiple keys) GroupBy( keys=[Key("year"), Key("category")], aggregate=MinK(keys=Key.SCORE, k=2) ) # Top 1 per category by priority, score as tiebreaker GroupBy( keys=Key("category"), aggregate=MinK(keys=[Key("priority"), Key.SCORE], k=1) ) rrN aggregater!c|jr |jiSdt|ji}|jj|d<|S)z:Convert the GroupBy to a dictionary for JSON serializationrr)rrrr6rs r(r6zGroupBy.to_dictsIyyDNN2I"(*:499*E!F"nn446{ r)r8c t|ts!tdt|j|s t Sd|vr t dd|vr t d|d}t|ttfs!tdt|j|s t d|d}t|ts!tdt|jtj|}t t|| S) zCreate GroupBy from dictionary. Examples: - {} -> GroupBy() (default, no grouping) - {"keys": ["category"], "aggregate": {"$min_k": {"keys": ["#score"], "k": 3}}} zExpected dict for GroupBy, got rzGroupBy requires 'keys' fieldrz"GroupBy requires 'aggregate' fieldz!GroupBy keys must be a list, got zGroupBy keys cannot be emptyz&GroupBy aggregate must be a dict, got )rr) rIrJrKrLr*rrMrNr rrPr)r8raggregate_datars r(rPzGroupBy.from_dicts$%=d4j>Q>Q=RST T9   <= = d "AB BF|$u .?T @S@S?TUV V;< <k*.$/8n9M9V9V8WX ''7 ,T2iHHr))r*r+r,rmrrNrrr rUrTr-rrrrr r6rnrPr/r)r(rrswB(-T'BD)E#s(O $B%)Ix ")c3h!IS#X!I9!I!Ir)r)S dataclassesrrtypingrrrrr r r chromadb.base_typesr numpyr  numpy.typingr chromadb.api.typesrrrrrrrrrrchromadb.typesrrrrr1rfrkrxrrrrrrrrrrrrUrrrrrrhrrrrrr<r2rArCrDrGr-rr&rr rprrTrr rrXrrrrrr/r)r(rs:(>>>,            G!G! G!T @%@ @ ?? ? // / // / // / 0%0 0 // / 0%0 0 00 0 1%1 1 5u5 5 9%9 9 4E4 4 8u8 8w-w-v U; L! ; M  )) )     .1.1 .1b  0 ['[' ['|  -$- - V$V V -$- - -$- - ;$; ; ;$; ; ;$; ; C $C  C L V$V V ;$; ; $$$ $ [$$[$ [$| R*R* R*pD9U38_5D$s)D ?5cE#s(O!;<?eCQTHoAV? $% $%S>$% 4c3h # %&$%N 2B2B 2Bj N9N N N9N N PIPI PIr)