Collection lifecycle management for zvec.
A collection is the fundamental storage unit — it holds typed documents
organized by a Zvex.Collection.Schema. Once created and opened, you can
insert, update, upsert, delete, and fetch documents, as well as manage
indexes and columns at runtime.
Every function that can fail returns {:ok, result} | {:error, Zvex.Error.t()}
and has a bang (!) variant that unwraps or raises.
Example
alias Zvex.Collection
alias Zvex.Collection.Schema
schema =
Schema.new("my_collection")
|> Schema.add_field("id", :string, primary_key: true)
|> Schema.add_field("embedding", :vector_fp32,
dimension: 768,
index: [type: :hnsw, metric: :cosine])
{:ok, collection} = Collection.create("/tmp/my_collection", schema)
{:ok, stats} = Collection.stats(collection)
:ok = Collection.close(collection)Summary
Functions
Adds a new column to the collection schema at runtime.
Like add_column/4 but raises on error.
Alters an existing column.
Like alter_column/3 but raises on error.
Closes the collection, releasing its native resources.
Like close/1 but raises on error.
Creates a new collection on disk and opens it.
Like create/3 but raises on error.
Creates an index on field_name.
Like create_index/3 but raises on error.
Deletes documents by their primary keys.
Like delete/2 but raises on error.
Deletes all documents matching a filter expression.
Like delete_by_filter/2 but raises on error.
Deletes documents and returns per-document result details. See insert_with_results/2.
Like delete_with_results/2 but raises on error.
Closes the collection (if open) and deletes its data directory from disk.
Like drop/1 but raises on error.
Removes a column from the collection schema. Existing data for this column is discarded.
Like drop_column/2 but raises on error.
Removes the index from field_name.
Like drop_index/2 but raises on error.
Fetches documents by their primary keys.
Like fetch/2 but raises on error.
Returns the names of all fields. Shorthand for field_names(collection, :all).
Returns the names of fields matching category.
Like field_names/1 but raises on error.
Like field_names/2 but raises on error.
Flushes buffered writes to persistent storage.
Like flush/1 but raises on error.
Returns true if the collection schema contains a field named field_name.
Returns true if the field field_name has an index.
Inserts one or more documents into the collection.
Like insert/2 but raises on error.
Inserts documents and returns per-document result details.
Like insert_with_results/2 but raises on error.
Opens an existing collection from path.
Like open/2 but raises on error.
Triggers index optimization on the collection.
Like optimize/1 but raises on error.
Returns the collection-level options as a map.
Like options/1 but raises on error.
Returns the Zvex.Collection.Schema of the open collection.
Like schema/1 but raises on error.
Returns a Zvex.Collection.Stats struct with the document count and index information.
Like stats/1 but raises on error.
Updates existing documents in the collection.
Like update/2 but raises on error.
Updates documents and returns per-document result details. See insert_with_results/2.
Like update_with_results/2 but raises on error.
Inserts or updates documents, depending on whether their primary key exists.
Like upsert/2 but raises on error.
Upserts documents and returns per-document result details. See insert_with_results/2.
Like upsert_with_results/2 but raises on error.
Types
An open collection handle.
:ref— opaque NIF resource reference to the underlying zvec collection.:path— filesystem path where the collection data is stored.
Once close/1 is called, the underlying resource is closed; further
operations through the public API return {:error, %Zvex.Error.Invalid.FailedPrecondition{}}.
Functions
@spec add_column(t(), String.t(), atom(), keyword()) :: :ok | {:error, Zvex.Error.t()}
Adds a new column to the collection schema at runtime.
Options
:nullable— whether the column allows null values (defaultfalse):dimension— vector dimension, required for vector types (default0):index— keyword list of index parameters (e.g.[type: :invert]):default— default expression string applied to existing documents
Like add_column/4 but raises on error.
@spec alter_column(t(), String.t(), keyword()) :: :ok | {:error, Zvex.Error.t()}
Alters an existing column.
Options
:new_name— rename the column:schema— keyword list with the new field definition (:name,:data_type,:nullable,:dimension)
Like alter_column/3 but raises on error.
@spec close(t()) :: :ok | {:error, Zvex.Error.t()}
Closes the collection, releasing its native resources.
After closing, all operations on this handle will return an error.
@spec close!(t()) :: :ok
Like close/1 but raises on error.
@spec create(String.t(), Zvex.Collection.Schema.t(), keyword()) :: {:ok, t()} | {:error, Zvex.Error.t()}
Creates a new collection on disk and opens it.
The schema is validated before being sent to the native layer. opts are
forwarded as collection-level options (e.g. segment configuration).
Returns {:ok, collection} on success.
@spec create!(String.t(), Zvex.Collection.Schema.t(), keyword()) :: t()
Like create/3 but raises on error.
@spec create_index(t(), String.t(), keyword()) :: :ok | {:error, Zvex.Error.t()}
Creates an index on field_name.
opts are index-specific parameters (e.g. type, metric, m,
ef_construction). See Zvex.Collection.Schema.IndexParams for the
full list of supported options.
Like create_index/3 but raises on error.
@spec delete(t(), [String.t()]) :: {:ok, %{success: non_neg_integer(), errors: non_neg_integer()}} | {:error, Zvex.Error.t()}
Deletes documents by their primary keys.
Returns a summary with :success and :errors counts.
@spec delete!(t(), [String.t()]) :: %{ success: non_neg_integer(), errors: non_neg_integer() }
Like delete/2 but raises on error.
@spec delete_by_filter(t(), String.t()) :: :ok | {:error, Zvex.Error.t()}
Deletes all documents matching a filter expression.
The filter is a zvec filter expression string (same syntax as
Zvex.Query.filter/2).
Like delete_by_filter/2 but raises on error.
@spec delete_with_results(t(), [String.t()]) :: {:ok, [map()]} | {:error, Zvex.Error.t()}
Deletes documents and returns per-document result details. See insert_with_results/2.
Like delete_with_results/2 but raises on error.
@spec drop(t()) :: :ok | {:error, Zvex.Error.t()}
Closes the collection (if open) and deletes its data directory from disk.
This is a destructive, irreversible operation.
@spec drop!(t()) :: :ok
Like drop/1 but raises on error.
@spec drop_column(t(), String.t()) :: :ok | {:error, Zvex.Error.t()}
Removes a column from the collection schema. Existing data for this column is discarded.
Like drop_column/2 but raises on error.
@spec drop_index(t(), String.t()) :: :ok | {:error, Zvex.Error.t()}
Removes the index from field_name.
Like drop_index/2 but raises on error.
@spec fetch(t(), [String.t()]) :: {:ok, [Zvex.Document.t()]} | {:error, Zvex.Error.t()}
Fetches documents by their primary keys.
Returns a list of Zvex.Document structs in the same order as the requested
keys. Missing keys are silently skipped.
@spec fetch!(t(), [String.t()]) :: [Zvex.Document.t()]
Like fetch/2 but raises on error.
@spec field_names(t()) :: {:ok, [String.t()]} | {:error, Zvex.Error.t()}
Returns the names of all fields. Shorthand for field_names(collection, :all).
@spec field_names(t(), :all | :forward | :vector | :indexed) :: {:ok, [String.t()]} | {:error, Zvex.Error.t()}
Returns the names of fields matching category.
Categories:
:all— every field in the schema:forward— scalar/forward-stored fields:vector— vector fields (dense and sparse):indexed— fields that have an index
Like field_names/1 but raises on error.
Like field_names/2 but raises on error.
@spec flush(t()) :: :ok | {:error, Zvex.Error.t()}
Flushes buffered writes to persistent storage.
@spec flush!(t()) :: :ok
Like flush/1 but raises on error.
Returns true if the collection schema contains a field named field_name.
Returns true if the field field_name has an index.
@spec insert(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, %{success: non_neg_integer(), errors: non_neg_integer()}} | {:error, Zvex.Error.t()}
Inserts one or more documents into the collection.
Accepts a single Zvex.Document or a list. Returns a summary map with
:success and :errors counts. Documents whose primary key already exists
will be counted as errors.
@spec insert!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: %{ success: non_neg_integer(), errors: non_neg_integer() }
Like insert/2 but raises on error.
@spec insert_with_results(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, [map()]} | {:error, Zvex.Error.t()}
Inserts documents and returns per-document result details.
Unlike insert/2 which returns aggregate counts, this returns a list of
result maps — one per document — with individual status information.
@spec insert_with_results!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: [map()]
Like insert_with_results/2 but raises on error.
@spec open( String.t(), keyword() ) :: {:ok, t()} | {:error, Zvex.Error.t()}
Opens an existing collection from path.
The collection must have been previously created with create/3. Accepts
the same opts as create/3 for overriding collection-level options.
Like open/2 but raises on error.
@spec optimize(t()) :: :ok | {:error, Zvex.Error.t()}
Triggers index optimization on the collection.
This merges segments and rebuilds indexes for better query performance. Can be a long-running operation on large collections.
@spec optimize!(t()) :: :ok
Like optimize/1 but raises on error.
@spec options(t()) :: {:ok, map()} | {:error, Zvex.Error.t()}
Returns the collection-level options as a map.
Like options/1 but raises on error.
@spec schema(t()) :: {:ok, Zvex.Collection.Schema.t()} | {:error, Zvex.Error.t()}
Returns the Zvex.Collection.Schema of the open collection.
@spec schema!(t()) :: Zvex.Collection.Schema.t()
Like schema/1 but raises on error.
@spec stats(t()) :: {:ok, Zvex.Collection.Stats.t()} | {:error, Zvex.Error.t()}
Returns a Zvex.Collection.Stats struct with the document count and index information.
@spec stats!(t()) :: Zvex.Collection.Stats.t()
Like stats/1 but raises on error.
@spec update(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, %{success: non_neg_integer(), errors: non_neg_integer()}} | {:error, Zvex.Error.t()}
Updates existing documents in the collection.
Documents are matched by primary key. Returns a summary with :success
and :errors counts. Documents whose primary key does not exist will be
counted as errors.
@spec update!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: %{ success: non_neg_integer(), errors: non_neg_integer() }
Like update/2 but raises on error.
@spec update_with_results(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, [map()]} | {:error, Zvex.Error.t()}
Updates documents and returns per-document result details. See insert_with_results/2.
@spec update_with_results!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: [map()]
Like update_with_results/2 but raises on error.
@spec upsert(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, %{success: non_neg_integer(), errors: non_neg_integer()}} | {:error, Zvex.Error.t()}
Inserts or updates documents, depending on whether their primary key exists.
Combines the semantics of insert/2 and update/2. Returns a summary
with :success and :errors counts.
@spec upsert!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: %{ success: non_neg_integer(), errors: non_neg_integer() }
Like upsert/2 but raises on error.
@spec upsert_with_results(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: {:ok, [map()]} | {:error, Zvex.Error.t()}
Upserts documents and returns per-document result details. See insert_with_results/2.
@spec upsert_with_results!(t(), Zvex.Document.t() | [Zvex.Document.t()]) :: [map()]
Like upsert_with_results/2 but raises on error.