Working with Vector Indexes

Create, manage, and optimize vector indexes for efficient similarity search.

This feature is in alpha

Expect rapid changes, limited features, and possible breaking updates. Share feedback as we refine the experience and expand access.

Vector indexes organize embeddings within a bucket with consistent dimensions and distance metrics. Each index defines how similarity searches are performed across your vectors.

Understanding vector indexes#

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)
Data Type - Vector format (currently float32)

Think of an index as a table in a traditional database. It has a schema (dimension) and a query strategy (distance metric).

Creating indexes#

Via Dashboard#

Open your vector bucket in the Supabase Dashboard.
Click Create Index.
Enter an index name (e.g., documents-openai).
Set the dimension matching your embeddings (e.g., 1536 for OpenAI's text-embedding-3-small).
Select the distance metric (cosine, euclidean, or l2).
Click Create.

Via SDK#

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
4
5
const bucket = supabase.storage.vectors.from('embeddings')
6
7
// Create an index
8
const { data, error } = await bucket.createIndex({
9
  indexName: 'documents-openai',
10
  dataType: 'float32',
11
  dimension: 1536,
12
  distanceMetric: 'cosine',
13
})
14
15
if (error) {
16
  console.error('Error creating index:', error)
17
} else {
18
  console.log('Index created:', data)
19
}

Choosing the right metric#

Most modern embedding models work best with cosine distance:

OpenAI (text-embedding-3-small, text-embedding-3-large): Cosine
Cohere (embed-english-v3.0): Cosine
Hugging Face (sentence-transformers): Cosine
Google (text-embedding-004): Cosine
Llama 2 embeddings: Cosine or L2

Tip: Check your embedding model's documentation for the recommended distance metric.

Important: Creating an index with incorrect dimensions will cause insert and query operations to fail.

Managing multiple indexes#

Create multiple indexes for different use cases or embedding models:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
// Index for OpenAI embeddings
4
await bucket.createIndex({
5
  indexName: 'documents-openai',
6
  dimension: 1536,
7
  distanceMetric: 'cosine',
8
  dataType: 'float32',
9
})
10
11
// Index for Cohere embeddings
12
await bucket.createIndex({
13
  indexName: 'documents-cohere',
14
  dimension: 1024,
15
  distanceMetric: 'cosine',
16
  dataType: 'float32',
17
})
18
19
// Index for different use case
20
await bucket.createIndex({
21
  indexName: 'images-openai',
22
  dimension: 1536,
23
  distanceMetric: 'cosine',
24
  dataType: 'float32',
25
})
26
27
// List all indexes
28
const { data: indexes } = await bucket.listIndexes()
29
console.log('All indexes:', indexes)

Use cases for multiple indexes#

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 - Keep language-specific embeddings separate

Listing and inspecting indexes#

List all indexes in a bucket#

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { data: indexes, error } = await bucket.listIndexes()
4
5
if (!error) {
6
  indexes?.forEach((index) => {
7
    console.log(`Index: ${index.name}`)
8
    console.log(`  Dimension: ${index.dimension}`)
9
    console.log(`  Distance: ${index.distanceMetric}`)
10
  })
11
}

Get index details#

1
const { data: indexDetails, error } = await bucket.getIndex('documents-openai')
2
3
if (!error && indexDetails) {
4
  console.log(`Index: ${indexDetails.name}`)
5
  console.log(`Created at: ${indexDetails.createdAt}`)
6
  console.log(`Dimension: ${indexDetails.dimension}`)
7
  console.log(`Distance metric: ${indexDetails.distanceMetric}`)
8
}

Deleting indexes#

Delete an index to free storage space:

1
const bucket = supabase.storage.vectors.from('embeddings')
2
3
const { error } = await bucket.deleteIndex('documents-openai')
4
5
if (error) {
6
  console.error('Error deleting index:', error)
7
} else {
8
  console.log('Index deleted successfully')
9
}

Before deleting an index#

Warning: Deleting an index is permanent and cannot be undone.

Backup important data - Export vectors before deletion if needed
Update applications - Ensure no code references the deleted index
Check dependencies - Verify no active queries use the index
Plan the deletion - Do this during low-traffic periods

Immutable properties#

Once 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

Optimizing index performance#

1
// Good - Appropriate batch size
2
const batch = vectors.slice(0, 250)
3
await index.putVectors({ vectors: batch })
4
5
// Good - Filter metadata before query
6
const { data } = await index.queryVectors({
7
  queryVector,
8
  topK: 5,
9
  filter: { category: 'electronics' },
10
})
11
12
// Avoid - Single vector inserts
13
for (const vector of vectors) {
14
  await index.putVectors({ vectors: [vector] })
15
}
16
17
// Avoid - Returning unnecessary data
18
const { data } = await index.queryVectors({
19
  queryVector,
20
  topK: 1000, // Too many results
21
  returnData: true, // Include large embeddings
22
})