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 {  } from '@supabase/supabase-js'
2
3
const  = ('https://your-project-id.supabase.co', 'your-service-key')
4
5
const  = ...('embeddings')
6
7
// Create an index
8
const { ,  } = await .({
9
  : 'documents-openai',
10
  : 'float32',
11
  : 1536,
12
  : 'cosine',
13
})
14
15
if () {
16
  .('Error creating index:', )
17
} else {
18
  .('Index created:', )
19
}

1
from supabase import create_client
2
3
supabase = create_client('https://your-project-id.supabase.co', 'your-service-key')
4
5
bucket = supabase.storage.vectors().from_('embeddings')
6
7
# Create an index
8
bucket.create_index(
9
    index_name='documents-openai',
10
    dimension=1536,
11
    distance_metric='cosine',
12
    data_type='float32'
13
)
14
15
print('✓ Index created: documents-openai')

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)

1
bucket = supabase.storage.vectors().from_('embeddings')
2
3
# Index for OpenAI embeddings
4
bucket.create_index(
5
    index_name='documents-openai',
6
    dimension=1536,
7
    distance_metric='cosine',
8
    data_type='float32'
9
)
10
11
# Index for Cohere embeddings
12
bucket.create_index(
13
    index_name='documents-cohere',
14
    dimension=1024,
15
    distance_metric='cosine',
16
    data_type='float32'
17
)
18
19
# Index for different use case
20
bucket.create_index(
21
    index_name='images-openai',
22
    dimension=1536,
23
    distance_metric='cosine',
24
    data_type='float32'
25
)
26
27
# List all indexes
28
indexes = bucket.list_indexes()
29
print('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
}

1
bucket = supabase.storage.vectors().from_('embeddings')
2
3
indexes = bucket.list_indexes()
4
5
if indexes:
6
    for index in indexes.indexes:
7
        print(f'Index: {index.indexName}')

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
}

1
index_details = bucket.get_index('documents-openai')
2
3
if index_details:
4
    print(f'Index: {index_details.index.index_name}')
5
    print(f'Dimension: {index_details.index.dimension}')
6
    print(f'Distance metric: {index_details.index.distance_metric}')

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
}

1
bucket = supabase.storage.vectors().from_('embeddings')
2
3
bucket.delete_index('documents-openai')
4
5
print('✓ Index deleted successfully')

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
})

1
# Good - Appropriate batch size
2
batch = vectors[:250]
3
index.put(batch)
4
5
# Good - Filter metadata before query
6
results = index.query(
7
    query_vector=query_vector,
8
    topK=5,
9
    filter={'category': 'electronics'}
10
)
11
12
# Avoid - Single vector inserts
13
for vector in vectors:
14
    index.put([vector])
15
16
# Avoid - Returning unnecessary data
17
results = index.query(
18
    query_vector=query_vector,
19
    topK=1000,  # Too many results
20
    return_data=True  # Include large embeddings
21
)