Querying Vectors

Perform similarity search and retrieve vectors using JavaScript SDK or Postgres.

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 similarity search finds vectors most similar to a query vector using distance metrics. You can query vectors using the JavaScript SDK or directly from Postgres using SQL.

Comparison to pgvector

Vector buckets and any Foreign Data Wrappers (FDW) they use only support one similarity search algorithm, the <===> distance operator.

Basic similarity search

1
import { createClient } from '@supabase/supabase-js'
2
3
const supabase = createClient('https://your-project-id.supabase.co', 'your-service-key')
4
5
const index = supabase.storage.vectors.from('embeddings').index('documents-openai')
6
7
// Query with a vector embedding
8
const { data, error } = await index.queryVectors({
9
  queryVector: {
10
    float32: [0.1, 0.2, 0.3 /* ... embedding of 1536 dimensions ... */],
11
  },
12
  topK: 5,
13
  returnDistance: true,
14
  returnMetadata: true,
15
})
16
17
if (error) {
18
  console.error('Query failed:', error)
19
} else {
20
  // Results are ranked by similarity (lowest distance = most similar)
21
  data.vectors.forEach((result, rank) => {
22
    console.log(`${rank + 1}. ${result.metadata?.title}`)
23
    console.log(`   Similarity score: ${result.distance.toFixed(4)}`)
24
  })
25
}

1
from supabase import create_client
2
3
supabase = create_client('https://your-project-id.supabase.co', 'your-service-key')
4
5
index = supabase.storage.vectors().from_('embeddings').index('documents-openai')
6
7
# Query with a vector embedding
8
results = index.query(
9
    query_vector={'float32': [0.1, 0.2, 0.3]},  # ... embedding of 1536 dimensions
10
    topK=5,
11
    return_distance=True,
12
    return_metadata=True
13
)
14
15
if results:
16
    # Results are ranked by similarity (lowest distance = most similar)
17
    for rank, result in enumerate(results.vectors, 1):
18
        print(f'{rank}. {result.metadata.get("title") if result.metadata else "N/A"}')
19
        if result.distance is not None:
20
            print(f'   Similarity score: {result.distance:.4f}')

1
-- Setup S3 Vector Wrapper (one-time setup)
2
-- https://supabase.com/docs/guides/database/extensions/wrappers/s3_vectors
3
4
-- Query similar vectors
5
SELECT
6
  key,
7
  metadata->>'title' as title,
8
  embd_distance(data) as distance,
9
  (1 - embd_distance(data)) as similarity_score
10
FROM s3_vectors.documents_openai
11
WHERE data <==> '[0.1, 0.2, 0.3, /* ... embedding ... */]'::embd
12
ORDER BY embd_distance(data) ASC
13
LIMIT 5;

Retrieve more than 100 results

Hosted vector buckets return at most 100 query results per response. To retrieve more nearest-neighbor results, set topK to the total number of results you need, up to 10,000, and follow nextToken until the response omits it. Keep the other query parameters unchanged between requests.

1
import {  } from '@supabase/supabase-js'
2
3
const  = ('https://your-project-id.supabase.co', 'your-service-key')
4
const  = ...('embeddings').('documents-openai')
5
6
const  = {
7
  : {
8
    : [0.1, 0.2, 0.3 /* ... embedding of 1536 dimensions ... */],
9
  },
10
  : 1000,
11
  : true,
12
  : true,
13
}
14
15
const  = []
16
let : string | undefined
17
18
do {
19
  const { ,  } = await .({
20
    ...,
21
    ...( ? {  } : {}),
22
  })
23
24
  if () {
25
    throw 
26
  }
27
28
  .(....)
29
   = .
30
} while ()
31
32
.(`Retrieved ${.} matches`)

Local query limit

Local vector buckets use pgvector. They accept topK values up to 100 and do not support nextToken for queryVectors. See Vector Bucket limits for the provider-specific limits.

Semantic search

Find documents similar to a query by embedding the query text:

1
import { createClient } from '@supabase/supabase-js'
2
import OpenAI from 'openai'
3
4
const supabase = createClient(...)
5
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
6
7
async function semanticSearch(query, topK = 5) {
8
  // Embed the query
9
  const queryEmbedding = await openai.embeddings.create({
10
    model: 'text-embedding-3-small',
11
    input: query
12
  })
13
14
  const queryVector = queryEmbedding.data[0].embedding
15
16
  // Search for similar vectors
17
  const { data, error } = await supabase.storage.vectors
18
    .from('embeddings')
19
    .index('documents-openai')
20
    .queryVectors({
21
      queryVector: { float32: queryVector },
22
      topK,
23
      returnDistance: true,
24
      returnMetadata: true
25
    })
26
27
  if (error) {
28
    throw error
29
  }
30
31
  return data.vectors.map((result) => ({
32
    id: result.key,
33
    title: result.metadata?.title,
34
    similarity: 1 - result.distance, // Convert distance to similarity (0-1)
35
    metadata: result.metadata
36
  }))
37
}
38
39
// Usage
40
const results = await semanticSearch('How do I use vector search?')
41
results.forEach((result) => {
42
  console.log(`${result.title} (${(result.similarity * 100).toFixed(1)}% similar)`)
43
})

1
from supabase import create_client
2
from openai import OpenAI
3
import os
4
5
supabase = create_client(...)
6
openai = OpenAI(api_key=os.environ.get('OPENAI_API_KEY'))
7
8
async def semantic_search(query, top_k=5):
9
    # Embed the query
10
    query_embedding = openai.embeddings.create(
11
        model='text-embedding-3-small',
12
        input=query
13
    )
14
15
    query_vector = query_embedding.data[0].embedding
16
17
    # Search for similar vectors
18
    results = supabase.storage.vectors() \
19
        .from_('embeddings') \
20
        .index('documents-openai') \
21
        .query(
22
            query_vector={'float32': query_vector},
23
            topK=top_k,
24
            return_distance=True,
25
            return_metadata=True
26
        )
27
28
    return [
29
        {
30
            'id': result.key,
31
            'title': result.metadata.get('title') if result.metadata else None,
32
            'similarity': 1 - result.distance if result.distance else 0,  # Convert distance to similarity (0-1)
33
            'metadata': result.metadata
34
        }
35
        for result in results.vectors
36
    ]
37
38
# Usage
39
results = semantic_search('How do I use vector search?')
40
for result in results:
41
    print(f'{result["title"]} ({result["similarity"] * 100:.1f}% similar)')

1
-- Semantic search from PostgreSQL
2
-- First, generate embedding from external API and store in a variable
3
-- Then use it to query vectors
4
5
WITH query_embedding AS (
6
  SELECT '[/* ... embedding from OpenAI API ... */]'::embd as embedding
7
)
8
SELECT
9
  key,
10
  metadata->>'title' as title,
11
  embd_distance(data) as distance,
12
  (1 - embd_distance(data)) as similarity_score
13
FROM s3_vectors.documents_openai,
14
     query_embedding
15
WHERE data <==> query_embedding.embedding
16
ORDER BY embd_distance(data) ASC
17
LIMIT 5;

Filtered similarity search

1
const index = supabase.storage.vectors
2
  .from('embeddings')
3
  .index('documents-openai')
4
5
// Search with metadata filter
6
const { data } = await index.queryVectors({
7
  queryVector: { float32: [...embedding...] },
8
  topK: 10,
9
  filter: {
10
    // Filter by metadata fields
11
    category: 'electronics',
12
    in_stock: true,
13
    price: { $lte: 500 } // Less than or equal to 500
14
  },
15
  returnDistance: true,
16
  returnMetadata: true
17
})

1
index = supabase.storage.vectors() \
2
    .from_('embeddings') \
3
    .index('documents-openai')
4
5
# Search with metadata filter
6
results = index.query(
7
    query_vector={'float32': [...embedding...]},
8
    topK=10,
9
    filter={
10
        # Filter by metadata fields
11
        'category': 'electronics',
12
        'in_stock': True,
13
        'price': {'$lte': 500}  # Less than or equal to 500
14
    },
15
    return_distance=True,
16
    return_metadata=True
17
)

1
-- Search with metadata filters
2
SELECT
3
  key,
4
  metadata->>'title' as title,
5
  (metadata->>'price')::numeric as price,
6
  embd_distance(data) as distance,
7
  (1 - embd_distance(data)) as similarity
8
FROM s3_vectors.documents_openai
9
WHERE data <==> '[...]'::embd
10
  AND (metadata->>'category') = 'electronics'
11
  AND (metadata->>'in_stock')::boolean = true
12
  AND (metadata->>'price')::numeric <= 500
13
ORDER BY embd_distance(data) ASC
14
LIMIT 10;

Retrieving specific vectors

1
const index = supabase.storage.vectors.from('embeddings').index('documents-openai')
2
3
const { data, error } = await index.getVectors({
4
  keys: ['doc-1', 'doc-2', 'doc-3'],
5
  returnData: true,
6
  returnMetadata: true,
7
})
8
9
if (!error) {
10
  data.vectors.forEach((vector) => {
11
    console.log(`${vector.key}: ${vector.metadata?.title}`)
12
  })
13
}

1
index = supabase.storage.vectors().from_('embeddings').index('documents-openai')
2
3
results = index.get('doc-1', 'doc-2', 'doc-3', return_data=True, return_metadata=True)
4
5
if results:
6
    for vector in results.vectors:
7
        print(f'{vector.key}: {vector.metadata.get("title") if vector.metadata else "N/A"}')

1
-- Retrieve specific vectors by key
2
select
3
  key,
4
  data as embedding,
5
  metadata
6
from s3_vectors.documents_openai
7
where key in ('doc-1', 'doc-2', 'doc-3');

Listing vectors

1
const index = supabase.storage.vectors.from('embeddings').index('documents-openai')
2
3
let nextToken = undefined
4
let pageCount = 0
5
6
do {
7
  const { data, error } = await index.listVectors({
8
    maxResults: 100,
9
    nextToken,
10
    returnData: false, // Don't return embeddings for faster response
11
    returnMetadata: true,
12
  })
13
14
  if (error) break
15
16
  pageCount++
17
  console.log(`Page ${pageCount}: ${data.vectors.length} vectors`)
18
19
  data.vectors.forEach((vector) => {
20
    console.log(`  - ${vector.key}: ${vector.metadata?.title}`)
21
  })
22
23
  nextToken = data.nextToken
24
} while (nextToken)

1
index = supabase.storage.vectors().from_('embeddings').index('documents-openai')
2
3
next_token = None
4
page_count = 0
5
6
while True:
7
    results = index.list(
8
        max_results=100,
9
        next_token=next_token,
10
        return_data=False,  # Don't return embeddings for faster response
11
        return_metadata=True
12
    )
13
14
    if not results:
15
        break
16
17
    page_count += 1
18
    print(f'Page {page_count}: {len(results.vectors)} vectors')
19
20
    for vector in results.vectors:
21
        print(f'  - {vector.key}: {vector.metadata.get("title") if vector.metadata else "N/A"}')
22
23
    next_token = results.nextToken
24
    if not next_token:
25
        break

1
-- List all vectors with pagination
2
select
3
  key,
4
  metadata
5
from s3_vectors.documents_openai
6
order by key asc
7
limit 100 offset 0;
8
-- To paginate, increase OFFSET for next page:
9
-- OFFSET 100 for page 2, OFFSET 200 for page 3, etc.

Hybrid search: Vectors + relational data

Combine similarity search with SQL filtering and joins:

1
async function hybridSearch(queryVector, filters) {
2
  const index = supabase.storage.vectors.from('embeddings').index('documents-openai')
3
4
  // Get similar vectors with filters
5
  const { data: vectorResults } = await index.queryVectors({
6
    queryVector: { float32: queryVector },
7
    topK: 100,
8
    filter: filters,
9
    returnDistance: true,
10
    returnMetadata: true,
11
  })
12
13
  // Get additional details from relational database
14
  const { data: details } = await supabase
15
    .from('documents')
16
    .select('*')
17
    .in(
18
      'id',
19
      vectorResults.vectors.map((v) => v.metadata?.doc_id)
20
    )
21
22
  // Merge results
23
  return vectorResults.vectors.map((vector) => {
24
    const detail = details?.find((d) => d.id === vector.metadata?.doc_id)
25
    return {
26
      ...vector,
27
      ...detail,
28
    }
29
  })
30
}

1
def hybrid_search(query_vector, filters):
2
    index = supabase.storage.vectors().from_('embeddings').index('documents-openai')
3
4
    # Get similar vectors with filters
5
    vector_results = index.query(
6
        query_vector={'float32': query_vector},
7
        topK=100,
8
        filter=filters,
9
        return_distance=True,
10
        return_metadata=True
11
    )
12
13
    # Get additional details from relational database
14
    doc_ids = [v.metadata.get('doc_id') for v in vector_results.vectors if v.metadata and v.metadata.get('doc_id')]
15
    details_response = supabase.table('documents').select('*').in_('id', doc_ids).execute()
16
    details = details_response.data if details_response.data else []
17
18
    # Merge results
19
    return [
20
        {
21
            **vector.__dict__ if hasattr(vector, '__dict__') else {},
22
            **next((d for d in details if d['id'] == vector.metadata.get('doc_id')), {})
23
        }
24
        for vector in vector_results.vectors
25
    ]

1
-- Hybrid search: vectors + relational data join
2
SELECT
3
  v.key as vector_id,
4
  v.metadata->>'title' as vector_title,
5
  d.id as document_id,
6
  d.full_text,
7
  d.author,
8
  d.created_at,
9
  embd_distance(v.data) as similarity_score
10
FROM s3_vectors.documents_openai v
11
LEFT JOIN public.documents d
12
  ON v.metadata->>'doc_id' = d.id::text
13
WHERE v.data <==> '[...]'::embd
14
  AND embd_distance(v.data) < 0.3  -- High similarity threshold
15
  AND d.category = 'articles'
16
ORDER BY embd_distance(v.data) ASC
17
LIMIT 50;

Real-world examples

RAG (retrieval-augmented generation)

1
import OpenAI from 'openai'
2
import { createClient } from '@supabase/supabase-js'
3
4
async function retrieveContextForLLM(userQuery) {
5
  const supabase = createClient(...)
6
  const openai = new OpenAI()
7
8
  // 1. Embed the user query
9
  const queryEmbedding = await openai.embeddings.create({
10
    model: 'text-embedding-3-small',
11
    input: userQuery
12
  })
13
14
  // 2. Retrieve relevant documents
15
  const { data: vectorResults } = await supabase.storage.vectors
16
    .from('embeddings')
17
    .index('documents-openai')
18
    .queryVectors({
19
      queryVector: { float32: queryEmbedding.data[0].embedding },
20
      topK: 5,
21
      returnMetadata: true
22
    })
23
24
  // 3. Use vectors to augment LLM prompt
25
  const context = vectorResults.vectors
26
    .map(v => v.metadata?.content || '')
27
    .join('\n\n')
28
29
  const response = await openai.chat.completions.create({
30
    model: 'gpt-4',
31
    messages: [
32
      {
33
        role: 'system',
34
        content: `Use the following context to answer the user's question:\n\n${context}`
35
      },
36
      {
37
        role: 'user',
38
        content: userQuery
39
      }
40
    ]
41
  })
42
43
  return response.choices[0].message.content
44
}

1
from openai import OpenAI
2
from supabase import create_client
3
4
async def retrieve_context_for_llm(user_query):
5
    supabase = create_client(...)
6
    openai = OpenAI()
7
8
    # 1. Embed the user query
9
    query_embedding = openai.embeddings.create(
10
        model='text-embedding-3-small',
11
        input=user_query
12
    )
13
14
    # 2. Retrieve relevant documents
15
    vector_results = supabase.storage.vectors() \
16
        .from_('embeddings') \
17
        .index('documents-openai') \
18
        .query(
19
            query_vector={'float32': query_embedding.data[0].embedding},
20
            topK=5,
21
            return_metadata=True
22
        )
23
24
    # 3. Use vectors to augment LLM prompt
25
    context = '\n\n'.join(
26
        v.metadata.get('content', '') if v.metadata else ''
27
        for v in vector_results.vectors
28
    )
29
30
    response = openai.chat.completions.create(
31
        model='gpt-4',
32
        messages=[
33
            {
34
                'role': 'system',
35
                'content': f'Use the following context to answer the user\'s question:\n\n{context}'
36
            },
37
            {
38
                'role': 'user',
39
                'content': user_query
40
            }
41
        ]
42
    )
43
44
    return response.choices[0].message.content

Product recommendations

1
async function recommendProducts(userEmbedding, topK = 5) {
2
  const supabase = createClient(...)
3
4
  // Find similar products
5
  const { data } = await supabase.storage.vectors
6
    .from('embeddings')
7
    .index('products-openai')
8
    .queryVectors({
9
      queryVector: { float32: userEmbedding },
10
      topK,
11
      filter: {
12
        in_stock: true
13
      },
14
      returnMetadata: true
15
    })
16
17
  return data.vectors.map((result) => ({
18
    id: result.metadata?.product_id,
19
    name: result.metadata?.name,
20
    price: result.metadata?.price,
21
    similarity: 1 - result.distance
22
  }))
23
}

1
def recommend_products(user_embedding, top_k=5):
2
    supabase = create_client(...)
3
4
    # Find similar products
5
    results = supabase.storage.vectors() \
6
        .from_('embeddings') \
7
        .index('products-openai') \
8
        .query(
9
            query_vector={'float32': user_embedding},
10
            topK=top_k,
11
            filter={'in_stock': True},
12
            return_metadata=True
13
        )
14
15
    return [
16
        {
17
            'id': result.metadata.get('product_id') if result.metadata else None,
18
            'name': result.metadata.get('name') if result.metadata else None,
19
            'price': result.metadata.get('price') if result.metadata else None,
20
            'similarity': 1 - result.distance if result.distance else 0
21
        }
22
        for result in results.vectors
23
    ]

Filtering before similarity search

1
// Use metadata filters to reduce search scope
2
const { data } = await index.queryVectors({
3
  queryVector,
4
  topK: 100,
5
  filter: {
6
    category: 'electronics', // Pre-filter by category
7
  },
8
})

1
# Use metadata filters to reduce search scope
2
results = index.query(
3
    query_vector=query_vector,
4
    topK=100,
5
    filter={'category': 'electronics'}  # Pre-filter by category
6
)