storage/vector-indexes

17 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Vector index definition and properties

A vector index organizes embeddings within a bucket with consistent dimensions and distance metrics. Each index defines how similarity searches are performed across vectors. An index specifies: Index Name (unique identifier within the bucket), Dimension (size of vector embeddings, e.g., 1536 for OpenAI), Distance Metric (similarity calculation method: cosine, euclidean, or L2), and Data Type (currently float32).

Create vector index via SDK - JavaScript

To create a vector index in JavaScript, use `supabase.storage.vectors.from('bucket-name').createIndex()` with parameters: indexName (string), dataType ('float32'), dimension (number, e.g., 1536), distanceMetric (string: 'cosine', 'euclidean', or 'l2'). Example: `const { data, error } = await bucket.createIndex({ indexName: 'documents-openai', dataType: 'float32', dimension: 1536, distanceMetric: 'cosine' })`

Create vector index via SDK - Python

To create a vector index in Python, use `supabase.storage.vectors().from_('bucket-name').create_index()` with keyword arguments: index_name (string), dimension (number), distance_metric (string: 'cosine', 'euclidean', or 'l2'), data_type ('float32'). Example: `bucket.create_index(index_name='documents-openai', dimension=1536, distance_metric='cosine', data_type='float32')`

Recommended distance metrics by embedding model

Most modern embedding models work best with cosine distance. OpenAI (text-embedding-3-small, text-embedding-3-large) uses cosine. Cohere (embed-english-v3.0) uses cosine. Hugging Face (sentence-transformers) uses cosine. Google (text-embedding-004) uses cosine. Llama 2 embeddings use cosine or L2. Check your embedding model's documentation for the recommended distance metric.

Vector index dimension mismatch error

Creating an index with incorrect dimensions will cause insert and query operations to fail. Ensure the dimension matches your embedding model's output dimensionality.

List all vector indexes in bucket - JavaScript

To list all indexes in a bucket using JavaScript, call `bucket.listIndexes()` which returns `{ data: indexes, error }`. The indexes array contains objects with properties: name, dimension, distanceMetric.

List all vector indexes in bucket - Python

To list all indexes in a bucket using Python, call `bucket.list_indexes()` which returns an object containing an indexes list. Each index object has properties: indexName, dimension, distance_metric.

Get vector index details - JavaScript

To get details of a specific index using JavaScript, call `bucket.getIndex('index-name')` which returns `{ data: indexDetails, error }`. indexDetails contains: name, createdAt, dimension, distanceMetric.

Get vector index details - Python

To get details of a specific index using Python, call `bucket.get_index('index-name')` which returns an object with an index property. The index object contains: index_name, dimension, distance_metric.

Delete vector index - JavaScript

To delete an index using JavaScript, call `bucket.deleteIndex('index-name')` which returns `{ error }`. Deletion is permanent and cannot be undone.

Delete vector index - Python

To delete an index using Python, call `bucket.delete_index('index-name')`. Deletion is permanent and cannot be undone.

Vector index immutable properties

Once a vector index is created, these properties cannot be changed: Dimension (must create new index with different dimension), Distance metric (cannot change after creation), Data type (currently only float32 supported). To use different values, create a new index with the desired properties.

Precautions before deleting vector index

Before deleting a vector index: backup important data and export vectors before deletion if needed, update applications to ensure no code references the deleted index, check dependencies and verify no active queries use the index, plan the deletion during low-traffic periods.

Use cases for multiple vector indexes

Create multiple indexes for: different embedding models (store vectors from OpenAI, Cohere, and local models separately), different domains (maintain separate indexes for documents, images, products, etc.), A/B testing (compare different embedding models side-by-side), multi-language support (keep language-specific embeddings separate).

Vector index performance optimization - JavaScript

To optimize vector index performance in JavaScript: use appropriate batch sizes (e.g., 250 vectors per batch) when inserting with `index.putVectors({ vectors: batch })`, filter metadata before query with `index.queryVectors({ queryVector, topK: 5, filter: { category: 'electronics' } })`. Avoid: single vector inserts in loops, returning unnecessary data (large topK values or returnData: true with large embeddings).

Vector index performance optimization - Python

To optimize vector index performance in Python: use appropriate batch sizes (e.g., 250 vectors per batch) when inserting with `index.put(batch)`, filter metadata before query with `index.query(query_vector=query_vector, topK=5, filter={'category': 'electronics'})`. Avoid: single vector inserts in loops, returning unnecessary data (large topK values or return_data=True with large embeddings).

Vector indexes feature status

Vector indexes for Supabase Storage are currently in alpha. Expect rapid changes, limited features, and possible breaking updates. Users are encouraged to share feedback on the GitHub discussions.

Give your agent this brain