Skip to content

Parameters

zvec.model.param

This module contains the params of Zvec

Modules:

Name Description
vector_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.
IVFIndexParam

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

Query parameters for IVF (Inverted File Index) 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).

Functions

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).

Functions

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
Functions

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).

Functions
to_dict 
to_dict() -> dict

Convert to dictionary with all fields

HnswIndexParam 

HnswIndexParam(
    metric_type: MetricType = ...,
    m: SupportsInt = 100,
    ef_construction: SupportsInt = 500,
    quantize_type: QuantizeType = ...,
)

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 100.
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.

Examples:

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

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.

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).

Functions
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,
)

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.

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 100.

 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.

Functions

IVFIndexParam 

IVFIndexParam(
    metric_type: MetricType = ...,
    n_list: SupportsInt = 0,
    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. If set to 0, the system will auto-select a reasonable value based on data size. Default is 0 (auto).
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). Set to 0 for auto. Defaults to 0.

 0
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 (0 = auto).

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).

Functions
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.

Functions

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).

Functions

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.

Functions
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.

Functions
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).

Functions

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.

Functions

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.

Functions
to_dict 
to_dict() -> dict

Convert to dictionary with all fields