@spec all(Vettore.Collection.t()) :: {:ok, [Vettore.Embedding.t()]} | {:error, term()}

Returns all embeddings in a collection.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> :ok = Vettore.put(collection, %{id: "a", vector: [0.0, 0.0]})
iex> {:ok, [%Vettore.Embedding{id: "a"}]} = Vettore.all(collection)

@spec batch(Vettore.DB.t(), String.t(), [Vettore.Embedding.t()]) ::
  {:ok, [String.t() | nil]} | {:error, term()}

Inserts many embeddings through the compatibility API.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :l2)
iex> embeddings = [
...>   %Vettore.Embedding{id: "a", vector: [0.0, 0.0]},
...>   %Vettore.Embedding{id: "b", vector: [1.0, 1.0]}
...> ]
iex> Vettore.batch(db, "docs", embeddings)
{:ok, ["a", "b"]}

iex> Vettore.batch(:bad_db, "docs", embeddings)
{:error, :invalid_arguments}

@spec create_collection(Vettore.DB.t(), String.t(), pos_integer(), atom(), keyword()) ::
  {:ok, String.t()} | {:error, term()}

Compatibility collection creation.

examples

Examples

iex> db = Vettore.new()
iex> Vettore.create_collection(db, "docs", 2, :cosine)
{:ok, "docs"}

iex> Vettore.create_collection(:bad_db, "docs", 2, :cosine)
{:error, :invalid_arguments}

@spec delete(Vettore.Collection.t(), String.t()) :: :ok | {:error, term()}

Deletes one embedding by id.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> :ok = Vettore.put(collection, %{id: "a", vector: [0.0, 0.0]})
iex> Vettore.delete(collection, "a")
:ok

@spec delete(Vettore.DB.t(), String.t(), String.t()) ::
  {:ok, String.t()} | {:error, term()}

Deletes one embedding by id through the compatibility API.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :l2)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [0.0, 0.0]})
iex> Vettore.delete(db, "docs", "a")
{:ok, "a"}

iex> Vettore.delete(:bad_db, "docs", "a")
{:error, :invalid_arguments}

@spec delete_collection(Vettore.DB.t(), String.t()) ::
  {:ok, String.t()} | {:error, :invalid_arguments}

Deletes a compatibility collection.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> Vettore.delete_collection(db, "docs")
{:ok, "docs"}

iex> Vettore.delete_collection(:bad_db, "docs")
{:error, :invalid_arguments}

@spec funnel_search(Vettore.Collection.t(), [number()], keyword()) ::
  {:ok, [Vettore.Result.t()]} | {:error, term()}

Runs Matryoshka-style funnel search.

Each stage scores a candidate set with a vector prefix, then final results are reranked with the full stored vectors.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 3, metric: :l2, index: :flat)
iex> :ok =
...>   Vettore.put_many(collection, [
...>     %{id: "near", vector: [1.0, 0.0, 0.0]},
...>     %{id: "far", vector: [-1.0, 0.0, 0.0]}
...>   ])
iex> {:ok, [%Vettore.Result{id: "near"}]} =
...>   Vettore.funnel_search(collection, [1.0, 0.0, 0.0],
...>     stages: [1, 3],
...>     candidates: 2,
...>     limit: 1
...>   )

@spec get(Vettore.Collection.t(), String.t()) ::
  {:ok, Vettore.Embedding.t()} | {:error, term()}

Fetches one embedding by id.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> :ok = Vettore.put(collection, %{id: "a", vector: [0.0, 0.0]})
iex> {:ok, %Vettore.Embedding{id: "a"}} = Vettore.get(collection, "a")

@spec get_all(Vettore.DB.t(), String.t()) ::
  {:ok, [{String.t(), [float()], map() | nil}]} | {:error, term()}

Returns all compatibility collection records as legacy tuples.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :l2)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [0.0, 0.0], metadata: %{kind: :origin}})
iex> {:ok, [{"a", [0.0, 0.0], %{kind: :origin}}]} = Vettore.get_all(db, "docs")

iex> Vettore.get_all(:bad_db, "docs")
{:error, :invalid_arguments}

@spec get_by_value(Vettore.DB.t(), String.t(), String.t()) ::
  {:ok, Vettore.Embedding.t()} | {:error, term()}

Fetches one embedding by id through the compatibility API.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [1.0, 0.0]})
iex> {:ok, %Vettore.Embedding{id: "a"}} = Vettore.get_by_value(db, "docs", "a")

iex> Vettore.get_by_value(db, "docs", "missing")
{:error, :not_found}

@spec get_by_vector(Vettore.DB.t(), String.t(), [number()]) ::
  {:ok, Vettore.Embedding.t()} | {:error, term()}

Fetches the first embedding matching a normalized vector.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [1.0, 0.0]})
iex> {:ok, %Vettore.Embedding{id: "a"}} = Vettore.get_by_vector(db, "docs", [1.0, 0.0])

iex> Vettore.get_by_vector(db, "docs", [0.0, 1.0])
{:error, :not_found}

@spec hybrid_search(Vettore.Collection.t(), [number()], keyword()) ::
  {:ok, [Vettore.Result.t()]} | {:error, term()}

Runs a hybrid candidate pipeline with final reranking.

:generators accepts atoms or keyword entries. Supported generators:

• :funnel - Matryoshka-style prefix candidate search
• :quantized - binary sign-bit candidate search
• :search - the collection's configured index
• :hnsw - alias for :search when the collection uses index: :hnsw

The default final reranker is exact vector scoring. Pass rerank: {:multi_vector, query_vectors} for ColBERT-style late interaction over the union of generated candidates.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2, index: :flat)
iex> :ok =
...>   Vettore.put_many(collection, [
...>     %{id: "near", vector: [1.0, 1.0]},
...>     %{id: "far", vector: [-1.0, -1.0]}
...>   ])
iex> {:ok, [%Vettore.Result{id: "near"}]} =
...>   Vettore.hybrid_search(collection, [1.0, 1.0],
...>     generators: [
...>       funnel: [stages: [1, 2], candidates: 2],
...>       quantized: [candidates: 2]
...>     ],
...>     limit: 1
...>   )

@spec insert(Vettore.DB.t(), String.t(), Vettore.Embedding.t()) ::
  {:ok, String.t() | nil} | {:error, term()}

Inserts one embedding through the compatibility API.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> embedding = %Vettore.Embedding{id: "a", vector: [1.0, 0.0]}
iex> Vettore.insert(db, "docs", embedding)
{:ok, "a"}

iex> Vettore.insert(:bad_db, "docs", %Vettore.Embedding{id: "a", vector: [1.0, 0.0]})
{:error, :invalid_arguments}

@spec load_snapshot(
  Path.t(),
  keyword()
) :: {:ok, Vettore.Collection.t()} | {:error, term()}

Loads a collection snapshot.

Pass options such as index: :flat or index: :hnsw to rebuild the loaded collection with a different index.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> :ok = Vettore.put(collection, %{id: "a", vector: [1.0, 2.0]})
iex> path = Path.join(System.tmp_dir!(), "vettore_load_example.ets")
iex> :ok = Vettore.snapshot(collection, path)
iex> {:ok, loaded} = Vettore.load_snapshot(path)
iex> {:ok, embedding} = Vettore.get(loaded, "a")
iex> File.rm(path)
iex> embedding.id
"a"

@spec multi_vector_search(Vettore.Collection.t(), [[number()]], keyword()) ::
  {:ok, [Vettore.Result.t()]} | {:error, term()}

Runs ColBERT-style late interaction over multi-vector records.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :inner_product)
iex> :ok =
...>   Vettore.put_many(collection, [
...>     %{id: "both_axes", vectors: [[1.0, 0.0], [0.0, 1.0]]},
...>     %{id: "one_axis", vectors: [[1.0, 0.0], [-1.0, 0.0]]}
...>   ])
iex> {:ok, [%Vettore.Result{id: "both_axes", score: 2.0} | _]} =
...>   Vettore.multi_vector_search(
...>     collection,
...>     [[1.0, 0.0], [0.0, 1.0]],
...>     limit: 1
...>   )

@spec new() :: Vettore.DB.t()

Creates a lightweight ETS-backed compatibility database.

examples

Examples

iex> db = Vettore.new()
iex> match?(%Vettore.DB{}, db)
true

@spec new(keyword()) :: {:ok, Vettore.Collection.t()} | {:error, term()}

Creates an ETS-backed vector collection.

This is the preferred public constructor for new code. Use Vettore.new/0 only when you need the older compatibility database API.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :cosine)
iex> collection.metric
:cosine

iex> {:ok, collection} =
...>   Vettore.new(
...>     dimensions: 2,
...>     metric: :l2,
...>     index: :hnsw,
...>     index_options: [m: 4, m0: 8, ef_construction: 16]
...>   )
iex> collection.index_options[:m]
4

@spec prepare_query(Vettore.Collection.t(), [number()]) ::
  {:ok, [float()]} | {:error, term()}

Validates and normalizes a query for a collection.

@spec put(Vettore.Collection.t(), Vettore.Embedding.t() | map()) ::
  :ok | {:error, term()}

Inserts one embedding into a collection.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> Vettore.put(collection, %{id: "a", vector: [0.0, 0.0]})
:ok

@spec put_many(Vettore.Collection.t(), [Vettore.Embedding.t() | map()]) ::
  :ok | {:error, term()}

Inserts many embeddings into a collection.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> Vettore.put_many(collection, [
...>   %{id: "a", vector: [0.0, 0.0]},
...>   %{id: "b", vector: [1.0, 1.0]}
...> ])
:ok

@spec quantized_search(Vettore.Collection.t(), [number()], keyword()) ::
  {:ok, [Vettore.Result.t()]} | {:error, term()}

Runs binary sign-bit candidate search followed by exact reranking.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2, index: :flat)
iex> :ok =
...>   Vettore.put_many(collection, [
...>     %{id: "near", vector: [1.0, 1.0]},
...>     %{id: "far", vector: [-1.0, -1.0]}
...>   ])
iex> {:ok, [%Vettore.Result{id: "near"}]} =
...>   Vettore.quantized_search(collection, [1.0, 1.0],
...>     candidates: 2,
...>     limit: 1
...>   )

@spec rerank(Vettore.DB.t(), String.t(), [{String.t(), float()}], keyword()) ::
  {:ok, [{String.t(), float()}]} | {:error, term()}

Applies MMR reranking to compatibility search results.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [1.0, 0.0]})
iex> {:ok, "b"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "b", vector: [0.0, 1.0]})
iex> Vettore.rerank(db, "docs", [{"a", 0.9}, {"b", 0.8}], limit: 1)
{:ok, [{"a", 0.9}]}

iex> Vettore.rerank(:bad_db, "docs", [{"a", 0.9}])
{:error, :invalid_arguments}

@spec search(Vettore.Collection.t(), [number()], keyword()) ::
  {:ok, [Vettore.Result.t()]} | {:error, term()}

Runs the configured collection search.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> :ok = Vettore.put(collection, %{id: "near", vector: [0.0, 0.0]})
iex> {:ok, [%Vettore.Result{id: "near"}]} = Vettore.search(collection, [0.0, 0.0], limit: 1)

@spec similarity_search(Vettore.DB.t(), String.t(), [number()], keyword()) ::
  {:ok, [{String.t(), float()}]} | {:error, term()}

Searches a compatibility collection.

examples

Examples

iex> db = Vettore.new()
iex> {:ok, "docs"} = Vettore.create_collection(db, "docs", 2, :cosine)
iex> {:ok, "a"} = Vettore.insert(db, "docs", %Vettore.Embedding{id: "a", vector: [1.0, 0.0]})
iex> {:ok, [{"a", score}]} = Vettore.similarity_search(db, "docs", [1.0, 0.0], limit: 1)
iex> score
1.0

iex> Vettore.similarity_search(:bad_db, "docs", [1.0, 0.0])
{:error, :invalid_arguments}

@spec snapshot(Vettore.Collection.t(), Path.t()) :: :ok | {:error, term()}

Saves a collection snapshot.

Only canonical ETS state is written. Native index state is rebuilt when a snapshot is loaded.

examples

Examples

iex> {:ok, collection} = Vettore.new(dimensions: 2, metric: :l2)
iex> path = Path.join(System.tmp_dir!(), "vettore_snapshot_example.ets")
iex> Vettore.snapshot(collection, path)
:ok
iex> File.rm(path)
:ok