Skip to content

API reference

Import from the top-level package:

from numpy_vector_store import VectorHit, VectorStore, __version__

These signatures and docstrings are rendered from the package source. Only the supported public members are included. TMetadata is your application payload type; ArrayLike refers to NumPy-compatible array input.

The source aliases _PathInput and _RealScalar appear in signatures. _PathInput means str | os.PathLike[str]. _RealScalar means a Python or NumPy integer or floating scalar; booleans are rejected. They describe accepted inputs and are not additional supported package exports.

Read search and filtering, persistence, and state and threading for the behavior behind these signatures.

VectorStore 

VectorStore(dimensions: SupportsIndex, *, normalize: bool | bool_ = True)

Bases: Generic[TMetadata]

A small in-memory vector store using NumPy exact vector search.

Metadata is an opaque row payload returned with vector hits. The store does not implement a metadata query language; pass row indexes to within_rows for prefiltered vector search.

Initialize the vector store.

Parameters:

Name Type Description Default
dimensions SupportsIndex

The number of dimensions for vectors to be stored.

 required
normalize bool | bool_

Whether to store vectors normalized to unit length.

 True

dimensions property 

dimensions: int

Return the configured vector width.

normalize property 

normalize: bool

Return whether vectors use normalized storage semantics.

file_path property 

file_path: Path | None

Return the currently bound archive path, if any.

vectors property 

vectors: NDArray[float32]

Return a zero-copy, non-writeable view of the current vectors.

metadata property 

metadata: NDArray[Any]

Return a zero-copy, non-writeable view of the current metadata rows.

open classmethod 

open(path: _PathInput) -> VectorStore[TMetadata]

Open a store from a versioned, self-describing archive.

add 

add(vectors: ArrayLike, metadata: Sequence[TMetadata] | NDArray[Any]) -> None

Add vectors and row metadata payloads.

When normalize=True, vectors are normalized at insert time. Metadata items are stored as opaque payloads and returned with vector hits.

reload 

reload() -> None

Refresh this store from its bound archive path.

save 

save(path: _PathInput | None = None) -> None

Save the store and bind an explicitly supplied destination path.

cosine_search(query: ArrayLike, *, top_k: SupportsIndex = 10, min_value: _RealScalar | None = None, within_rows: Sequence[SupportsIndex] | NDArray[integer[Any]] | None = None) -> list[VectorHit[TMetadata]]

Return the most similar rows using cosine similarity.

Parameters:

Name Type Description Default
query ArrayLike

1D query vector.

 required
top_k SupportsIndex

Maximum number of hits to return.

 10
min_value _RealScalar | None

Optional minimum cosine similarity value.

 None
within_rows Sequence[SupportsIndex] | NDArray[integer[Any]] | None

Optional row indexes to restrict search to.

 None 
dot_search(query: ArrayLike, *, top_k: SupportsIndex = 10, min_value: _RealScalar | None = None, within_rows: Sequence[SupportsIndex] | NDArray[integer[Any]] | None = None) -> list[VectorHit[TMetadata]]

Return rows ranked by dot product.

With normalize=True, this is the dot product of unit vectors. With normalize=False, this is the true dot product over original vectors.

euclidean_search(query: ArrayLike, *, top_k: SupportsIndex = 10, max_value: _RealScalar | None = None, within_rows: Sequence[SupportsIndex] | NDArray[integer[Any]] | None = None) -> list[VectorHit[TMetadata]]

Return rows ranked by Euclidean distance.

With normalize=True, this is distance between normalized directions. With normalize=False, this is true Euclidean distance over original vectors.

get 

get(index: SupportsIndex) -> tuple[npt.NDArray[np.float32], TMetadata] | None

Get a stored vector and metadata payload by row index.

clear 

clear() -> None

Clear all vectors and metadata from the store.

__len__ 

__len__() -> int

Return the number of stored vector rows.

VectorHit dataclass

Bases: Generic[TMetadata]

A typed vector-search result.

index instance-attribute 

index: int

value instance-attribute 

value: float

metadata instance-attribute 

metadata: TMetadata

A frozen result record. Fields cannot be reassigned, but a mutable metadata payload is still shared with the application. Equality and hashability follow the field values; a hit containing a dictionary is unhashable. Use hit.index or an application identifier when you need a stable key.

Package version

__version__ is the installed version string. This documentation edition describes 0.7.0.