Supabase Vector

Learning Objectives

• Understand what Supabase Vector is and how pgvector adds vector search to PostgreSQL
• Identify when using Supabase Vector eliminates the need for a separate dedicated vector database
• Evaluate the trade-offs between Supabase Vector (integrated) and standalone services like Pinecone

What Is Supabase Vector?

Supabase Vector is vector storage and similarity search built directly into Supabase's PostgreSQL database via the pgvector extension. Instead of spinning up a separate vector database service alongside your application database, Supabase Vector lets you store embeddings in the same PostgreSQL database where your application data already lives — as a vector column type, queryable with standard SQL.

For developers already using Supabase for auth, user data, and application storage (as this platform does), Supabase Vector is often the simplest path to adding RAG or semantic search: no new service to provision, no new API to learn, no additional data to keep in sync between systems.

How Supabase Vector Works

pgvector adds a native vector data type to PostgreSQL, along with vector-specific operators and indexes:

-- Enable the pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create a table with a vector column (1536 dimensions for text-embedding-3-small)
CREATE TABLE documents (
  id         bigserial PRIMARY KEY,
  content    text,
  metadata   jsonb,
  embedding  vector(1536)
);

-- Add an IVFFlat index for fast approximate nearest neighbor search
CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops)
  WITH (lists = 100);

-- Insert a document with its embedding
INSERT INTO documents (content, embedding)
VALUES ('Supabase Vector enables semantic search in PostgreSQL', '[0.1, 0.02, ...]');

-- Semantic similarity search: find 5 most similar documents
SELECT content, 1 - (embedding <=> '[query_vector]') AS similarity
FROM documents
ORDER BY embedding <=> '[query_vector]'
LIMIT 5;

The <=> operator computes cosine distance. <-> computes Euclidean distance. Standard SQL handles the rest.

Key Advantages of the Integrated Approach

Single Database, Single Service

Every embedding lives in the same database as your application data:

• User's documents → stored in Supabase → embeddings in the same row or a related table
• No data synchronization between app DB and vector DB
• One connection string, one dashboard, one billing account
• Queries can JOIN vector search results with user data, filters, and business logic in a single SQL query

Row-Level Security (RLS) Applies Automatically

Because vectors are stored in a regular PostgreSQL table, Supabase's Row-Level Security policies apply:

-- RLS policy: users can only search their own documents
CREATE POLICY "Users can search their own documents"
ON documents FOR SELECT
USING (auth.uid() = user_id);

With a dedicated vector database like Pinecone, you need to implement user data isolation yourself (via namespaces). With Supabase Vector, your existing RLS policies handle it automatically.

SQL Joins with Vector Results

Combine semantic search with relational filters in one query:

-- Find relevant documents from the last 30 days, by this user, sorted by similarity
SELECT d.content, d.created_at, 1 - (d.embedding <=> $1) AS similarity
FROM documents d
JOIN users u ON d.user_id = u.id
WHERE d.user_id = auth.uid()
  AND d.created_at > NOW() - INTERVAL '30 days'
  AND d.category = $2
ORDER BY d.embedding <=> $1
LIMIT 10;

This SQL query combines vector similarity, time filtering, ownership, and category — impossible in a pure vector database without bringing data back to the application layer.

Supabase AI Helpers

Supabase provides official utilities for common AI workflows:

Edge Functions for Embedding Generation

// Supabase Edge Function that generates embeddings on new documents
import { createClient } from 'https://esm.sh/@supabase/supabase-js'
import OpenAI from 'https://deno.land/x/openai/mod.ts'

const supabase = createClient(Deno.env.get('SUPABASE_URL'), Deno.env.get('SUPABASE_SERVICE_ROLE_KEY'))
const openai = new OpenAI({ apiKey: Deno.env.get('OPENAI_API_KEY') })

// Trigger this via a database webhook when a new document is inserted
Deno.serve(async (req) => {
  const { content, id } = await req.json()
  const embedding = await openai.embeddings.create({ model: 'text-embedding-3-small', input: content })
  await supabase.from('documents').update({ embedding: embedding.data[0].embedding }).eq('id', id)
  return new Response('OK')
})

Vector Dimension Support

pgvector supports vectors up to 2,000 dimensions — sufficient for all major embedding models:

Studio AI Assistant and the MCP Server

Beyond vectors, Supabase ships AI directly into the developer workflow. The Studio AI Assistant is a built-in helper in the Supabase dashboard that understands your project's schema — it generates SQL, explains tables, and surfaces "Fix with Assistant" buttons across the Studio that can hand a problem off to Claude or ChatGPT. It needs no setup, though it is scoped to the dashboard.

For agent-driven workflows that reach beyond the dashboard, the Supabase MCP Server connects AI coding tools like Cursor, Claude, and GitHub Copilot to the full backend — database, edge functions, storage, and more — through the Model Context Protocol. Together with edge-function embedding generation above, these make Supabase usable not just by AI applications but through AI agents.

Scaling Considerations

For most applications, pgvector performs well:

• HNSW index (available since pgvector 0.5): High-speed approximate search; better performance than IVFFlat for most workloads
• IVFFlat index: Good for datasets up to tens of millions of vectors with proper lists tuning
• Exact search (no index): Reliable for small datasets (under 100K vectors) — always returns the true nearest neighbors

At very large scale (100 million+ vectors), standalone vector databases with specialized hardware and distributed architectures outperform pgvector. For most production applications, pgvector handles the workload comfortably.

Pricing

Supabase Vector is included at no extra charge in all Supabase plans:

Vector storage is counted against the same database storage pool as your regular application data.

Strengths

• Zero extra service: No separate vector DB to provision, authenticate, or pay for
• Full SQL power: JOIN vectors with relational data; apply WHERE clauses; use window functions
• RLS works automatically: Existing Supabase security policies apply to vector queries
• Familiar tooling: Supabase dashboard, SQL Editor, and JS/Python clients work for vector operations
• Free on all plans: No vector-specific pricing — included in standard Supabase plans
• HNSW index performance: Fast approximate search competitive with dedicated vector DBs for typical production workloads
• Supabase ecosystem: Works with Supabase Auth, Storage, Edge Functions, and Realtime

Limitations & Considerations

• Scale ceiling: At 100 million+ vectors, dedicated vector databases with specialized hardware outperform pgvector
• PostgreSQL overhead: General-purpose database adds overhead vs. purpose-built vector stores for high-QPS vector-only workloads
• Index tuning required: HNSW and IVFFlat indexes need parameter tuning (m, ef_construction, lists) for optimal performance as data grows
• 2,000 dimension limit: pgvector supports up to 2,000 dimensions (use halfvec for larger embedding models)

Best Use Cases

When to choose alternatives:

• Need 100 million+ vectors → Pinecone or Qdrant
• Not using Supabase/PostgreSQL → choose based on your stack (Pinecone for managed, Chroma for local)
• Need sub-10ms vector query latency at high volume → dedicated vector databases

Getting Started

-- 1. Enable pgvector in your Supabase project
CREATE EXTENSION IF NOT EXISTS vector;

-- 2. Create a table for your embeddings
CREATE TABLE knowledge_base (
  id        bigserial PRIMARY KEY,
  user_id   uuid REFERENCES auth.users(id),
  content   text NOT NULL,
  embedding vector(1536),
  created_at timestamptz DEFAULT now()
);

-- 3. Create HNSW index for fast similarity search
CREATE INDEX ON knowledge_base USING hnsw (embedding vector_cosine_ops);

-- 4. Add RLS so users only search their own documents
ALTER TABLE knowledge_base ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Users can manage their own documents"
ON knowledge_base USING (auth.uid() = user_id);

Then use the Supabase client from your Next.js app:

const { data } = await supabase.rpc('match_documents', {
  query_embedding: queryVector,
  match_count: 5
})

Key Takeaways

• Supabase Vector brings vector similarity search to PostgreSQL via pgvector — enabling AI applications to store embeddings in the same database as their application data
• Eliminates the need for a separate vector database service for most use cases — saving cost, complexity, and data synchronization overhead
• Row-Level Security policies automatically apply to vector queries — ideal for multi-tenant apps where each user has their own document store
• SQL power shines: JOIN vector similarity results with relational filters, ownership checks, and business logic in a single query
• Best for Supabase/PostgreSQL-backed applications up to tens of millions of vectors; dedicated vector databases scale better beyond that threshold