Skip to content

Collection Schema

zvec.model.schema

This module contains the schema of Zvec

Modules:

Name Description
collection_schema
field_schema

Classes:

Name Description
CollectionSchema

Defines the structure of a collection in Zvec.
FieldSchema

Represents a scalar (non-vector) field in a collection schema.
VectorSchema

Represents a vector field in a collection schema.

Classes

CollectionSchema 

CollectionSchema(
    name: str,
    fields: Optional[Union[FieldSchema, list[FieldSchema]]] = None,
    vectors: Optional[Union[VectorSchema, list[VectorSchema]]] = None,
)

Defines the structure of a collection in Zvec.

A collection schema specifies the name of the collection and its fields, including both scalar fields (e.g., int, string) and vector fields. Field names must be unique across both scalar and vector fields.

Parameters:

Name Type Description Default
name
str

Name of the collection.

 required
fields
Optional[Union[FieldSchema, list[FieldSchema]]]

One or more scalar field definitions. Defaults to None.

 None
vectors
Optional[Union[VectorSchema, list[VectorSchema]]]

One or more vector field definitions. Defaults to None.

 None

Raises:

Type Description
TypeError

If fields or vectors are of unsupported types.
ValueError

If any field or vector name is duplicated.

Examples:

>>> from zvec import FieldSchema, VectorSchema, DataType, IndexType
>>> id_field = FieldSchema("id", DataType.INT64, is_primary=True)
>>> emb_field = VectorSchema("embedding", dim=128, data_type=DataType.VECTOR_FP32)
>>> schema = CollectionSchema(
...     name="my_collection",
...     fields=id_field,
...     vectors=emb_field
... )
>>> print(schema.name)
my_collection

Methods:

Name Description
field

Retrieve a scalar field by name.
vector

Retrieve a vector field by name.

Attributes:

Name Type Description
name str

str: The name of the collection.
fields list[FieldSchema]

list[FieldSchema]: All scalar (non-vector) fields in the schema.
vectors list[VectorSchema]

list[VectorSchema]: All vector fields in the schema.
Attributes
name property 
name: str

str: The name of the collection.

fields property 
fields: list[FieldSchema]

list[FieldSchema]: All scalar (non-vector) fields in the schema.

vectors property 
vectors: list[VectorSchema]

list[VectorSchema]: All vector fields in the schema.

Functions
field 
field(name: str) -> Optional[FieldSchema]

Retrieve a scalar field by name.

Parameters:

Name Type Description Default
name str

Name of the field.

 required

Returns:

Type Description
Optional[FieldSchema]

Optional[FieldSchema]: The field if found, otherwise None.
vector 
vector(name: str) -> Optional[VectorSchema]

Retrieve a vector field by name.

Parameters:

Name Type Description Default
name str

Name of the vector field.

 required

Returns:

Type Description
Optional[VectorSchema]

Optional[VectorSchema]: The vector field if found, otherwise None.

FieldSchema 

FieldSchema(
    name: str,
    data_type: DataType,
    nullable: bool = False,
    index_param: Optional[InvertIndexParam] = None,
)

Represents a scalar (non-vector) field in a collection schema.

A FieldSchema defines the name, data type, nullability, and optional inverted index configuration for a regular field (e.g., ID, timestamp, category).

Parameters:

Name Type Description Default
name
str

Name of the field. Must be unique within the collection.

 required
data_type
DataType

Data type of the field (e.g., INT64, STRING).

 required
nullable
bool

Whether the field can contain null values. Defaults to False.

 False
index_param
Optional[InvertIndexParam]

Inverted index parameters for this field. Only applicable to fields that support indexing (e.g., scalar fields used in filtering). Defaults to None.

 None

Examples:

>>> from zvec.typing import DataType
>>> from zvec.model.param import InvertIndexParam
>>> id_field = FieldSchema(
...     name="id",
...     data_type=DataType.INT64,
...     nullable=False,
...     index_param=InvertIndexParam(enable_range_optimization=True)
... )

Attributes:

Name Type Description
name str

str: The name of the field.
data_type DataType

DataType: The data type of the field (e.g., INT64, STRING).
nullable bool

bool: Whether the field allows null values.
index_param Optional[InvertIndexParam]

Optional[InvertIndexParam]: Inverted index configuration, if any.
Attributes
name property 
name: str

str: The name of the field.

data_type property 
data_type: DataType

DataType: The data type of the field (e.g., INT64, STRING).

nullable property 
nullable: bool

bool: Whether the field allows null values.

index_param property 
index_param: Optional[InvertIndexParam]

Optional[InvertIndexParam]: Inverted index configuration, if any.

VectorSchema 

VectorSchema(
    name: str,
    data_type: DataType,
    dimension: Optional[int] = 0,
    index_param: Optional[Union[HnswIndexParam, FlatIndexParam, IVFIndexParam]] = None,
)

Represents a vector field in a collection schema.

A VectorSchema defines the name, data type, dimensionality, and index configuration for a vector field used in similarity search.

Parameters:

Name Type Description Default
name
str

Name of the vector field. Must be unique within the collection.

 required
data_type
DataType

Vector data type (e.g., VECTOR_FP32, VECTOR_INT8).

 required
dimension
int

Dimensionality of the vector. Must be > 0 for dense vectors; may be None for sparse vectors.

 0
index_param
Union[HnswIndexParam, IVFIndexParam, FlatIndexParam]

Index configuration for this vector field. Defaults to HnswIndexParam().

 None

Examples:

>>> from zvec.typing import DataType
>>> from zvec.model.param import HnswIndexParam
>>> emb_field = VectorSchema(
...     name="embedding",
...     data_type=DataType.VECTOR_FP32,
...     dimension=128,
...     index_param=HnswIndexParam(ef_construction=200, m=16)
... )

Attributes:

Name Type Description
name str

str: The name of the vector field.
data_type DataType

DataType: The vector data type (e.g., VECTOR_FP32).
dimension int

int: The dimensionality of the vector.
index_param Union[HnswIndexParam, IVFIndexParam, FlatIndexParam]

Union[HnswIndexParam, IVFIndexParam, FlatIndexParam]: Index configuration for the vector.
Attributes
name property 
name: str

str: The name of the vector field.

data_type property 
data_type: DataType

DataType: The vector data type (e.g., VECTOR_FP32).

dimension property 
dimension: int

int: The dimensionality of the vector.

index_param property 
index_param: Union[HnswIndexParam, IVFIndexParam, FlatIndexParam]

Union[HnswIndexParam, IVFIndexParam, FlatIndexParam]: Index configuration for the vector.