Hybrid capability

Base class and models for hybrid search operations.

This module defines hybrid search configuration models and BaseHybridCapability, which datastores implement for hybrid search combining fulltext and vector retrieval paradigms.

BaseHybridCapability(encryption=None, default_batch_size=None)

Bases: DataStoreCapability

Base class for hybrid capability implementations.

create(chunks, batch_size=None, **kwargs) async

Create chunks with automatic encryption and batching.

Parameters:

Name	Type	Description	Default
chunks	list[Chunk]	Chunks to create and index.	required
batch_size	int | None	Override batch size. Defaults to None.	None
**kwargs	Any	Passed to subclass _create.	{}

create_from_vector(chunks, dense_vectors=None, batch_size=None, **kwargs) async

Create from pre-computed vectors with encryption and batching.

Parameters:

Name	Type	Description	Default
chunks	list[Chunk]	Chunks to index.	required
dense_vectors	dict[str, list[tuple[Chunk, Vector]]] | None	Per-field vectors. Defaults to None.	None
batch_size	int | None	Override batch size; controls actual batching. Defaults to None.	None
**kwargs	Any	Passed to subclass.	{}

retrieve(query, filters=None, options=None, **kwargs) async

Retrieve using hybrid search with automatic decryption.

Parameters:

Name	Type	Description	Default
query	str	Query text to search with.	required
filters	FilterClause | QueryFilter | None	Query filters to apply. Defaults to None.	None
options	QueryOptions | None	Query options like limit and sorting. Defaults to None.	None
**kwargs	Any	Additional arguments passed to _retrieve.	{}

Returns:

Type	Description
list[Chunk]	list[Chunk]: Decrypted query results.

retrieve_by_vector(query=None, dense_vectors=None, filters=None, options=None, **kwargs) async

Retrieve by pre-computed vectors with automatic decryption.

Parameters:

Name	Type	Description	Default
query	str | None	Optional query text. Defaults to None.	None
dense_vectors	dict[str, Vector] | None	Field name to query vector. Defaults to None.	None
filters	FilterClause | QueryFilter | None	Filters. Defaults to None.	None
options	QueryOptions | None	Query options. Defaults to None.	None
**kwargs	Any	Passed to _retrieve_by_vector.	{}

Returns:

Type	Description
list[Chunk]	list[Chunk]: Decrypted chunks.

HybridSearchType

Bases: StrEnum

Types of searches that can be combined in hybrid search.

SearchConfig

Bases: BaseModel

Configuration for a single search component in hybrid search.

Examples:

FULLTEXT search configuration: python config = SearchConfig( search_type=HybridSearchType.FULLTEXT, field="text", weight=0.3 )

VECTOR search configuration: python config = SearchConfig( search_type=HybridSearchType.VECTOR, field="embedding", em_invoker=em_invoker, weight=0.5 )

Attributes:

Name	Type	Description
search_type	HybridSearchType	Type of search (FULLTEXT or VECTOR).
field	str	Field name in the index (e.g., "text", "embedding").
weight	float	Weight for this search in hybrid search. Defaults to 1.0.
em_invoker	BaseEMInvoker | None	Embedding model invoker required for VECTOR type. Defaults to None.
top_k	int | None	Per-search top_k limit (optional). Defaults to None.
extra_kwargs	dict[str, Any]	Additional search-specific parameters. Defaults to empty dict.

validate_field_not_empty(v) classmethod

Validate that field name is not empty.

Parameters:

Name	Type	Description	Default
v	str	Field name value.	required

Returns:

Name	Type	Description
str	str	Validated field name.

Raises:

Type	Description
ValueError	If field name is empty.

validate_search_requirements()

Validate configuration based on search type.

Returns:

Name	Type	Description
SearchConfig	'SearchConfig'	Validated configuration instance.

Raises:

Type	Description
ValueError	If required fields are missing for the search type.

validate_top_k(v) classmethod

Validate that top_k is positive if provided.

Parameters:

Name	Type	Description	Default
v	int | None	top_k value.	required

Returns:

Type	Description
int | None	int | None: Validated top_k value.

Raises:

Type	Description
ValueError	If top_k is provided but not positive.