Supabase.Storage.Vector.Index (supabase_storage v0.6.1)

Operations for managing vector data within indexes.

This module provides functions for inserting, retrieving, listing, querying, and deleting vectors within a specific index. All operations require a Supabase.Storage.Vector instance with both vector_bucket_name and vector_index_name set.

Usage

# Scope to bucket and index
index = Supabase.Storage.Vector.from(client, "embeddings")
        |> Supabase.Storage.Vector.index("documents")

# Insert vectors
Supabase.Storage.Vector.Index.put_vectors(index, %{
  vectors: [
    %{key: "doc-1", data: %{float32: [0.1, 0.2, ...]}, metadata: %{title: "Intro"}}
  ]
})

# Query similar vectors
Supabase.Storage.Vector.Index.query_vector(index, %{
  query_vector: %{float32: [0.1, 0.2, ...]},
  topK: 5,
  return_distance: true
})

Summary

Types

data_type()

Data type for vector components, currently only float32 is supported

distance_metric()

Distance metrics for similarity calculations

t()

Vector index metadata structure.

Functions

changeset(i, attrs)

create_changeset(i, attrs)

delete_vectors(v, keys)

Deletes vectors by their keys in batch (1-500 keys per request).

get_vectors(v, opts \\ %{})

Retrieves vectors by their keys in batch.

list_vectors(v, opts \\ %{})

Lists vectors in the index with pagination.

put_vectors(v, params \\ %{})

Inserts or updates vectors in batch (1-500 vectors per request).

query_vector(v, query \\ %{})

Queries for similar vectors using approximate nearest neighbor (ANN) search.

Types

data_type()

@type data_type() :: :float32

Data type for vector components, currently only float32 is supported

distance_metric()

@type distance_metric() :: :cosine | :euclidean | :dotproduct

Distance metrics for similarity calculations

t()

@type t() :: %Supabase.Storage.Vector.Index{
  creation_time: integer() | nil,
  data_type: data_type(),
  dimension: integer(),
  distance_metric: distance_metric(),
  index_name: String.t(),
  metadata_configuration:
    nil
    | %Supabase.Storage.Vector.Index.MetadataConfiguration{
        non_filterable_metadata_keys: [String.t()] | nil
      },
  vector_bucket_name: String.t()
}

Vector index metadata structure.

Fields

:index_name - Unique name of the index within the bucket
:vector_bucket_name - Name of the parent vector bucket
:dimension - Dimensionality of vectors (e.g., 384, 768, 1536)
:data_type - Data type of vector components (currently only :float32)
:distance_metric - Similarity metric used for queries
:creation_time - Unix timestamp when the index was created
:metadata_configuration - Configuration for metadata filtering
- :non_filterable_metadata_keys - Keys that cannot be used in filters

Functions

changeset(i, attrs)

create_changeset(i, attrs)

delete_vectors(v, keys)

Deletes vectors by their keys in batch (1-500 keys per request).

Parameters

v - A Supabase.Storage.Vector instance with both bucket and index names set
keys - List of vector keys to delete (1-500 items, required)

Returns

{:ok, :deleted} - Vectors were successfully deleted
{:error, reason} - Operation failed

Examples

iex> index = Supabase.Storage.Vector.from(client, "embeddings")
...>         |> Supabase.Storage.Vector.index("documents")
iex> Supabase.Storage.Vector.Index.delete_vectors(index, ["doc-1", "doc-2", "doc-3"])
{:ok, :deleted}

get_vectors(v, opts \\ %{})

Retrieves vectors by their keys in batch.

Parameters

v - A Supabase.Storage.Vector instance with both bucket and index names set
opts - Map with:
- :keys - List of vector keys to retrieve (required)
- :return_data - Whether to include vector data in response (optional, default: false)
- :return_metadata - Whether to include metadata in response (optional, default: false)

Returns

{:ok, response} - Successfully retrieved vectors
{:error, reason} - Operation failed

Examples

iex> index = Supabase.Storage.Vector.from(client, "embeddings")
...>         |> Supabase.Storage.Vector.index("documents")
iex> Supabase.Storage.Vector.Index.get_vectors(index, %{
...>   keys: ["doc-1", "doc-2"],
...>   return_data: true,
...>   return_metadata: true
...> })
{:ok, %Response{body: %{"vectors" => [...]}}}

list_vectors(v, opts \\ %{})

Lists vectors in the index with pagination.

Supports parallel scanning via segment configuration for faster iteration over large datasets.

Parameters

v - A Supabase.Storage.Vector instance with both bucket and index names set
opts - Map with:
- :max_results - Maximum number of results to return (optional, default: 500, max: 1000)
- :next_token - Token for pagination from previous response (optional)
- :return_data - Whether to include vector data in response (optional, default: false)
- :return_metadata - Whether to include metadata in response (optional, default: false)
- :segment_count - Total number of parallel segments for scanning (optional, 1-16)
- :segment_index - Zero-based index of this segment (optional, 0 to segment_count-1)

Returns

{:ok, response} - Successfully retrieved vectors with pagination token
{:error, reason} - Operation failed

Examples

iex> index = Supabase.Storage.Vector.from(client, "embeddings")
...>         |> Supabase.Storage.Vector.index("documents")
iex> Supabase.Storage.Vector.Index.list_vectors(index, %{
...>   max_results: 100,
...>   return_metadata: true
...> })
{:ok, %Response{body: %{"vectors" => [...], "nextToken" => "..."}}}

put_vectors(v, params \\ %{})

Inserts or updates vectors in batch (1-500 vectors per request).

Vectors are upserted by their key - if a key already exists, it will be updated.

Parameters

v - A Supabase.Storage.Vector instance with both bucket and index names set
params - Map with:
- :vectors - List of vector objects (1-500 items, required):
  - :key - Unique identifier for the vector
  - :data - Vector embedding data: %{float32: [...]}
  - :metadata - Optional arbitrary JSON metadata

Returns

{:ok, :put} - Vectors were successfully inserted/updated
{:error, reason} - Operation failed

Examples

iex> index = Supabase.Storage.Vector.from(client, "embeddings")
...>         |> Supabase.Storage.Vector.index("documents")
iex> Supabase.Storage.Vector.Index.put_vectors(index, %{
...>   vectors: [
...>     %{
...>       key: "doc-1",
...>       data: %{float32: [0.1, 0.2, 0.3]},
...>       metadata: %{title: "Introduction", page: 1}
...>     }
...>   ]
...> })
{:ok, :put}

query_vector(v, query \\ %{})

Queries for similar vectors using approximate nearest neighbor (ANN) search.

Finds the most similar vectors to the query vector based on the index's distance metric.

Parameters

v - A Supabase.Storage.Vector instance with both bucket and index names set
query - Map with:
- :query_vector - Query vector to find similar vectors: %{float32: [...]} (required)
- :topK - Number of nearest neighbors to return (optional, default: 10)
- :filter - Optional JSON filter for metadata (optional)
- :return_distance - Whether to include distance scores (optional, default: false)
- :return_metadata - Whether to include metadata in results (optional, default: false)

Returns

{:ok, response} - Successfully retrieved similar vectors ordered by distance
{:error, reason} - Operation failed

Examples

iex> index = Supabase.Storage.Vector.from(client, "embeddings")
...>         |> Supabase.Storage.Vector.index("documents")
iex> Supabase.Storage.Vector.Index.query_vector(index, %{
...>   query_vector: %{float32: [0.1, 0.2, 0.3]},
...>   topK: 5,
...>   filter: %{category: "technical"},
...>   return_distance: true,
...>   return_metadata: true
...> })
{:ok, %Response{body: %{
  "vectors" => [%{"key" => "doc-1", "distance" => 0.95, ...}],
  "distanceMetric" => "cosine"
}}}