soev_retrieval.domain
Describe what a store searches, what it returns, and the filters that narrow a search.
These names are plain data. They cross the VectorStore boundary in both directions, so every store and every
search uses the same types.
Search results
A search names a target and returns hits. A fetch returns chunks.
Target
type aliasTarget = strThe name of what a store searches.
Only the store reads the name. The store resolves it to a collection, a collection and a tenant, or a filtered view, as its backend and the layout of the deployment decide.
SearchScope
dataclassSearchScope(target, where=None)What one search covers: a target, narrowed by where when given (a folder, a sync, a document set).
paramtargetTargetThe target to search.
paramwhereFilter | None= NoneThe filter that narrows the target, or None to search all of it.
Hit
dataclassHit(id, document_id, score, properties)One chunk that a search returned, best first when in a sequence.
score is assigned by the store that answered, and compares only against other hits from the same call. A
Weaviate fusion score and a pgvector blended score are different quantities. So order by it, and never threshold on
it.
paramidstrThe opaque id of the chunk. It is stable for the chunk.
paramdocument_idstrThe document that the chunk came from, the unit that a deletion applies to.
paramscorefloatThe score that the answering store gave the hit.
parampropertiesMapping[str, object]The stored fields that the store returned.
Chunk
dataclassChunk(id, document_id, properties)One chunk that a fetch returned: a Hit without a score, because nothing was searched for.
paramidstrThe opaque id of the chunk. It is stable for the chunk.
paramdocument_idstrThe document that the chunk came from.
parampropertiesMapping[str, object]The stored fields that the store returned.
Filters
A filter is one predicate on a stored field, or predicates combined with AllOf, AnyOf and Not.
Filter
type aliasFilter = DeclaredFilter | AllOf | AnyOf | NotA filter expression: one predicate, or predicates combined with AllOf, AnyOf and Not.
A search or a fetch takes it as where. None in place of a filter restricts nothing.
DeclaredFilter
dataclassDeclaredFilter(field, op, value)One predicate on a stored field: field op value.
op names an entry of OPERATORS, which declares whether value is one scalar or a sequence of them, and which
field types the operator is defined on. A store checks a filter against its field spec and refuses rather than
guesses. AllOf, AnyOf and Not combine predicates.
Example
from soev_retrieval.domain import AllOf, DeclaredFilter, Not
where = AllOf(
DeclaredFilter("year", "gte", 2020),
Not(DeclaredFilter("tags", "contains_any", ("forms",))),
)paramfieldstrThe name of the stored field.
paramopstrThe name of an operator in OPERATORS, for example "eq", "in" or "gte".
paramvalueScalar | tuple[Scalar, ...] | list[Scalar]The operand: one Scalar, or a tuple or list of them for an operator that takes many.
AllOf
dataclassAllOf(*terms)A filter that holds when every one of its terms holds.
With no terms, it matches everything. Give the terms as positional arguments: AllOf(first, second).
paramtermsFilterThe filters that must all hold.
AnyOf
dataclassAnyOf(*terms)A filter that holds when at least one of its terms holds.
With no terms, it matches nothing: see NOTHING. Give the terms as positional arguments: AnyOf(first, second).
paramtermsFilterThe filters of which at least one must hold.
Not
dataclassNot(term)A filter that holds when its term does not hold.
paramtermFilterThe filter that must not hold.
NOTHING
constantNOTHING: Final = AnyOf()The filter that no chunk satisfies, for example a folder that a rewrite found empty.
A store answers it with an empty sequence and does not search. simplify folds a filter that matches nothing to it.
Scalar
type aliasScalar = str | int | float | boolOne operand value of a DeclaredFilter.
Fields
A store declares the stored fields of each target, and which of them a filter can name.
FieldSpec
type aliasFieldSpec = Mapping[str, tuple[FieldType, bool]]The stored fields of a target: each field name maps to its FieldType and to whether a filter can name it.
VectorStore.fields returns it, and validate checks a filter against it.
FieldType
type aliasFieldType = Literal['keyword', 'text', 'number', 'date', 'bool']The type of a stored field. It decides which operand values a filter on the field takes.
A keyword, text or date field takes a str, and a date is ISO 8601 text. A number field takes an int or a
float. A bool field takes a bool, and a bool is never a number.
A list field has the type of its items. For example, a field tags that holds keywords is a keyword field.