Supabase.Storage.Vector (supabase_storage v0.6.1)

API for managing vector buckets in Supabase Storage.

Vector buckets are specialized storage containers for vector embeddings used in similarity search and machine learning applications. This module provides operations for creating, retrieving, listing, and deleting vector buckets.

Public Alpha

This API is currently in public alpha. Features and interfaces may change as the API evolves. Use in production environments at your own discretion.

Example

# Create a vector client
vector = Supabase.Storage.Vector.from(client)

# Create a new vector bucket
{:ok, :created} = Supabase.Storage.Vector.create_bucket(vector, "embeddings")

# Get bucket metadata
{:ok, metadata} = Supabase.Storage.Vector.get_bucket(vector, "embeddings")

# List all buckets
{:ok, buckets} = Supabase.Storage.Vector.list_buckets(vector)

# Delete a bucket (must be empty)
{:ok, :deleted} = Supabase.Storage.Vector.delete_bucket(vector, "embeddings")

Summary

Types

t()

Vector client instance containing the Supabase client and optional bucket name.

Functions

create_bucket(v, vector_bucket_name)

Creates a new vector bucket.

create_index(v, params \\ %{})

Creates a new vector index within the current bucket.

delete_bucket(v, vector_bucket_name)

Deletes a vector bucket.

delete_index(v, index_name)

Deletes a vector index and all its data.

from(client, vector_bucket_name \\ nil)

Creates a new Vector client instance.

get_bucket(v, vector_bucket_name)

Retrieves metadata for a specific vector bucket.

get_index(v, index_name)

Retrieves metadata for a specific vector index.

index(v, index_name \\ nil)

Scopes the vector client to a specific index within the current bucket.

list_buckets(v, options \\ %{max_results: 100})

Lists vector buckets with optional filtering and pagination.

list_indexes(v, options \\ %{max_results: 100})

Lists vector indexes within the current bucket with optional filtering and pagination.

Types

t()

@type t() :: %Supabase.Storage.Vector{
  client: Supabase.Client.t(),
  vector_bucket_name: String.t() | nil,
  vector_index_name: String.t() | nil
}

Vector client instance containing the Supabase client and optional bucket name.

Functions

create_bucket(v, vector_bucket_name)

Creates a new vector bucket.

Vector buckets must have unique names within a project. Once created, buckets can contain multiple vector indexes for different embedding dimensions and distance metrics.

Parameters

v - A Supabase.Storage.Vector instance
vector_bucket_name - Unique name for the new bucket

Returns

{:ok, :created} - Bucket was successfully created
{:error, reason} - Creation failed

Examples

iex> Supabase.Storage.Vector.create_bucket(vector, "embeddings")
{:ok, :created}

iex> Supabase.Storage.Vector.create_bucket(vector, "embeddings")
{:error, %{message: "Bucket already exists"}}

create_index(v, params \\ %{})

Creates a new vector index within the current bucket.

Vector indexes define the structure for storing and querying vectors, including the dimension, distance metric, and optional metadata configuration.

Parameters

v - A Supabase.Storage.Vector instance with vector_bucket_name set
params - Map with index configuration:
- :index_name - Unique name for the index (required)
- :data_type - Data type of vectors, currently only :float32 (required)
- :dimension - Dimensionality of vectors, e.g., 384, 768, 1536 (required)
- :distance_metric - Similarity metric: :cosine, :euclidean, or :dotproduct (required)
- :metadata_configuration - Optional metadata settings (optional)
  - :non_filterable_metadata_keys - List of metadata keys that cannot be used in filters

Returns

{:ok, :created} - Index was successfully created
{:error, reason} - Creation failed

Examples

iex> vector = Supabase.Storage.Vector.from(client, "embeddings")
iex> Supabase.Storage.Vector.create_index(vector, %{
...>   index_name: "documents-openai",
...>   data_type: :float32,
...>   dimension: 1536,
...>   distance_metric: :cosine,
...>   metadata_configuration: %{
...>     non_filterable_metadata_keys: ["raw_text"]
...>   }
...> })
{:ok, :created}

delete_bucket(v, vector_bucket_name)

Deletes a vector bucket.

Important: The bucket must be empty before it can be deleted. All vector indexes and their contents must be removed first.

Parameters

v - A Supabase.Storage.Vector instance
vector_bucket_name - Name of the bucket to delete

Returns

{:ok, :deleted} - Bucket was successfully deleted
{:error, reason} - Deletion failed (e.g., bucket not empty or doesn't exist)

Examples

iex> Supabase.Storage.Vector.delete_bucket(vector, "old-embeddings")
{:ok, :deleted}

iex> Supabase.Storage.Vector.delete_bucket(vector, "embeddings")
{:error, %{message: "Bucket must be empty before deletion"}}

delete_index(v, index_name)

Deletes a vector index and all its data.

Important: This operation permanently deletes the index and all vectors stored in it.

Parameters

v - A Supabase.Storage.Vector instance with vector_bucket_name set
index_name - Name of the index to delete

Returns

{:ok, :deleted} - Index was successfully deleted
{:error, reason} - Deletion failed

Examples

iex> vector = Supabase.Storage.Vector.from(client, "embeddings")
iex> Supabase.Storage.Vector.delete_index(vector, "old-index")
{:ok, :deleted}

from(client, vector_bucket_name \\ nil)

Creates a new Vector client instance.

Parameters

client - A Supabase.Client instance
vector_bucket_name - Optional default bucket name to use for operations (default: nil)
vector_index_name - Optional default index name to use for operations (default: nil)

Returns

A Supabase.Storage.Vector struct.

Examples

iex> client = Supabase.init_client(url, key)
iex> vector = Supabase.Storage.Vector.from(client)
%Supabase.Storage.Vector{client: client, vector_bucket_name: nil}

iex> vector = Supabase.Storage.Vector.from(client, "my-bucket")
%Supabase.Storage.Vector{client: client, vector_bucket_name: "my-bucket"}

get_bucket(v, vector_bucket_name)

Retrieves metadata for a specific vector bucket.

Returns detailed information about a vector bucket including its name, creation time, and encryption configuration if available.

Parameters

v - A Supabase.Storage.Vector instance
vector_bucket_name - Name of the bucket to retrieve

Returns

{:ok, metadata} - Successfully retrieved bucket metadata
{:error, reason} - Bucket not found or retrieval failed

Examples

iex> Supabase.Storage.Vector.get_bucket(vector, "embeddings")
{:ok, %Supabase.Storage.Vector.Metadata{
  vector_bucket_name: "embeddings",
  creation_time: 1704067200,
  encryption_configuration: %{kms_key_arn: nil, sse_type: nil}
}}

get_index(v, index_name)

Retrieves metadata for a specific vector index.

Returns detailed configuration about a vector index including its dimension, distance metric, and metadata configuration.

Parameters

v - A Supabase.Storage.Vector instance with vector_bucket_name set
index_name - Name of the index to retrieve

Returns

{:ok, response} - Successfully retrieved index metadata
{:error, reason} - Index not found or retrieval failed

Examples

iex> vector = Supabase.Storage.Vector.from(client, "embeddings")
iex> Supabase.Storage.Vector.get_index(vector, "documents-openai")
{:ok, %Response{body: %{
  "index" => %{
    "indexName" => "documents-openai",
    "dimension" => 1536,
    "distanceMetric" => "cosine",
    "dataType" => "float32"
  }
}}}

index(v, index_name \\ nil)

Scopes the vector client to a specific index within the current bucket.

This convenience method creates a new client instance with both bucket and index names set, allowing index-scoped operations like put_vectors/2, query_vector/2, etc.

Parameters

v - A Supabase.Storage.Vector instance with vector_bucket_name set
index_name - Name of the index to scope operations to (optional)

Returns

A Supabase.Storage.Vector struct with vector_index_name set.

Examples

iex> vector = Supabase.Storage.Vector.from(client, "embeddings")
iex> index = Supabase.Storage.Vector.index(vector, "documents")
%Supabase.Storage.Vector{
  client: client,
  vector_bucket_name: "embeddings",
  vector_index_name: "documents"
}

# Now you can perform vector operations
iex> Supabase.Storage.Vector.Index.put_vectors(index, %{vectors: [...]})

list_buckets(v, options \\ %{max_results: 100})

Lists vector buckets with optional filtering and pagination.

Supports filtering by name prefix and pagination for large result sets.

Parameters

v - A Supabase.Storage.Vector instance
options - Optional map with the following keys:
- :prefix - Filter buckets by name prefix (optional)
- :max_results - Maximum number of results to return (default: 100, optional)
- :next_token - Token for pagination from previous response (optional)

Returns

{:ok, response} - Successfully retrieved bucket list with optional pagination token
{:error, reason} - List operation failed

Examples

# List all buckets
iex> Supabase.Storage.Vector.list_buckets(vector)
{:ok, %{vector_buckets: [%{vector_bucket_name: "embeddings"}], next_token: nil}}

# Filter by prefix
iex> Supabase.Storage.Vector.list_buckets(vector, %{prefix: "prod-"})
{:ok, %{vector_buckets: [%{vector_bucket_name: "prod-embeddings"}], next_token: nil}}

# Paginate results
iex> Supabase.Storage.Vector.list_buckets(vector, %{max_results: 10, next_token: "..."})
{:ok, %{vector_buckets: [...], next_token: "next_page_token"}}

list_indexes(v, options \\ %{max_results: 100})

Lists vector indexes within the current bucket with optional filtering and pagination.

Parameters

v - A Supabase.Storage.Vector instance with vector_bucket_name set
options - Optional map with the following keys:
- :prefix - Filter indexes by name prefix (optional)
- :max_results - Maximum number of results to return (default: 100, optional)
- :next_token - Token for pagination from previous response (optional)

Returns

{:ok, response} - Successfully retrieved index list with optional pagination token
{:error, reason} - List operation failed

Examples

iex> vector = Supabase.Storage.Vector.from(client, "embeddings")
iex> Supabase.Storage.Vector.list_indexes(vector)
{:ok, %Response{body: %{
  "indexes" => [%{"indexName" => "documents-openai"}],
  "nextToken" => nil
}}}

# Filter by prefix
iex> Supabase.Storage.Vector.list_indexes(vector, %{prefix: "documents-"})
{:ok, %Response{body: %{"indexes" => [...]}}}