Document¶

This is an automatically generated API reference of the VERA storage and search engine (vera.document).

document ¶

Classes:

VeraDocument –

An embedded storage and search engine backed by one portable .vera file.
EmbeddingFunction –

Protocol for embedding functions used when writing records.
DuplicateRecordError –

Raised when add() receives an ID that already exists.
RecordNotFoundError –

Raised when a requested chunk or attachment does not exist.
ReadOnlyError –

Raised when a write is attempted on a read-only database.

VeraDocument ¶

VeraDocument(path: Path, conn: Connection, *, mode: OpenMode, embedding_function: EmbeddingFunction | None)

An embedded storage and search engine backed by one portable .vera file.

Use :meth:create to initialize a new archive and :meth:open to access an existing one. Archives support CRUD on :class:~vera.models.ChunkRecord objects, optional binary attachments, and semantic, keyword, or hybrid search.

Example

from vera import ChunkRecord, VeraDocument

with VeraDocument.create("example.vera") as document:
    document.add([ChunkRecord(id="1", text="Hello world.")])

with VeraDocument.open("example.vera") as document:
    results = document.search(text="hello", top_k=5)

Methods:

create –

Create a new empty .vera archive at path.
open –

Open an existing .vera archive.
set_metadata –

Replace caller-controlled archive metadata.
add –

Insert new chunk records.
upsert –

Insert or replace chunk records atomically.
get –

Fetch chunk records by ID and/or metadata filter.
delete –

Delete chunk records by ID and/or metadata filter.
search –

Search chunk records.
put_attachments –

Store opaque binary attachments.
get_attachment –

Return a stored attachment by ID.
attachments –

Return stored attachments, optionally filtered by metadata equality.
delete_attachment –

Delete a stored attachment.
inspect –

Return archive metadata and record counts.
validate –

Check archive integrity.
transaction –

Run a batch of writes in a single SQLite transaction.
close –

Close the database connection.
__enter__ –
__exit__ –

Attributes:

path –
mode (OpenMode) –
metadata (dict[str, Any]) –

Caller-controlled archive metadata as a mutable dict.

path `instance-attribute` ¶

path = path

mode `property` ¶

mode: OpenMode

metadata `property` ¶

metadata: dict[str, Any]

Caller-controlled archive metadata as a mutable dict.

create `classmethod` ¶

create(path: str | PathLike[str], *, embedding_function: EmbeddingFunction | None = None, model: str = 'hashing', metadata: JsonObject | None = None, overwrite: bool = False) -> 'VeraDocument'

Create a new empty .vera archive at path.

Parameters:

path (str | PathLike[str]) –

Destination file path.
embedding_function (EmbeddingFunction | None, default: None ) –

Custom embedder. When omitted, model selects the default embedder.
model (str, default: 'hashing' ) –

Default embedding model name (for example "hashing").
metadata (JsonObject | None, default: None ) –

Caller-controlled JSON metadata stored in the archive.
overwrite (bool, default: False ) –

When False (default), raise :class:FileExistsError if path already exists.

Returns:

'VeraDocument' –

A write-mode database handle.

Raises:

FileExistsError –

When the target exists and overwrite is false.

open `classmethod` ¶

open(path: str | PathLike[str], *, mode: OpenMode = 'read', embedding_function: EmbeddingFunction | None = None) -> 'VeraDocument'

Open an existing .vera archive.

Parameters:

path (str | PathLike[str]) –

Path to an existing archive.
mode (OpenMode, default: 'read' ) –

"read" (default) opens SQLite read-only; "write" allows mutations.
embedding_function (EmbeddingFunction | None, default: None ) –

Embedder used for write-mode searches and record writes. When omitted in write mode, the model recorded in the archive is used.

Returns:

'VeraDocument' –

A database handle.

Raises:

FileNotFoundError –

When path does not exist.
ValueError –

When the archive format version is unsupported or the embedder dimension does not match the archive.

set_metadata ¶

set_metadata(metadata: JsonObject) -> None

Replace caller-controlled archive metadata.

Parameters:

metadata (JsonObject) –

JSON-compatible mapping stored in the archive header.

Raises:

ReadOnlyError –

When the database is opened read-only.

add ¶

add(records: Iterable[ChunkRecord]) -> None

Insert new chunk records.

Parameters:

records (Iterable[ChunkRecord]) –

Records to insert. IDs must not already exist.

Raises:

DuplicateRecordError –

When a record ID already exists.
ReadOnlyError –

When the database is opened read-only.
RecordNotFoundError –

When an attachment reference is missing.

upsert ¶

upsert(records: Iterable[ChunkRecord]) -> None

Insert or replace chunk records atomically.

Parameters:

records (Iterable[ChunkRecord]) –

Records to insert or update by ID.

Raises:

ReadOnlyError –

When the database is opened read-only.
RecordNotFoundError –

When an attachment reference is missing.

get ¶

get(ids: Iterable[str] | None = None, *, where: Mapping[str, Any] | None = None, limit: int | None = None) -> list[ChunkRecord]

Fetch chunk records by ID and/or metadata filter.

Parameters:

ids (Iterable[str] | None, default: None ) –

Specific chunk IDs to retrieve. When omitted, all matching records are returned subject to where and limit.
where (Mapping[str, Any] | None, default: None ) –

Exact equality filter on top-level metadata keys.
limit (int | None, default: None ) –

Maximum number of records to return.

Returns:

Matching ( list[ChunkRecord] ) –

class:~vera.models.ChunkRecord objects in storage order.

delete ¶

delete(ids: Iterable[str] | None = None, *, where: Mapping[str, Any] | None = None) -> int

Delete chunk records by ID and/or metadata filter.

Parameters:

ids (Iterable[str] | None, default: None ) –

Specific chunk IDs to delete.
where (Mapping[str, Any] | None, default: None ) –

Exact equality filter on top-level metadata keys.

Returns:

int –

The number of records deleted.

search ¶

search(text: str | None = None, *, vector: Sequence[float] | None = None, mode: SearchMode = 'hybrid', where: Mapping[str, Any] | None = None, top_k: int = 10, context_chunks: int = 0) -> list[QueryResult]

Search chunk records.

Parameters:

text (str | None, default: None ) –

Query string for semantic or keyword search. Required unless vector is supplied for semantic mode.
vector (Sequence[float] | None, default: None ) –

Pre-computed query vector for semantic search.
mode (SearchMode, default: 'hybrid' ) –

"hybrid" (default), "semantic", or "keyword".
where (Mapping[str, Any] | None, default: None ) –

Exact equality filter on top-level metadata keys.
top_k (int, default: 10 ) –

Maximum number of results to return.
context_chunks (int, default: 0 ) –

Number of adjacent stored chunks to include.

Returns:

Ranked ( list[QueryResult] ) –

class:~vera.models.QueryResult objects.

put_attachments ¶

put_attachments(attachments: Iterable[AttachmentRecord], *, upsert: bool = False) -> None

Store opaque binary attachments.

Parameters:

attachments (Iterable[AttachmentRecord]) –

Attachment payloads to insert.
upsert (bool, default: False ) –

When True, replace existing attachments with the same ID.

Raises:

ReadOnlyError –

When the database is opened read-only.
DuplicateRecordError –

When an ID exists and upsert is false.

get_attachment ¶

get_attachment(attachment_id: str) -> AttachmentRecord

Return a stored attachment by ID.

Parameters:

attachment_id (str) –

Attachment identifier.

Returns:

AttachmentRecord –

The matching :class:~vera.models.AttachmentRecord.

Raises:

RecordNotFoundError –

When no attachment exists with that ID.

attachments ¶

attachments(*, where: Mapping[str, Any] | None = None) -> list[AttachmentRecord]

Return stored attachments, optionally filtered by metadata equality.

Parameters:

where (Mapping[str, Any] | None, default: None ) –

Exact equality filter on top-level attachment metadata keys.

Returns:

list[AttachmentRecord] –

Matching attachments in storage order.

delete_attachment ¶

delete_attachment(attachment_id: str) -> None

Delete a stored attachment.

Parameters:

attachment_id (str) –

Attachment identifier.

Raises:

RecordNotFoundError –

When no attachment exists with that ID.
ValueError –

When the attachment is still referenced by a chunk.
ReadOnlyError –

When the database is opened read-only.

inspect ¶

inspect() -> dict[str, Any]

Return archive metadata and record counts.

Returns:

dict[str, Any] –

A dict with path, format_version, embedding_model,
dict[str, Any] –

chunks, attachments, and related fields.

validate ¶

validate() -> dict[str, Any]

Check archive integrity.

Returns:

dict[str, Any] –

A report dict with an ok boolean and an issues list.

transaction ¶

transaction() -> Iterator['VeraDocument']

Run a batch of writes in a single SQLite transaction.

Yields:

'VeraDocument' –

This database handle for use inside the with block.

Raises:

RuntimeError –

When nested transactions are attempted.
ReadOnlyError –

When the database is opened read-only.

close ¶

close() -> None

Close the database connection.

enter ¶

__enter__() -> 'VeraDocument'

exit ¶

__exit__(*exc: object) -> None

EmbeddingFunction ¶

Bases: Protocol

Protocol for embedding functions used when writing records.

Attributes:

model_name (str) –

Identifier stored in the archive metadata.
dimension (int) –

Vector length expected by the database.

Methods:

embed –

Embed a batch of texts.

model_name `instance-attribute` ¶

model_name: str

dimension `instance-attribute` ¶

dimension: int

embed ¶

embed(texts: list[str]) -> ndarray

Embed a batch of texts.

Parameters:

texts (list[str]) –

Strings to embed.

Returns:

ndarray –

A 2-D array of shape (len(texts), dimension).

DuplicateRecordError ¶

Bases: ValueError

Raised when add() receives an ID that already exists.

RecordNotFoundError ¶

Bases: KeyError

Raised when a requested chunk or attachment does not exist.

ReadOnlyError ¶

Bases: PermissionError

Raised when a write is attempted on a read-only database.

See QueryResult for the shape of search hits.

Document¶

document ¶

VeraDocument ¶

path instance-attribute ¶

mode property ¶

metadata property ¶

create classmethod ¶

open classmethod ¶

set_metadata ¶

add ¶

upsert ¶

get ¶

delete ¶

search ¶

put_attachments ¶

get_attachment ¶

attachments ¶

delete_attachment ¶

inspect ¶

validate ¶

transaction ¶

close ¶

__enter__ ¶

__exit__ ¶

EmbeddingFunction ¶

model_name instance-attribute ¶

dimension instance-attribute ¶

embed ¶

DuplicateRecordError ¶

RecordNotFoundError ¶

ReadOnlyError ¶

path `instance-attribute` ¶

mode `property` ¶

metadata `property` ¶

create `classmethod` ¶

open `classmethod` ¶

enter ¶

exit ¶

model_name `instance-attribute` ¶

dimension `instance-attribute` ¶