Skip to content

Parameters

zvec.model.param

This module contains the params of Zvec

Modules:

Name Description
query

Classes:

Name Description
AddColumnOption

Options for adding a new column to a collection.
AlterColumnOption

Options for altering an existing column (e.g., changing index settings).
CollectionOption

Options for opening or creating a collection.
FlatIndexParam

Parameters for configuring a flat (brute-force) index.
HnswIndexParam

Parameters for configuring an HNSW (Hierarchical Navigable Small World) index.
HnswQueryParam

Query parameters for HNSW (Hierarchical Navigable Small World) index.
HnswRabitqIndexParam

Parameters for configuring an HNSW (Hierarchical Navigable Small World) index with RabitQ quantization.
HnswRabitqQueryParam

Query parameters for HNSW index with RabitQ quantization.
IVFIndexParam

Parameters for configuring an IVF (Inverted File Index) index.
IVFQueryParam

Query parameters for IVF (Inverted File Index) index.
FtsIndexParam

Parameters for configuring a full-text search (FTS) index.
FtsQueryParam

Query parameters for full-text search (FTS) index.
IndexOption

Options for creating an index.
IndexParam

Base class for all index parameter configurations.
InvertIndexParam

Parameters for configuring an invert index.
OptimizeOption

Options for optimizing a collection (e.g., merging segments).
QueryParam

Base class for all query parameter configurations.
SegmentOption

Options for segment-level operations.
VectorIndexParam

Base class for vector index parameter configurations.

Classes

AddColumnOption 

AddColumnOption(concurrency: SupportsInt = 0)

Options for adding a new column to a collection.

Attributes:

Name Type Description
concurrency int

Number of threads to use when backfilling data for the new column. If 0, auto-detect is used. Default is 0.

Examples:

>>> opt = AddColumnOption(concurrency=1)
>>> print(opt.concurrency)
1

Constructs an AddColumnOption instance.

Parameters:

Name Type Description Default
concurrency
int

Number of threads for data backfill. 0 means auto-detect. Defaults to 0.

 0
Attributes
concurrency property 
concurrency: int

int: Number of threads used when adding a column (0 = auto).

Methods:

AlterColumnOption 

AlterColumnOption(concurrency: SupportsInt = 0)

Options for altering an existing column (e.g., changing index settings).

Attributes:

Name Type Description
concurrency int

Number of threads to use during the alteration process. If 0, the system will choose an optimal value automatically. Default is 0.

Examples:

>>> opt = AlterColumnOption(concurrency=1)
>>> print(opt.concurrency)
1

Constructs an AlterColumnOption instance.

Parameters:

Name Type Description Default
concurrency
int

Number of threads for column alteration. 0 means auto-detect. Defaults to 0.

 0
Attributes
concurrency property 
concurrency: int

int: Number of threads used when altering a column (0 = auto).

Methods:

CollectionOption 

CollectionOption(read_only: bool = False, enable_mmap: bool = True)

Options for opening or creating a collection.

Attributes:

Name Type Description
read_only bool

Whether the collection is opened in read-only mode. Default is False.
enable_mmap bool

Whether to use memory-mapped I/O for data files. Default is True.

Examples:

>>> opt = CollectionOption(read_only=True, enable_mmap=False)
>>> print(opt.read_only)
True

Constructs a CollectionOption instance.

Parameters:

Name Type Description Default
read_only
bool

Open collection in read-only mode. Defaults to False.

 False
enable_mmap
bool

Enable memory-mapped I/O. Defaults to True.

 True
Methods:

FlatIndexParam 

FlatIndexParam(metric_type: MetricType = ..., quantize_type: QuantizeType = ...)

Bases: VectorIndexParam

Parameters for configuring a flat (brute-force) index.

A flat index performs exact nearest neighbor search by comparing the query vector against all vectors in the collection. It is simple, accurate, and suitable for small to medium datasets or as a baseline.

Attributes:

Name Type Description
metric_type MetricType

Distance metric used for similarity computation. Default is MetricType.IP (inner product).
quantize_type QuantizeType

Optional quantization type for vector compression (e.g., FP16, INT8). Use QuantizeType.UNDEFINED to disable quantization. Default is QuantizeType.UNDEFINED.

Examples:

>>> from zvec.typing import MetricType, QuantizeType
>>> params = FlatIndexParam(
...     metric_type=MetricType.L2,
...     quantize_type=QuantizeType.FP16
... )
>>> print(params)
{'metric_type': 'L2', 'quantize_type': 'FP16'}

Constructs a FlatIndexParam instance.

Parameters:

Name Type Description Default
metric_type
MetricType

Distance metric. Defaults to MetricType.IP.

 ...
quantize_type
QuantizeType

Vector quantization type. Defaults to QuantizeType.UNDEFINED (no quantization).

 ...

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
type property 
type: IndexType

IndexType: The type of the index.

metric_type property 
metric_type: MetricType

MetricType: Distance metric (e.g., IP, COSINE, L2).

quantize_type property 
quantize_type: QuantizeType

QuantizeType: Vector quantization type (e.g., FP16, INT8).

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

HnswIndexParam 

HnswIndexParam(
    metric_type: MetricType = ...,
    m: SupportsInt = 50,
    ef_construction: SupportsInt = 500,
    quantize_type: QuantizeType = ...,
    use_contiguous_memory: bool = False,
)

Bases: VectorIndexParam

Parameters for configuring an HNSW (Hierarchical Navigable Small World) index.

HNSW is a graph-based approximate nearest neighbor search index. This class encapsulates its construction hyperparameters.

Attributes:

Name Type Description
metric_type MetricType

Distance metric used for similarity computation. Default is MetricType.IP (inner product).
m int

Number of bi-directional links created for every new element during construction. Higher values improve accuracy but increase memory usage and construction time. Default is 50.
ef_construction int

Size of the dynamic candidate list for nearest neighbors during index construction. Larger values yield better graph quality at the cost of slower build time. Default is 500.
quantize_type QuantizeType

Optional quantization type for vector compression (e.g., FP16, INT8). Default is QuantizeType.UNDEFINED to disable quantization.
use_contiguous_memory bool

If True, the HNSW streamer allocates a single contiguous memory arena for all graph nodes, improving cache locality and search throughput at the cost of peak memory usage. Default is False.

Examples:

>>> from zvec.typing import MetricType, QuantizeType
>>> params = HnswIndexParam(
...     metric_type=MetricType.COSINE,
...     m=16,
...     ef_construction=200,
...     quantize_type=QuantizeType.INT8,
...     use_contiguous_memory=True,
... )
>>> print(params)
{'metric_type': 'IP', 'm': 16, 'ef_construction': 200, 'quantize_type': 'INT8', 'use_contiguous_memory': True}

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
ef_construction property 
ef_construction: int

int: Candidate list size during index construction.

m property 
m: int

int: Maximum number of neighbors per node in upper layers.

use_contiguous_memory property 
use_contiguous_memory: bool

bool: Whether to allocate a single contiguous memory arena for all HNSW graph nodes. Improves cache locality and search throughput at the cost of peak memory usage. Defaults to False.

type property 
type: IndexType

IndexType: The type of the index.

metric_type property 
metric_type: MetricType

MetricType: Distance metric (e.g., IP, COSINE, L2).

quantize_type property 
quantize_type: QuantizeType

QuantizeType: Vector quantization type (e.g., FP16, INT8).

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

HnswQueryParam 

HnswQueryParam(
    ef: SupportsInt = 300,
    radius: SupportsFloat = 0.0,
    is_linear: bool = False,
    is_using_refiner: bool = False,
    extra_params: dict[str, int] = ...,
)

Bases: QueryParam

Query parameters for HNSW (Hierarchical Navigable Small World) index.

Controls the trade-off between search speed and accuracy via the ef parameter.

Attributes:

Name Type Description
type IndexType

Always IndexType.HNSW.
ef int

Size of the dynamic candidate list during search. Larger values improve recall but slow down search. Default is 300.
radius float

Search radius for range queries. Default is 0.0.
is_linear bool

Force linear search. Default is False.
is_using_refiner bool

Whether to use refiner for the query. Default is False.
prefetch_offset int

Graph prefetch offset (PO) used by the HNSW fast path. 0 disables prefetching. Default is 8. Values are clamped to 256.
prefetch_lines int

Number of 64B cache lines to prefetch per neighbour vector (PL). 0 (default) uses the auto-derived value ceil(vector_size/64). Values are clamped to 256.

Examples:

>>> params = HnswQueryParam(ef=300)
>>> print(params.ef)
300
>>> print(params.to_dict() if hasattr(params, 'to_dict') else params)
{"type":"HNSW", "ef":300}

Constructs an HnswQueryParam instance.

Parameters:

Name Type Description Default
ef
int

Search-time candidate list size. Higher values improve accuracy. Defaults to 300.

 300
radius
float

Search radius for range queries. Default is 0.0.

 0.0
is_linear
bool

Force linear search. Default is False.

 False
is_using_refiner
bool

Whether to use refiner for the query. Default is False.

 False
extra_params
dict

Additional search parameters. Supported keys: - prefetch_offset (int): Graph prefetch offset (PO). 0 disables prefetching. Default is 8. - prefetch_lines (int): Number of 64B cache lines to prefetch per neighbour vector (PL). 0 (default) means auto-derive from vector size.

 ...
Attributes
ef property 
ef: int

int: Size of the dynamic candidate list during HNSW search.

prefetch_offset property 
prefetch_offset: int

int: Graph prefetch offset used by the HNSW fast path.

prefetch_lines property 
prefetch_lines: int

int: Override of prefetch cache lines per vector (0=auto).

is_linear property 
is_linear: bool

bool: Whether to bypass the index and use brute-force linear search.

is_using_refiner property 
is_using_refiner: bool

bool: Whether to use refiner for the query.

radius property 
radius: float

IndexType: The type of index this query targets.

type property 
type: IndexType

IndexType: The type of index this query targets.

Methods:

HnswRabitqIndexParam 

HnswRabitqIndexParam(
    metric_type: MetricType = ...,
    total_bits: SupportsInt = 7,
    num_clusters: SupportsInt = 16,
    m: SupportsInt = 50,
    ef_construction: SupportsInt = 500,
    sample_count: SupportsInt = 0,
)

Bases: VectorIndexParam

Parameters for configuring an HNSW (Hierarchical Navigable Small World) index with RabitQ quantization.

HNSW is a graph-based approximate nearest neighbor search index. RabitQ is a quantization method that provides high compression with minimal accuracy loss.

Attributes:

Name Type Description
metric_type MetricType

Distance metric used for similarity computation. Default is MetricType.IP (inner product).
total_bits int

Total bits for RabitQ quantization. Default is 7.
num_clusters int

Number of clusters for RabitQ. Default is 16.
m int

Number of bi-directional links created for every new element during construction. Higher values improve accuracy but increase memory usage and construction time. Default is 50.
ef_construction int

Size of the dynamic candidate list for nearest neighbors during index construction. Larger values yield better graph quality at the cost of slower build time. Default is 500.
sample_count int

Sample count for RabitQ training. Default is 0.

Examples:

>>> from zvec.typing import MetricType
>>> params = HnswRabitqIndexParam(
...     metric_type=MetricType.COSINE,
...     total_bits=8,
...     num_clusters=256,
...     m=16,
...     ef_construction=200,
...     sample_count=10000
... )
>>> print(params)
{'metric_type': 'COSINE', 'total_bits': 8, 'num_clusters': 256, 'm': 16, 'ef_construction': 200, 'sample_count': 10000}

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
ef_construction property 
ef_construction: int

int: Candidate list size during index construction.

m property 
m: int

int: Maximum number of neighbors per node.

total_bits property 
total_bits: int

int: Total bits for RabitQ quantization.

num_clusters property 
num_clusters: int

int: Number of clusters for RabitQ.

sample_count property 
sample_count: int

int: Sample count for RabitQ training.

type property 
type: IndexType

IndexType: The type of the index.

metric_type property 
metric_type: MetricType

MetricType: Distance metric (e.g., IP, COSINE, L2).

quantize_type property 
quantize_type: QuantizeType

QuantizeType: Vector quantization type (e.g., FP16, INT8).

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

HnswRabitqQueryParam 

HnswRabitqQueryParam(
    ef: SupportsInt = 300,
    radius: SupportsFloat = 0.0,
    is_linear: bool = False,
    is_using_refiner: bool = False,
)

Bases: QueryParam

Query parameters for HNSW index with RabitQ quantization.

Controls the trade-off between search speed and accuracy via the ef parameter.

Attributes:

Name Type Description
type IndexType

Always IndexType.HNSW_RABITQ.
ef int

Size of the dynamic candidate list during search. Larger values improve recall but slow down search. Default is 300.
radius float

Search radius for range queries. Default is 0.0.
is_linear bool

Force linear search. Default is False.
is_using_refiner bool

Whether to use refiner for the query. Default is False.

Examples:

>>> params = HnswRabitqQueryParam(ef=300)
>>> print(params.ef)
300

Constructs an HnswRabitqQueryParam instance.

Parameters:

Name Type Description Default
ef
int

Search-time candidate list size. Higher values improve accuracy. Defaults to 300.

 300
radius
float

Search radius for range queries. Default is 0.0.

 0.0
is_linear
bool

Force linear search. Default is False.

 False
is_using_refiner
bool

Whether to use refiner for the query. Default is False.

 False
Attributes
ef property 
ef: int

int: Size of the dynamic candidate list during HNSW search.

is_linear property 
is_linear: bool

bool: Whether to bypass the index and use brute-force linear search.

is_using_refiner property 
is_using_refiner: bool

bool: Whether to use refiner for the query.

radius property 
radius: float

IndexType: The type of index this query targets.

type property 
type: IndexType

IndexType: The type of index this query targets.

Methods:

IVFIndexParam 

IVFIndexParam(
    metric_type: MetricType = ...,
    n_list: SupportsInt = 10,
    n_iters: SupportsInt = 10,
    use_soar: bool = False,
    quantize_type: QuantizeType = ...,
)

Bases: VectorIndexParam

Parameters for configuring an IVF (Inverted File Index) index.

IVF partitions the vector space into clusters (inverted lists). At query time, only a subset of clusters is searched, providing a trade-off between speed and accuracy.

Attributes:

Name Type Description
metric_type MetricType

Distance metric used for similarity computation. Default is MetricType.IP (inner product).
n_list int

Number of clusters (inverted lists) to partition the dataset into. Default is 10.
n_iters int

Number of iterations for k-means clustering during index training. Higher values yield more stable centroids. Default is 10.
use_soar bool

Whether to enable SOAR (Scalable Optimized Adaptive Routing) for improved IVF search performance. Default is False.
quantize_type QuantizeType

Optional quantization type for vector compression (e.g., FP16, INT8). Default is QuantizeType.UNDEFINED.

Examples:

>>> from zvec.typing import MetricType, QuantizeType
>>> params = IVFIndexParam(
...     metric_type=MetricType.COSINE,
...     n_list=100,
...     n_iters=15,
...     use_soar=True,
...     quantize_type=QuantizeType.INT8
... )
>>> print(params.n_list)
100

Constructs an IVFIndexParam instance.

Parameters:

Name Type Description Default
metric_type
MetricType

Distance metric. Defaults to MetricType.IP.

 ...
n_list
int

Number of inverted lists (clusters). Defaults to 10.

 10
n_iters
int

Number of k-means iterations during training. Defaults to 10.

 10
use_soar
bool

Enable SOAR optimization. Defaults to False.

 False
quantize_type
QuantizeType

Vector quantization type. Defaults to QuantizeType.UNDEFINED.

 ...

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
n_iters property 
n_iters: int

int: Number of k-means iterations during training.

n_list property 
n_list: int

int: Number of inverted lists.

use_soar property 
use_soar: bool

bool: Whether SOAR optimization is enabled.

type property 
type: IndexType

IndexType: The type of the index.

metric_type property 
metric_type: MetricType

MetricType: Distance metric (e.g., IP, COSINE, L2).

quantize_type property 
quantize_type: QuantizeType

QuantizeType: Vector quantization type (e.g., FP16, INT8).

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

IVFQueryParam 

IVFQueryParam(nprobe: SupportsInt = 10)

Bases: QueryParam

Query parameters for IVF (Inverted File Index) index.

Controls how many inverted lists (nprobe) to visit during search.

Attributes:

Name Type Description
type IndexType

Always IndexType.IVF.
nprobe int

Number of closest clusters (inverted lists) to search. Higher values improve recall but increase latency. Default is 10.
radius float

Search radius for range queries. Default is 0.0.
is_linear bool

Force linear search. Default is False.

Examples:

>>> params = IVFQueryParam(nprobe=20)
>>> print(params.nprobe)
20

Constructs an IVFQueryParam instance.

Parameters:

Name Type Description Default
nprobe
int

Number of inverted lists to probe during search. Higher values improve accuracy. Defaults to 10.

 10
Attributes
nprobe property 
nprobe: int

int: Number of inverted lists to search during IVF query.

is_linear property 
is_linear: bool

bool: Whether to bypass the index and use brute-force linear search.

is_using_refiner property 
is_using_refiner: bool

bool: Whether to use refiner for the query.

radius property 
radius: float

IndexType: The type of index this query targets.

type property 
type: IndexType

IndexType: The type of index this query targets.

Methods:

FtsIndexParam 

FtsIndexParam(tokenizer_name: str = 'standard', filters: list[str] = ..., extra_params: str = '')

Bases: IndexParam

Parameters for configuring a full-text search (FTS) index.

Controls the tokenizer pipeline used during indexing and querying.

Attributes:

Name Type Description
type IndexType

Always IndexType.FTS.
tokenizer_name str

Name of the tokenizer (e.g., "standard", "jieba"). Default is "standard".
filters list[str]

List of token filter names applied after tokenization. Default is ["lowercase"].
extra_params str

Additional parameters passed to the tokenizer. Default is "".

Examples:

>>> params = FtsIndexParam(tokenizer_name="jieba", filters=["lowercase"])
>>> print(params.tokenizer_name)
jieba

Constructs an FtsIndexParam instance.

Parameters:

Name Type Description Default
tokenizer_name
str

Tokenizer name. Defaults to "standard".

 'standard'
filters
list[str]

Token filter names. Defaults to ["lowercase"].

 ...
extra_params
str

Extra tokenizer parameters. Defaults to "".

 ''

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
tokenizer_name property 
tokenizer_name: str

str: Name of the tokenizer.

filters property 
filters: list[str]

list[str]: Token filter names.

extra_params property 
extra_params: str

str: Additional tokenizer parameters.

type property 
type: IndexType

IndexType: The type of the index.

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

FtsQueryParam 

FtsQueryParam(default_operator: str = '')

Bases: QueryParam

Query parameters for full-text search (FTS) index.

Controls the default boolean operator used to combine adjacent bare terms in a query string.

Attributes:

Name Type Description
type IndexType

Always IndexType.FTS.
default_operator str

Default boolean operator for adjacent bare terms. Supported values (case-insensitive): "OR" (default), "AND".

Examples:

>>> params = FtsQueryParam(default_operator="AND")
>>> print(params.default_operator)
AND

Constructs an FtsQueryParam instance.

Parameters:

Name Type Description Default
default_operator
str

Default boolean operator for adjacent bare terms. Supported: "OR", "AND". Defaults to "" (uses engine default).

 ''
Attributes
default_operator property 
default_operator: str

str: Default boolean operator for bare terms.

is_linear property 
is_linear: bool

bool: Whether to bypass the index and use brute-force linear search.

is_using_refiner property 
is_using_refiner: bool

bool: Whether to use refiner for the query.

radius property 
radius: float

IndexType: The type of index this query targets.

type property 
type: IndexType

IndexType: The type of index this query targets.

Methods:

IndexOption 

IndexOption(concurrency: SupportsInt = 0)

Options for creating an index.

Attributes:

Name Type Description
concurrency int

Number of threads to use during index creation. If 0, the system will choose an optimal value automatically. Default is 0.

Examples:

>>> opt = IndexOption(concurrency=4)
>>> print(opt.concurrency)
4

Constructs an IndexOption instance.

Parameters:

Name Type Description Default
concurrency
int

Number of concurrent threads. 0 means auto-detect. Defaults to 0.

 0
Attributes
concurrency property 
concurrency: int

int: Number of threads used for index creation (0 = auto).

Methods:

IndexParam

Base class for all index parameter configurations.

This abstract base class defines the common interface for index types. It should not be instantiated directly; use derived classes instead.

Attributes:

Name Type Description
type IndexType

The type of the index (e.g., HNSW, FLAT, INVERT).

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
type property 
type: IndexType

IndexType: The type of the index.

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

InvertIndexParam 

InvertIndexParam(enable_range_optimization: bool = False, enable_extended_wildcard: bool = False)

Bases: IndexParam

Parameters for configuring an invert index.

This class controls whether range query optimization is enabled for invert index structures.

Attributes:

Name Type Description
type IndexType

Always IndexType.INVERTED.
enable_range_optimization bool

Whether range optimization is enabled.
enable_extended_wildcard bool

Whether extended wildcard (suffix and infix) search is enabled.

Examples:

>>> params = InvertIndexParam(enable_range_optimization=True, enable_extended_wildcard=False)
>>> print(params.enable_range_optimization)
True
>>> print(params.enable_extended_wildcard)
False
>>> config = params.to_dict()
>>> print(config)
{'enable_range_optimization': True, 'enable_extended_wildcard': False}

Constructs an InvertIndexParam instance.

Parameters:

Name Type Description Default
enable_range_optimization
bool

If True, enables range query optimization for the invert index. Defaults to False.

 False
enable_extended_wildcard
bool

If True, enables extended wildcard search including suffix and infix patterns. Defaults to False.

 False

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
enable_extended_wildcard property 
enable_extended_wildcard: bool

bool: Whether extended wildcard (suffix and infix) search is enabled. Note: Prefix search is always enabled regardless of this setting.

enable_range_optimization property 
enable_range_optimization: bool

bool: Whether range optimization is enabled for this inverted index.

type property 
type: IndexType

IndexType: The type of the index.

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

OptimizeOption 

OptimizeOption(concurrency: SupportsInt = 0)

Options for optimizing a collection (e.g., merging segments).

Attributes:

Name Type Description
concurrency int

Number of threads to use during optimization. If 0, the system will choose an optimal value automatically. Default is 0.

Examples:

>>> opt = OptimizeOption(concurrency=2)
>>> print(opt.concurrency)
2

Constructs an OptimizeOption instance.

Parameters:

Name Type Description Default
concurrency
int

Number of concurrent threads. 0 means auto-detect. Defaults to 0.

 0
Attributes
concurrency property 
concurrency: int

int: Number of threads used for optimization (0 = auto).

Methods:

QueryParam

Base class for all query parameter configurations.

This abstract base class defines common query settings such as search radius and whether to force linear (brute-force) search. It should not be instantiated directly; use derived classes like HnswQueryParam or IVFQueryParam.

Attributes:

Name Type Description
type IndexType

The index type this query is configured for.
radius float

Search radius for range queries. Used in combination with top-k to filter results. Default is 0.0 (disabled).
is_linear bool

If True, forces brute-force linear search instead of using the index. Useful for debugging or small datasets. Default is False.
is_using_refiner bool

Whether to use refiner for the query. Default is False.
Attributes
is_linear property 
is_linear: bool

bool: Whether to bypass the index and use brute-force linear search.

is_using_refiner property 
is_using_refiner: bool

bool: Whether to use refiner for the query.

radius property 
radius: float

IndexType: The type of index this query targets.

type property 
type: IndexType

IndexType: The type of index this query targets.

SegmentOption 

SegmentOption()

Options for segment-level operations.

Currently, this class mirrors CollectionOption and is used internally. It supports read-only mode, memory mapping, and buffer configuration.

Note

This class is primarily for internal use. Most users should use CollectionOption instead.

Examples:

>>> opt = SegmentOption()
>>> print(opt.enable_mmap)
True

Constructs a SegmentOption with default settings.

Attributes:

Name Type Description
enable_mmap bool

bool: Whether memory-mapped I/O is enabled.
max_buffer_size int

int: Maximum buffer size in bytes (internal use).
read_only bool

bool: Whether the segment is read-only.
Attributes
enable_mmap property 
enable_mmap: bool

bool: Whether memory-mapped I/O is enabled.

max_buffer_size property 
max_buffer_size: int

int: Maximum buffer size in bytes (internal use).

read_only property 
read_only: bool

bool: Whether the segment is read-only.

Methods:

VectorIndexParam

Bases: IndexParam

Base class for vector index parameter configurations.

Encapsulates common settings for all vector index types.

Attributes:

Name Type Description
type IndexType

The specific vector index type (e.g., HNSW, FLAT).
metric_type MetricType

Distance metric used for similarity search.
quantize_type QuantizeType

Optional vector quantization type.

Methods:

Name Description
to_dict

Convert to dictionary with all fields
Attributes
metric_type property 
metric_type: MetricType

MetricType: Distance metric (e.g., IP, COSINE, L2).

quantize_type property 
quantize_type: QuantizeType

QuantizeType: Vector quantization type (e.g., FP16, INT8).

type property 
type: IndexType

IndexType: The type of the index.

Methods:
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

zvec.model.param.query.Query dataclass 

Query(
    field_name: str,
    id: Optional[str] = None,
    vector: VectorType = None,
    param: Optional[
        Union[HnswQueryParam, HnswRabitqQueryParam, IVFQueryParam, FtsQueryParam]
    ] = None,
    fts: Optional[Fts] = None,
)

Represents a search query for a specific field in a collection.

A Query can be constructed for either vector search or full-text search, but not both simultaneously.

For vector search, provide id or vector (and optionally param). For FTS, provide fts.

Attributes:

Name Type Description
field_name str

Name of the field to query.
id Optional[str]

Document ID to fetch vector from. Default is None.
vector VectorType

Explicit query vector. Default is None.
param Optional[Union[HnswQueryParam, HnswRabitqQueryParam, IVFQueryParam, FtsQueryParam]]

Index-specific query parameters. Default is None.
fts Optional[Fts]

Full-text search parameters. Default is None.

Examples:

>>> import zvec
>>> # Query by ID
>>> q1 = zvec.Query(field_name="embedding", id="doc123")
>>> # Query by vector
>>> q2 = zvec.Query(
...     field_name="embedding",
...     vector=[0.1, 0.2, 0.3],
...     param=HnswQueryParam(ef=300)
... )
>>> # FTS query
>>> q3 = zvec.Query(
...     field_name="content",
...     fts=Fts(match_string="machine learning")
... )
>>> # FTS query with custom operator
>>> q4 = zvec.Query(
...     field_name="content",
...     fts=Fts(match_string="machine learning"),
...     param=FtsQueryParam(default_operator="AND")
... )

Methods:

Name Description
has_id

Check if the query is based on a document ID.
has_vector

Check if the query contains an explicit vector.
has_fts

Check if the query contains an FTS (full-text search) condition.

Methods:

has_id 

has_id() -> bool

Check if the query is based on a document ID.

Returns:

Name Type Description
bool bool

True if id is set, False otherwise.

has_vector 

has_vector() -> bool

Check if the query contains an explicit vector.

Returns:

Name Type Description
bool bool

True if vector is non-empty, False otherwise.

has_fts 

has_fts() -> bool

Check if the query contains an FTS (full-text search) condition.

Returns:

Name Type Description
bool bool

True if fts is set with a query_string or match_string.