Zvec.Collection (zvec v0.4.0)

High-level API for zvec collections.

Example

schema =
  Zvec.Schema.new("test")
  |> Zvec.Schema.add_vector("vec", 4, index: %{type: :hnsw, metric_type: :cosine})

{:ok, col} = Zvec.Collection.create_and_open("/tmp/mydb", schema)
:ok = Zvec.Collection.insert(col, [Zvec.Doc.new("pk1", %{"vec" => vec_binary})])
:ok = Zvec.Collection.optimize(col)
{:ok, results} = Zvec.Collection.query(col, Zvec.Query.vector("vec", [0.1, 0.2, 0.3, 0.4], topk: 1))

Summary

Types

ref()

Functions

create_and_open(path, schema, opts \\ [])

Create a new collection and open it.

create_index(ref, column, params)

Create an index on a column.

delete(ref, pks)

Delete documents by primary keys.

delete_by_filter(ref, filter)

Delete documents matching a filter expression.

destroy(ref)

Destroy the collection (deletes data on disk).

drop_index(ref, column)

Drop an index from a column.

fetch(ref, pks)

Fetch documents by primary keys.

flush(ref)

Flush pending writes to disk.

insert(ref, docs)

Insert documents into the collection.

open(path, opts \\ [])

Open an existing collection.

optimize(ref)

Optimize the collection (build ANN indexes, compact segments).

query(ref, query_map)

Execute a vector similarity query.

schema(ref)

Get the collection schema.

stats(ref)

Get collection statistics.

upsert(ref, docs)

Upsert documents (insert or update if pk exists).

Types

ref()

@type ref() :: reference()

Functions

create_and_open(path, schema, opts \\ [])

@spec create_and_open(String.t(), Zvec.Schema.t(), keyword()) ::
  {:ok, ref()} | {:error, {atom(), String.t()}}

Create a new collection and open it.

Options

:read_only - open read-only (default: false)
:enable_mmap - enable memory mapping (default: true)
:max_buffer_size - write buffer size in bytes (default: 64MB)

create_index(ref, column, params)

@spec create_index(ref(), String.t(), map()) :: :ok | {:error, {atom(), String.t()}}

Create an index on a column.

delete(ref, pks)

@spec delete(ref(), [String.t()]) :: :ok | {:error, {atom(), String.t()}}

Delete documents by primary keys.

delete_by_filter(ref, filter)

@spec delete_by_filter(ref(), String.t()) :: :ok | {:error, {atom(), String.t()}}

Delete documents matching a filter expression.

destroy(ref)

@spec destroy(ref()) :: :ok | {:error, {atom(), String.t()}}

Destroy the collection (deletes data on disk).

drop_index(ref, column)

@spec drop_index(ref(), String.t()) :: :ok | {:error, {atom(), String.t()}}

Drop an index from a column.

fetch(ref, pks)

@spec fetch(ref(), [String.t()]) ::
  {:ok, [Zvec.Doc.t()]} | {:error, {atom(), String.t()}}

Fetch documents by primary keys.

flush(ref)

@spec flush(ref()) :: :ok | {:error, {atom(), String.t()}}

Flush pending writes to disk.

insert(ref, docs)

@spec insert(ref(), [Zvec.Doc.t()]) :: :ok | {:error, {atom(), String.t()}}

Insert documents into the collection.

Returns :ok if all documents were inserted successfully.

open(path, opts \\ [])

@spec open(
  String.t(),
  keyword()
) :: {:ok, ref()} | {:error, {atom(), String.t()}}

Open an existing collection.

optimize(ref)

@spec optimize(ref()) :: :ok | {:error, {atom(), String.t()}}

Optimize the collection (build ANN indexes, compact segments).

query(ref, query_map)

@spec query(ref(), map()) :: {:ok, [Zvec.Doc.t()]} | {:error, {atom(), String.t()}}

Execute a vector similarity query.

Returns {:ok, results} where each result is a Zvec.Doc with :pk, :score, and :fields.

schema(ref)

@spec schema(ref()) :: {:ok, map()} | {:error, {atom(), String.t()}}

Get the collection schema.

stats(ref)

@spec stats(ref()) :: {:ok, map()} | {:error, {atom(), String.t()}}

Get collection statistics.

upsert(ref, docs)

@spec upsert(ref(), [Zvec.Doc.t()]) :: :ok | {:error, {atom(), String.t()}}

Upsert documents (insert or update if pk exists).

Returns :ok if all documents were upserted successfully.