LKi SSKJrJr SSKJrJrJrJrJrJ r J r SSK J r SSK rSSKJr SSKJrJrJrJrJrJrJrJrJrJr SSKJrJrJr \"SS 55r \"S S 55r!\"S S \!55r"\"SS\!55r#\"SS\!55r$\"SS\!55r%\"SS\!55r&\"SS\!55r'\"SS\!55r(\"SS\!55r)\"SS\!55r*\"SS\!55r+\"S S!\!55r,\"S"S#\!55r-\"S$S%\!55r.\"S&S'\!55r/"S(S)5r0\0"S*5\0l1\0"S+5\0l2\0"S,5\0l3\0"S-5\0l4\0"S.5\0l5\0r6\"S/S055r7\"S1S255r8\"S3S455r9\"S5S655r:\"S7S855r;\"S9S:\;55r<\"S;S<\;55r=\"S=S>\;55r>\"S?S@\;55r?\"SASB\;55r@\"SCSD\;55rA\"SESF\;55rB\"SGSH\;55rC\"SISJ\;55rD\"SKSL\;55rE\"SMSN\;55rF\"SOSP\;55rG\"SQSR55rHSS\\ \0\I4ST\\I4SUjrJSS\ \\\K\SV44ST\\ \0\I44SWjrLSX\ISY\\I\4ST\K\\ \0\I4\M44SZjrN\"S[S\55rO\"S]S^\O55rP\"S_S`\O55rQ\"SaSb55rRg)c) dataclassfield)OptionalListDictSetAnyUnioncast) LiteralValueN)NDArray) EmbeddingsIDsInclude OneOrMany SparseVectorTYPE_KEYSPARSE_VECTOR_TYPE_VALUEmaybe_cast_one_to_manynormalize_embeddingsvalidate_embeddings) CollectionRequestVersionContextSegmentcV\rSrSr%\\S'\\S'\\S'\\S'\S\4Sj5r Sr g ) Scan collectionknnmetadatarecordreturncf[URRURRS9$)N)collection_version log_position)rrversionr%selfs h/var/www/html/dynamic-report/venv/lib/python3.13/site-packages/chromadb/execution/expression/operator.pyr& Scan.version"s)$#6655  N) __name__ __module__ __qualname____firstlineno__r__annotations__rpropertyrr&__static_attributes__r,r+r)rrs2 L O  .  r+rcj\rSrSrSrS\\\44Sjr\ S\\\4SS4Sj5r S Sjr S Sjr S r g ) Where+aBase 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"c[S5e)zCConvert the Where expression to a dictionary for JSON serialization#Subclasses must implement to_dict()NotImplementedErrorr's r)to_dict Where.to_dictB!"GHHr+datac" [U[5(d![S[U5R35eU(d [ S5eSU;a[US[ 5(d$[S[US5R35e[US5S:Xa [ S5e[U5S:a [ S5eUSVs/sHn[RU5PM nn[U5S:XaUS$USnUSS HnX1-nM U$S U;a[US [ 5(d$[S [US 5R35e[US 5S:Xa [ S 5e[U5S:a [ S 5eUS Vs/sHn[RU5PM nn[U5S:XaUS$USnUSS HnX1-nM U$[U5S:wa[ S[U535e[[UR555upE[U[5(d![S[U5R35e[U[5(GaU(d[ SUS35e[U5S:wa[ SUS35e[[UR555upgUS:Xa[U5U:H$US:Xa[U5U:g$US:Xa[U5U:$US:Xa[U5U:$US:Xa[U5U:$US:Xa[U5U:*$US:XaP[U[ 5(d![S[U5R35e[U5RU5$US:XaP[U[ 5(d![S[U5R35e[U5R!U5$US:Xa`[U[["[$[&45(d![S[U5R35e[U5R)U5$US:Xa`[U[["[$[&45(d![S [U5R35e[U5R+U5$US!:XaP[U[5(d![S"[U5R35e[U5R-U5$US#:XaP[U[5(d![S$[U5R35e[U5R/U5$[ S%U35e[U5U:H$s snfs snf)&aCreate 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- ValueErrorlistlenr5 from_dictnextiteritemsstrKeyis_innot_inintfloatboolcontains not_containsregex not_regex)r>c conditionsresultr conditionopvalues r)rVWhere.from_dictFse*$%%;DJd6lD11/T&\0B0K0K/LM4< A% !GHH4y1} P7;6lCl%//!,lJC:!#!!}$]F^$M d]d5k400":4U ;L;U;U:V WXX4;1$ !FGG4y1} O7;5kBk%//!,kJB:!#!!}$]F^$M4yA~ Ec$i[Q $D$67 EeS))7U 8L8L7MN)T** $3E7:KLy>Q&$3E7:]^!ioo&7!89 ;u:..5[u:..5[u:--6\u:..5[u:--6\u:..5[%eT22'7U 8L8L7MNu:++E226\%eT22'8e9M9M8NOu:,,U33;&%ec3t-DEE'QRVW\R]RfRfQghu:..u55?*%ec3t-DEE'UVZ[`VaVjVjUklu:225998^%eS11'DT%[EYEYDZ[u:++E22<'%eS11'HeI]I]H^_u://66$'9"%>??5zY..SD$Cs VV c@[U[5(aP[U[5(a"[URUR-5$[URU/-5$[U[5(a[U/UR-5$[X/5$)zOverload & operator for AND)rOAndrfr(others r)__and__ Where.__and__s dC %%%4??U-=-==>>t%01 1 s # #v 0 001 1D=!!r+c@[U[5(aP[U[5(a"[URUR-5$[URU/-5$[U[5(a[U/UR-5$[X/5$)zOverload | operator for OR)rOOrrfrns r)__or__ Where.__or__s dB  %$$$//E,<,<<==doo/0 0 r " "tfu///0 04-  r+r,N)ror5r"rm)ror5r"rs)r-r.r/r0__doc__rrZr r; staticmethodrVrprtr3r,r+r)r5r5+sV*Ic3hIP/S#XP/7P/P/d " !r+r5cB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)rmz(Logical AND of multiple where conditionsrfr"cdSURVs/sHoR5PM sn0$s snf)Nr@rfr;r(res r)r; And.to_dicts'doo>oo>??>-r,N r-r.r/r0rvrr5r1rrZr r;r3r,r+r)rmrms%2U @c3h@r+rmcB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)rsz'Logical OR of multiple where conditionsrfr"cdSURVs/sHoR5PM sn0$s snf)NrBr{r|s r)r; Or.to_dicts'T__=_ _=>>=r~r,Nrr,r+r)rsrss#1U ?c3h?r+rscF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) Eqi zEquality comparisonkeyrjr"c6URSUR00$)NrCrrjr's r)r; Eq.to_dict5$**-..r+r,N r-r.r/r0rvrZr1r rr;r3r,r+r)rr s# H J/c3h/r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) NeizNot equal comparisonrrjr"c6URSUR00$)NrDrr's r)r; Ne.to_dictrr+r,Nrr,r+r)rr# H J/c3h/r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) Gti zGreater than comparisonrrjr"c6URSUR00$)NrErr's r)r; Gt.to_dict'rr+r,Nrr,r+r)rr s#! H J/c3h/r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) Gtei+z Greater than or equal comparisonrrjr"c6URSUR00$)NrFrr's r)r; Gte.to_dict264::.//r+r,Nrr,r+r)rr+s#* H J0c3h0r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) Lti6zLess than comparisonrrjr"c6URSUR00$)NrGrr's r)r; Lt.to_dict=rr+r,Nrr,r+r)rr6rr+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) LteiAzLess than or equal comparisonrrjr"c6URSUR00$)NrHrr's r)r; Lte.to_dictHrr+r,Nrr,r+r)rrAs#' H J0c3h0r+rcL\rSrSr%Sr\\S'\\\S'S\ \\44Sjr Sr g) IniLz"In comparison - value is in a listrvaluesr"c6URSUR00$)NrIrrr's r)r; In.to_dictSs5$++.//r+r,N r-r.r/r0rvrZr1rr rr;r3r,r+r)rrLs(, H I0c3h0r+rcL\rSrSr%Sr\\S'\\\S'S\ \\44Sjr Sr g) NiniWz*Not in comparison - value is not in a listrrr"c6URSUR00$)NrJrr's r)r; Nin.to_dict^s64;;/00r+r,Nrr,r+r)rrWs(4 H I1c3h1r+rcF\rSrSr%Sr\\S'\\S'S\\\ 44Sjr Sr g) ContainsibzEContains comparison for document content or metadata array membershiprrjr"c6URSUR00$)NrKrr's r)r;Contains.to_dictis; 344r+r,N r-r.r/r0rvrZr1r rr r;r3r,r+r)rrbs$O H 5c3h5r+rcF\rSrSr%Sr\\S'\\S'S\\\ 44Sjr Sr g) NotContainsimzINot-contains comparison for document content or metadata array membershiprrjr"c6URSUR00$)NrLrr's r)r;NotContains.to_dictts?DJJ788r+r,Nrr,r+r)rrms$S H 9c3h9r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) RegexixzRegular expression matchingrpatternr"c6URSUR00$)NrMrrr's r)r; Regex.to_dicts8T\\233r+r,N r-r.r/r0rvrZr1rr r;r3r,r+r)rrxs#% H L4c3h4r+rcF\rSrSr%Sr\\S'\\S'S\\\44Sjr Sr g) NotRegexiz$Negative regular expression matchingrrr"c6URSUR00$)NrNrr's r)r;NotRegex.to_dicts<677r+r,Nrr,r+r)rrs#. H L8c3h8r+rcL\rSrSr%SrS\S'S\S'S\S'S\S'S\S'S\4S jrS \4S jr S \ S \ 4S jr S \ S \ 4SjrS \ S \4SjrS \ S \4SjrS \ S \4SjrS \ S \4SjrS\\ S \4SjrS\\ S \4SjrS\S \4SjrS\S \4SjrS \ S \!4Sjr"S \ S \#4Sjr$Sr%g)r[ia;Field 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 EMBEDDINGMETADATASCOREnamecXlg)Nr)r(rs r)__init__ Key.__init__s r+r"c,[UR5$)z!Make Key hashable for use in sets)hashrr's r)__hash__ Key.__hash__sDIIr+rjc.[URU5$)zEquality: Key('field') == value)rrr(rjs r)__eq__ Key.__eq__$))U##r+c.[URU5$)z Not equal: Key('field') != value)rrrs r)__ne__ Key.__ne__rr+c.[URU5$)z"Greater than: Key('field') > value)rrrs r)__gt__ Key.__gt__rr+c.[URU5$)z,Greater than or equal: Key('field') >= value)rrrs r)__ge__ Key.__ge__499e$$r+c.[URU5$)zLess than: Key('field') < value)rrrs r)__lt__ Key.__lt__rr+c.[URU5$)z)Less than or equal: Key('field') <= value)rrrs r)__le__ Key.__le__rr+rc.[URU5$)z?Check if field value is in list: Key('field').is_in(['a', 'b']))rrr(rs r)r\ Key.is_ins$))V$$r+c.[URU5$)zDCheck if field value is not in list: Key('field').not_in(['a', 'b']))rrrs r)r] Key.not_ins499f%%r+rc.[URU5$)z9Match field against regex: Key('field').regex('^pattern'))rrr(rs r)rc Key.regexsTYY((r+c.[URU5$)z@Field should not match regex: Key('field').not_regex('^pattern'))rrrs r)rd Key.not_regexs 7++r+cURS:Xa [U[5(d [S5e[ URU5$)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)rrOrZrQrrs r)ra Key.containss9 99 #Juc,B,BNO O 5))r+cURS:Xa [U[5(d [S5e[ URU5$)a^Check 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)rrOrZrQrrs r)rbKey.not_containss9 99 #Juc,B,BRS S499e,,r+rN)&r-r.r/r0rvr1rZrr^rr rrrrrrrrrrrrrrr\rr]rrcrrdr rrarrbr3r,r+r)r[r[s(!H IOO LS# $C$B$$C$B$$C$B$%C%C%$C$B$%C%C% %DI%"%&T#Y&3&)S)U),,, *l *x * -, -; -r+r[#idr #embedding #metadata#scorecR\rSrSr%Sr\\\S'Sr\\ \S'Sr \\ \S'Sr g)FilteriNuser_idswherewhere_documentr,) r-r.r/r0rrrr1rr rr3r,r+r)rrs,"Hhsm"E8C=$(NHSM(r+rc*\rSrSr%\\S'\\S'Srg)KNNi embeddingsfetchr,N)r-r.r/r0rr1r^r3r,r+r)rrs  Jr+rcv\rSrSr%Sr\\S'Sr\\\S'S\ \ \ 44Sjr \ S\ \ \ 4SS4S j5rS rg) Limiti!roffsetNlimitr"cZSUR0nURbURUS'U$)z8Convert the Limit to a dictionary for JSON serializationrrrrr(rgs r)r; Limit.to_dict&s,DKK( :: !"jjF7O r+r>c^[U[5(d![S[U5R35eUR SS5n[U[ 5(d![S[U5R35eUS:a[SU35eUR S5nUbJ[U[ 5(d![S[U5R35eUS::a[SU35eSS1n[UR55U- nU(a[S U35e[XS 9$) 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) rOrPrQrRr-getr^rSsetkeysr)r>rr allowed_keysunexpected_keyss r)rVLimit.from_dict-s,$%%;DJ>OPQ QF00r+r,)r-r.r/r0rr^r1rrrrZr r;rwrVr3r,r+r)rr!sWFCOE8C=c3h"1S#X"17"1"1r+rct\rSrSr%Sr\\S'Sr\\S'Sr\\S'Sr \\S'Sr \\S'\ S\ 4S j5r S rg ) ProjectioniSFdocument embeddingr rankurir"cn[5nUR(aURS5 UR(aURS5 UR(aURS5 UR (aURS5 UR (aURS5 U$)N documentsr metadatas distancesuris)rTrappendrr rr)r(includess r)includedProjection.included[sm6 == OOK ( >> OOL ) == OOK ( 99 OOK ( 88 OOF #r+r,N)r-r.r/r0rr`r1rr rrr2rrr3r,r+r)rrSsMHdItHdD$C  '  r+rc\rSrSrSrS\\\44Sjr\ S\\\4SS4Sj5r S\ S\ \ 4SS4S jrS\ \ \ 4SS4S jrS\ S\ \ 4SS 4S jrS\ \ \ 4SS 4S jrS\ S\ \ 4SS4SjrS\ \ \ 4SS4SjrS\ S\ \ 4SS4SjrS\ \ \ 4SS4SjrSSjrS SjrS SjrS!SjrS"SjrS\ S\ \ 4SS4SjrS\ S\ \ 4SS4SjrSrg)#RankilaBase 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"c[S5e)zCConvert the Score expression to a dictionary for JSON serializationr8r9r's r)r; Rank.to_dictr=r+r>c[U[5(d![S[U5R35eU(d [ S5e[ U5S:wa[ S[ U535e[[UR555nUS:XaLUSn[U[[45(d![S[U5R35e[U5$US:XGaFUSn[U[5(d![S[U5R35eS U;a [ S 5eUS n[U[5(aPUR[5[:Xa[ R""U5nO[ S [S [S U35e[U[$[&[(R*45(a=[-U5nU(a[ U5S:a [ S5e[/U5 USnO![S[U5R35eURSS5n[U[05(d![S[U5R35eURSS5n[U[5(d![S[U5R35eUS::a[ SU35eURSS5n[U[25(d![S[U5R35e[5UUUURS5US9$US:XaUSn [U [$[&45(d![S[U 5R35e[ U 5S:a[ S [ U 535eU V s/sHn [6R#U 5PM n n U Sn U SS!Hn X-n M U $US":XaUS"n [U [5(d![S#[U 5R35eS$U ;dS%U ;a [ S&5e[6R#U S$5n[6R#U S%5nX- $US':XaUS'n [U [$[&45(d![S([U 5R35e[ U 5S:a[ S)[ U 535eU V s/sHn [6R#U 5PM n n U Sn U SS!Hn X-n M U $US*:XaUS*n[U[5(d![S+[U5R35eS$U;dS%U;a [ S,5e[6R#US$5n[6R#US%5nX- $US-:XaYUS-n[U[5(d![S.[U5R35e[9[6R#U55$US/:Xa^US/n[U[5(d![S0[U5R35e[6R#U5R;5$US1:Xa^US1n[U[5(d![S2[U5R35e[6R#U5R=5$US3:XaUS3n [U [$[&45(d![S4[U 5R35e[ U 5S:a[ S5[ U 535eU V s/sHn [6R#U 5PM n n U Sn U SS!Hn U R?U 5n M U $US6:XaUS6n [U [$[&45(d![S7[U 5R35e[ U 5S:a[ S8[ U 535eU V s/sHn [6R#U 5PM n n U Sn U SS!Hn U RAU 5n M U $[ S9U35es sn fs sn fs sn fs sn f):a Create 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 emptyrAz1Rank 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 rrz$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)r&rrr)r($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: )!rOrPrQrRr-rSrUrWrXr r^r_Valr rrrrVrTtuplenpndarrayrrrZr`Knnr absexplogmaxmin)r>rirjknn_datar& normalizedrrr( ranks_datarranksrgsub_datar-r.div_data child_datas r)rVRank.from_dicts "$%%:4:;N;N:OPQ Q89 9 t9>CCI;O $tyy{# $ <LEec5\22">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-880j1A1J1J0KL:" :3z?:KL1;; 1T^^A& E;1XF12YM 6\F|Hh--HhI`I`HabX%)@ !JKK>>(6"23DNN8G#45E<  6\fJj4-880j1A1J1J0KL:" :3z?:KL1;; 1T^^A& E;1XF12YM 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-880j1A1J1J0KL:" :3z?:KL1;; 1T^^A& E;1XF12YAM 6\fJj4-880j1A1J1J0KL:" :3z?:KL1;; 1T^^A& E;1XF12YAM6rd;< Rank.max#-ec5\#B#BSZ  dC *c**4:: (8(8899tzzZL01 1  C ( (v 0 001 1D%&&r+Minc[U[[45(a [U5OUn[U[5(aP[U[5(a"[ UR UR -5$[ UR U/-5$[U[5(a[ U/UR -5$[ X/5$)z1Minimum of this rank and another: rank.min(rank2))rOr^r_r6rrDrKs r)r?Rank.minrr+r,N)r"r^)r"rr)r"ry)r"r|)r-r.r/r0rvrrZr r;rwrVr r_r^rMrRrWr[r`rcrgrjrnrsr;r<r=r>r?r3r,r+r)r r ls6Ic3hIX=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+r c<\rSrSr%Sr\\S'S\\\ 44Sjr Sr g)rrizAbsolute value of a rankrr"c:SURR50$)Nr1rr;r's r)r; Abs.to_dict ))+,,r+r,N r-r.r/r0rvr r1rrZr r;r3r,r+r)rrrr" J-c3h-r+rrcF\rSrSr%Sr\\S'\\S'S\\\ 44Sjr Sr g) reizDivision of two ranksr-r.r"cpSURR5URR5S.0$)Nr0r-r.r-r;r.r's r)r; Div.to_dict,!2!2!4tzz?Q?Q?STUUr+r,Nrr,r+r)reres% J KVc3hVr+rec<\rSrSr%Sr\\S'S\\\ 44Sjr Sr g)ryizExponentiation of a rankrr"c:SURR50$)Nr2rr's r)r; Exp.to_dictrr+r,Nrr,r+r)ryryrr+ryc<\rSrSr%Sr\\S'S\\\ 44Sjr Sr g)r|izLogarithm of a rankrr"c:SURR50$)Nr3rr's r)r; Log.to_dictrr+r,Nrr,r+r)r|r|s J-c3h-r+r|cB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)r~izMaximum of multiple ranksrDr"cdSURVs/sHoR5PM sn0$s snf)Nr4rDr;r(rCs r)r; Max.to_dict'djj9jj9::9r~r,N r-r.r/r0rvrr r1rrZr r;r3r,r+r)r~r~## :;c3h;r+r~cB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)rizMinimum of multiple ranksrDr"cdSURVs/sHoR5PM sn0$s snf)Nr5rrs r)r; Min.to_dictrr~r,Nrr,r+r)rrrr+rcB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)r^iz Multiplication of multiple ranksrDr"cdSURVs/sHoR5PM sn0$s snf)Nr/rrs r)r; Mul.to_dictrr~r,Nrr,r+r)r^r^s#* :;c3h;r+r^c\rSrSr%Sr\\\\\ SSS4\ S'\ Rr \\\4\ S'Sr\\ S 'S r\\\ S 'S r\\ S 'S\\\44SjrSrg )r:iakKNN-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]r&rr'rNr)Fr(r"cURn[U[5(aUR5nO/[U[R 5(aUR 5nURn[U[5(a URnXURS.nURbURUS'UR(aURUS'SU0$)N)r&rrr)r(r%) r&rOrr;r8r9tolistrr[rrr)r()r( query_value key_valuergs r)r; Knn.to_dict?sjj k< 0 0%--/K  RZZ 0 0%,,.KHH i % %!I'4::N << # $ F9    $($4$4F= !r+r,)r-r.r/r0rvr rZrr_rr1Krrr[rr^r)rr(r`rr r;r3r,r+r)r:r:s~<   U    ;;CsCx&E3O#GXe_#K c3h r+r:cF\rSrSr%Sr\\S'\\S'S\\\ 44Sjr Sr g) rUiYzSubtraction of two ranksr-r.r"cpSURR5URR5S.0$)Nr,rrr's r)r; Sub.to_dict`rr+r,Nrr,r+r)rUrUYs%" J KVc3hVr+rUcB\rSrSr%Sr\\\S'S\\ \ 44Sjr Sr g)rIidzSummation of multiple ranksrDr"cdSURVs/sHoR5PM sn0$s snf)Nr*rrs r)r; Sum.to_dictjrr~r,Nrr,r+r)rIrIds#% :;c3h;r+rIc<\rSrSr%Sr\\S'S\\\ 44Sjr Sr g)r6inzConstant rank valuerjr"cSUR0$)Nr$)rjr's r)r; Val.to_dictts ##r+r,N) r-r.r/r0rvr_r1rrZr r;r3r,r+r)r6r6ns L$c3h$r+r6cx\rSrSr%Sr\\\S'Sr\ \S'Sr \ \\ \S'Sr \\S 'S \\\44S jrS rg) RrfixaMReciprocal 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 ) rD<kNweightsF normalizer"cUR(d [S5eURS::a[SUR35eURb[ UR5[ UR5:wa8[S[ UR5S[ UR5S35e[ SUR55(a [S 5eUR(a UROS /[ UR5-nUR (a0[U5nUS:Xa [S 5eUVs/sHo3U- PM nn[XR5VVs/sHup4X0RU-- PM nnnUSnUS SHnXg-nM U*R5$s snfs snnf) 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*# UH oS:v M g7f)gNr,).0ws r) Rrf.to_dict..s1Lqs7Lsz All weights must be non-negativeg?z3Sum of weights must be positive when normalize=TruerA) rDrSrrrUanyrsumzipr;)r(r weight_sumrrtermsrrf_sumterms r)r; Rrf.to_dictszz=> > 66Q;7x@A A << #4<< C O3 )#dll*;)<>WJQ !VWW/67w!:~wG7584LM4Lfftm$4LMa!"IDnG!!##8Ns F71F<r,)r-r.r/r0rvrr r1rr^rrr_rr`rrZr r;r3r,r+r)rrxsN+Z : AsK%)GXd5k ")It($c3h($r+rc~\rSrSr%Sr\"\S9r\\ \ \ 4\ S'S\ \ \44Sjr\S\ \ \4SS4Sj5rS rg ) SelectiaSelection 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_factoryr r"c/nURHFn[U[5(aURUR5 M5URU5 MH S[ [ RU550$)z9Convert the Select to a dictionary for JSON serializationr )r rOr[rrrTrPfromkeys)r( key_stringsrs r)r;Select.to_dicts_ A!S!!""166*""1%  T]];7899r+r>c[U[5(d![S[U5R35eUR S/5n[U[ [[45(d![S[U5R35e/nUGHn[U[5(d![S[U5R35eUS:Xa!UR[R5 MaUS:Xa!UR[R5 MUS:Xa!UR[R5 MUS:Xa!UR[R5 MUS :Xa!UR[R 5 MUR[U55 GM S1n[UR#55U- nU(a[%S U35e['[U5S 9$) 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 r z*Select keys must be a list/tuple/set, got z!Select key must be a string, got rrrrrz Unexpected keys in Select dict: )r )rOrPrQrRr-r rTr7r rZrr[rrrrrr rSr)r>r key_listrr rs r)rVSelect.from_dicts$%%AjC((CFa / >> >s,4rir>c:Xn[U[5(d#[US[U5R35eSU;a[ US35eSU;a[ US35eUSn[U[ [45(d#[US[U5R35eU(d[ US35eUSn[U[5(d#[US[U5R35eUS ::a[ US U35e[U5U4$) aTParse 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 r z requires 'keys' fieldrz 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 ) rOrPrQrRr-rSrTr7r^r)rir>agg_datar rs r)_parse_k_aggregater;s) xH h % %2$4T(^5L5L4MNOO XB45677 (B42344 F D dT5M * *2$8d9L9L8MNOO B44566 A a  2$9$q':J:J9KLMMAvB48<== D !1 $$r+cV\rSrSrSrS\\\44Sjr\ S\\\4SS4Sj5r Sr g) Aggregateiba Base 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"c[S5e)zGConvert the Aggregate expression to a dictionary for JSON serializationr8r9r's r)r;Aggregate.to_dictur=r+r>c[U[5(d![S[U5R35eU(d [ S5e[ U5S:wa[ S[ U535e[[UR555nUS:Xa[X5up#[X#S9$US:Xa[X5up#[X#S9$[ SU35e) 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 emptyrAz6Aggregate dict must contain exactly one operator, got $min_kr$max_kzUnknown aggregate operator: ) rOrPrQrRr-rSrUrWrXr rMinKMaxK)r>rir rs r)rVAggregate.from_dictys$%%?T @S@S?TUV V=> > t9>HT T $tyy{# $ >(2GDT' ' 8^(2GDT' ';B4@A Ar+r,N) r-r.r/r0rvrrZr r;rwrVr3r,r+r)rrbsK"Ic3hIBS#XB;BBr+rcV\rSrSr%Sr\\\\4\ S'\ \ S'S\ \\ 44Sjr Srg) riz:Keep k records with minimum aggregate key values per groupr rr"cJS[UR5URS.0$)Nrrrr rr's r)r; MinK.to_dict #3DII#>TVVLMMr+r,Nr-r.r/r0rvrr r[rZr1r^rr r;r3r,r+r)rr3D E#s(O $$ FNc3hNr+rcV\rSrSr%Sr\\\\4\ S'\ \ S'S\ \\ 44Sjr Srg) riz:Keep k records with maximum aggregate key values per groupr rr"cJS[UR5URS.0$)Nrrrr's r)r; MaxK.to_dictrr+r,Nrr,r+r)rrrr+rc\rSrSr%Sr\"\S9r\\ \ \ 4\ S'Sr \\\ S'S\\ \44Sjr\S \\ \4SS4S j5rS rg) GroupByiaGroup 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) ) rr N aggregater"cUR(a URc0$S[UR50nURR5US'U$)z:Convert the GroupBy to a dictionary for JSON serializationr r)r rrr;rs r)r;GroupBy.to_dictsIyyDNN2I"(*:499*E!F"nn446{ r+r>c@[U[5(d![S[U5R35eU(d [ 5$SU;a [ S5eSU;a [ S5eUSn[U[[45(d![S[U5R35eU(d [ S5eUSn[U[5(d![S[U5R35e[RU5n[ [U5US 9$) zCreate GroupBy from dictionary. Examples: - {} -> GroupBy() (default, no grouping) - {"keys": ["category"], "aggregate": {"$min_k": {"keys": ["#score"], "k": 3}}} zExpected dict for GroupBy, got r zGroupBy 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 )r r) rOrPrQrRr-rrSrTr7rrVr)r>r aggregate_datars r)rVGroupBy.from_dicts $%%=d4j>Q>Q=RST T9   <= = d "AB BF|$u ..?T @S@S?TUV V;< <k*.$//8n9M9V9V8WX ''7 ,T2iHHr+r,)r-r.r/r0rvrrTr rr r[rZr1rrrrr r;rwrVr3r,r+r)rrswB(-T'BD)E#s(O $B%)Ix ")c3h!IS#X!I9!I!Ir+r)S dataclassesrrtypingrrrrr r r chromadb.base_typesr numpyr8 numpy.typingr chromadb.api.typesrrrrrrrrrrchromadb.typesrrrrr5rmrsrrrrrrrrrrrrr[rrrrrrrrrrr rrreryr|r~rr^r:rUrIr6rrrZrr7rr^rrrrrr,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+