@spec all_ids(db_ref()) :: {:ok, [String.t()]} | {:error, String.t()}

Returns a list of all vector IDs currently stored in the database.

@spec calculate_distance(vector(), vector(), metric()) ::
  {:ok, float()} | {:error, String.t()}

Calculates the distance between two vectors a and b using the specified metric.

Supported metrics: :cosine, :euclidean, :dot_product, :manhattan.

Returns {:ok, distance} on success, or {:error, reason} on failure (e.g. dimension mismatch).

@spec count(db_ref()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Convenience alias for db_len/1.

@spec count!(db_ref()) :: non_neg_integer()

Convenience alias for len!/1.

@spec db_len(db_ref()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Returns the total number of vectors in the database.

@spec delete(db_ref(), id_input()) :: {:ok, boolean()} | {:error, String.t()}

Deletes an entry by its ID (string, atom, or integer).

Returns {:ok, true} if deleted, {:ok, false} if not found, or {:error, reason} on failure.

@spec delete!(db_ref(), id_input()) :: boolean()

Deletes an entry by its ID, raising RuntimeError on failure.

@spec distance(vector(), vector(), metric()) :: {:ok, float()} | {:error, String.t()}

Convenience helper for calculate_distance/3, defaulting to :cosine.

@spec distance!(vector(), vector(), metric()) :: float()

Calculates distance between two vectors, raising ArgumentError on failure.

@spec empty?(db_ref()) :: {:ok, boolean()} | {:error, String.t()}

Convenience alias for is_empty/1.

@spec get(db_ref(), id_input()) ::
  {:ok, entry_map()} | {:error, :not_found} | {:error, String.t()}

Convenience alias for get_entry/2.

@spec get!(db_ref(), id_input()) :: entry_map()

Convenience alias for get_entry!/2.

@spec get_entry(db_ref(), id_input()) ::
  {:ok, entry_map()} | {:error, :not_found} | {:error, String.t()}

Retrieves a vector entry by its ID (string, atom, or integer).

Returns {:ok, %{id: id, vector: vector, metadata: metadata}} if found, {:error, :not_found} if no entry with that ID exists, or {:error, reason} on failure.

@spec get_entry!(db_ref(), id_input()) :: entry_map()

Retrieves a vector entry, raising RuntimeError if not found or if an error occurs.

@spec get_struct(db_ref(), id_input()) ::
  {:ok, RuvectorElixir.VectorEntry.t()}
  | {:error, :not_found}
  | {:error, String.t()}

Retrieves a vector entry and returns it as a RuvectorElixir.VectorEntry struct.

@spec get_struct!(db_ref(), id_input()) :: RuvectorElixir.VectorEntry.t()

Retrieves a vector entry as a VectorEntry struct, raising RuntimeError if not found or on error.

@spec info(db_ref()) :: map()

Gets database metadata info including :dimensions, :node_count, :distance_metric, :storage_path, and :hnsw.

@spec insert(db_ref(), entry_input()) :: {:ok, String.t()} | {:error, String.t()}

Inserts a vector entry into the database.

The entry can be:

• A RuvectorElixir.VectorEntry struct.
• A map with :vector (and optional :id, :metadata).
• A raw list of numbers [1.0, 2.0, ...] (in which case a UUID is automatically assigned).

Returns {:ok, id} on success, or {:error, reason} on failure.

Examples

{:ok, id} = RuvectorElixir.insert(db, [0.1, 0.2, 0.3])
{:ok, "doc_1"} = RuvectorElixir.insert(db, %{id: "doc_1", vector: [0.1, 0.2, 0.3], metadata: %{"author" => "Alice"}})

@spec insert!(db_ref(), entry_input()) :: String.t()

Inserts a vector entry into the database, raising ArgumentError on failure.

@spec insert_batch(db_ref(), [entry_input()]) ::
  {:ok, [String.t()]} | {:error, String.t()}

Inserts a batch of vector entries into the database.

Returns {:ok, [id]} on success, or {:error, reason} on failure.

Examples

entries = [
  %{id: "v1", vector: [0.1, 0.2, 0.3]},
  %{id: "v2", vector: [0.4, 0.5, 0.6]}
]
{:ok, ["v1", "v2"]} = RuvectorElixir.insert_batch(db, entries)

@spec insert_batch!(db_ref(), [entry_input()]) :: [String.t()]

Inserts a batch of vector entries into the database, raising ArgumentError on failure.

@spec is_empty(db_ref()) :: {:ok, boolean()} | {:error, String.t()}

Checks if the database is empty.

@spec keys(db_ref()) :: {:ok, [String.t()]} | {:error, String.t()}

Convenience alias for all_ids/1.

@spec keys!(db_ref()) :: [String.t()]

Returns all vector IDs in the database, raising on error.

@spec len(db_ref()) :: {:ok, non_neg_integer()} | {:error, String.t()}

Convenience alias for db_len/1.

@spec len!(db_ref()) :: non_neg_integer()

Returns the total number of vectors in the database, raising on error.

@spec open(Path.t(), pos_integer(), db_options() | keyword()) ::
  {:ok, db_ref()} | {:error, String.t()}

Opens or creates a ruvector database at path with the specified vector dimensions and optional configuration options.

Options can be supplied as either a map or a keyword list.

Options

• :metric / :distance_metric - Distance metric to use (:cosine, :euclidean, :dot_product, :manhattan). Default: :cosine.
• :hnsw - Either a boolean true for default HNSW index parameters, or a map/keyword list with:
  • :m - Number of bi-directional links created per node (default: 16).
  • :ef_construction - Size of dynamic candidate list during construction (default: 100).
  • :ef_search - Size of dynamic candidate list during search (default: 50).
  • :max_elements - Initial capacity of the graph index (default: 1_000_000).
• :quantization - Optional quantization configuration (:scalar, :binary, :none, or product map).

In-Memory Databases

Use a path prefixed with memory:// (e.g. memory://my_session) for a non-persisted in-memory database.

Examples

{:ok, db} = RuvectorElixir.open("my_db.rvf", 128)
{:ok, db} = RuvectorElixir.open("my_db.rvf", 128, metric: :euclidean, hnsw: true)
{:ok, mem_db} = RuvectorElixir.open("memory://transient", 64)

@spec open!(Path.t(), pos_integer(), db_options() | keyword()) :: db_ref()

Opens a database, raising RuntimeError on failure.

@spec open_db(Path.t(), pos_integer()) :: {:ok, db_ref()} | {:error, String.t()}

Opens a ruvector database at path with dimensions.

Equivalent to open(path, dimensions, %{}).

@spec open_db(Path.t(), pos_integer(), db_options() | keyword()) ::
  {:ok, db_ref()} | {:error, String.t()}

Opens a ruvector database with configuration options.

@spec open_db_with_options(Path.t(), pos_integer(), db_options() | nil) ::
  {:ok, db_ref()} | {:error, String.t()}

Native NIF: Opens a ruvector database with optional settings map.

@spec search(db_ref(), vector(), pos_integer()) :: [String.t()] | {:error, String.t()}

Searches the database for the top k closest vectors to query_vector.

Returns a list of matching vector ID strings, or {:error, reason} on failure.

@spec search(db_ref(), vector(), map() | keyword() | nil, pos_integer()) ::
  [String.t()] | {:error, String.t()}

Searches the database for the top k closest vectors matching the optional filter.

Filter can be a map or a keyword list.

Returns a list of matching vector ID strings, or {:error, reason} on failure.

@spec search!(db_ref(), vector(), pos_integer()) :: [String.t()]

Searches the database for top k closest vectors, raising ArgumentError on failure.

@spec search!(db_ref(), vector(), map() | keyword() | nil, pos_integer()) :: [
  String.t()
]

Searches the database for top k closest vectors with filter, raising ArgumentError on failure.

@spec search_detailed(db_ref(), vector(), pos_integer()) ::
  {:ok, [search_result()]} | {:error, String.t()}

Searches the database for top k closest vectors, returning detailed search result maps.

Each result map contains:

• :id - Vector ID string
• :score - Similarity / distance score (lower is closer for distance metrics)
• :vector - Vector embedding float list (or nil)
• :metadata - Metadata map (or nil)

@spec search_detailed(db_ref(), vector(), map() | keyword() | nil, pos_integer()) ::
  {:ok, [search_result()]} | {:error, String.t()}

Searches the database with a metadata filter, returning detailed search results.

@spec search_detailed(
  db_ref(),
  vector(),
  map() | keyword() | nil,
  pos_integer(),
  pos_integer() | nil
) ::
  {:ok, [search_result()]} | {:error, String.t()}

Native NIF: Searches the database with a filter and optional HNSW ef_search override.

@spec search_detailed!(
  db_ref(),
  vector(),
  map() | keyword() | nil,
  pos_integer(),
  pos_integer() | nil
) ::
  [search_result()]

Searches the database returning detailed search results, raising ArgumentError on failure.