Doc Class

zvec.model.doc.Doc

Doc(
    id: str,
    score: Optional[float] = None,
    vectors: Optional[dict[str, VectorType]] = None,
    fields: Optional[dict[str, Any]] = None,
)

Represents a retrieved document with optional metadata, fields, and vectors.

This immutable data class encapsulates the result of a search or retrieval operation. It includes the document ID, relevance score (if applicable), scalar fields, and vector embeddings.

During initialization, any numpy.ndarray in vectors is automatically converted to a plain Python list for JSON serialization and immutability.

Attributes:

Name	Type	Description
id	str	Unique identifier of the document.
score	Optional[float]	Relevance score from search. Defaults to None.
vectors	Optional[dict[str, VectorType]]	Named vector embeddings associated with the document. Values are converted to lists if originally np.ndarray. Defaults to None.
fields	Optional[dict[str, Any]]	Scalar metadata fields (e.g., title, timestamp). Defaults to None.

Examples:

>>> import numpy as np
>>> import zvec
>>> doc = zvec.Doc(
...     id="doc1",
...     score=0.95,
...     vectors={"emb": np.array([0.1, 0.2, 0.3])},
...     fields={"title": "Hello World"}
... )
>>> print(doc.vector("emb"))
[0.1, 0.2, 0.3]
>>> print(doc.has_field("title"))
True

Methods:

Name	Description
has_field	Check if the document contains a scalar field with the given name.
has_vector	Check if the document contains a vector with the given name.
vector	Get a vector by name.
field	Get a scalar field by name.
vector_names	Get the list of all vector names in this document.
field_names	Get the list of all scalar field names in this document.

Functions

has_field

has_field(name: str) -> bool

Check if the document contains a scalar field with the given name.

Parameters:

Name	Type	Description	Default
name	str	Name of the field to check.	required

Returns:

Name	Type	Description
bool	bool	True if the field exists, False otherwise.

has_vector

has_vector(name: str) -> bool

Check if the document contains a vector with the given name.

Parameters:

Name	Type	Description	Default
name	str	Name of the vector to check.	required

Returns:

Name	Type	Description
bool	bool	True if the vector exists, False otherwise.

vector

vector(name: str)

Get a vector by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the vector.	required

Returns:

Name	Type	Description
Any		The vector (as a list) if it exists, otherwise None.

field

field(name: str)

Get a scalar field by name.

Parameters:

Name	Type	Description	Default
name	str	Name of the field.	required

Returns:

Name	Type	Description
Any		The field value if it exists, otherwise None.

vector_names

vector_names() -> list[str]

Get the list of all vector names in this document.

Returns:

Type	Description
list[str]	list[str]: A list of vector field names. Empty if no vectors.

field_names

field_names() -> list[str]

Get the list of all scalar field names in this document.

Returns:

Type	Description
list[str]	list[str]: A list of field names. Empty if no fields.