apps/www/_blog/2025-12-01-vector-buckets.mdx
Today, we're introducing Vector Buckets, a new storage option that gives you the durability and cost efficiency of Amazon S3 with built-in similarity search.
Vector search is becoming a core primitive for modern apps: semantic search, recommendations, RAG, image and audio similarity, and more.
Supabase already gives you powerful tools for vectors, such as pgvector in Postgres. With Vector Buckets, you now have more options for how you store vectors:
Vector Buckets are a new bucket type in Supabase Storage.
Conceptually:
documents-openai).Embeddings add up quickly: thousands of floats per vector, multiplied by millions of items.
Instead of putting everything in Postgres, Vector Buckets store your embeddings in S3-backed object storage, which gives you:
Your vectors live in a storage layer built for large datasets, while you still query them through Postgres.
Vector Buckets are not just blobs of float arrays. Each index supports similarity search out of the box.
Similarity search lets you find items that are conceptually related based on their vector representations, not just exact keyword matches. That’s what powers:
With Vector Buckets, you can:
No extra vector database to run, no new query language. Just vector indexes with search, available from the same Supabase SDKs you already use or directly via Postgres.
Vector Buckets are designed to provide sub-second similarity search over large datasets, which is more than enough for:
If you’re chasing ultra-low latency at very high QPS, pgvector in a tuned Postgres cluster (or a dedicated vector database) remains the best place to push performance. Vector Buckets focus on simple, scalable similarity search at large scale, not on being the absolute fastest option.
Each vector can include an arbitrary metadata object, for example:
metadata: {
title: 'Getting started with Vector Buckets',
type: 'doc',
language: 'en',
project_id: '1234',
}
You can:
type = 'doc' AND language = 'en')This makes it easy to build domain-aware, tenant-aware semantic search.
pgvector?Vector Buckets and pgvector are complementary. They serve different roles and work best together.
pgvector when…documents or products)pgvector for the highest-traffic / most latency-sensitive queriesIn practice, many apps will use both:
pgvector.At a high level, here’s what happens under the hood:
1. Vector Bucket in Supabase Storage
You create a bucket of type Vector Bucket in the Dashboard or via API.
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project.supabase.co', 'your-service-key')
await supabase.storage.vectors.createBucket('embeddings')
2. Create Vector indexes inside the bucket
Inside the Vector Bucket, you create one or more indexes.
// Create an index in that bucket
await supabase.storage.vectors.from('embeddings').createIndex('documents-openai', {
dimension: 1536,
distanceMetric: 'cosine',
})
3. Store vectors
You can store vectors directly from the SDK, an Edge Function, or Postgres.
// Postgres
INSERT INTO s3_vectors.documents_openai (key, data, metadata)
VALUES
(
'doc-1',
'[0.1, 0.2, 0.3, /* ... rest of embedding ... */]'::embd,
'{"title": "Getting Started with Vector Buckets", "source": "documentation"}'::jsonb
),
(
'doc-2',
'[0.4, 0.5, 0.6, /* ... rest of embedding ... */]'::embd,
'{"title": "Advanced Vector Search", "source": "blog"}'::jsonb
);
// JS-SDK (server only)
const index = supabase.storage.vectors
.from('embeddings')
.index('documents-openai')
const { error } = await index.putVectors({
vectors: [
{
key: 'doc-1',
data: {
float32: [0.1, 0.2, 0.3 /* ... */],
},
metadata: {
title: 'Getting started with Vector Buckets',
type: 'doc',
language: 'en',
},
},
],
})
4. Query vectors
You can run similarity search queries against your indexes, either via the SDK or Postgres.
// Postgres
SELECT
key,
metadata->>'title' as title,
embd_distance(data) as distance
FROM s3_vectors.documents_openai
WHERE data <==> '[0.1, 0.2, 0.3, /* ... embedding ... */]'::embd
ORDER BY embd_distance(data) ASC
LIMIT 5;
// JS-SDK (Server only)
const index = supabase.storage.vectors
.from('embeddings')
.index('documents-openai')
// Query with a vector embedding
const { data, error } = await index.queryVectors({
queryVector: {
float32: [0.1, 0.2, 0.3 /* ... embedding of 1536 dimensions ... */],
},
topK: 5,
returnDistance: true,
returnMetadata: true,
})
Vector Buckets currently can handle large-but-not-infinite workloads:
That makes Vector Buckets a great fit for:
A few concrete ways to put Vector Buckets to work:
pgvector for instant in-app search.pgvector first and falls back to Vector Buckets when needed.Vector Buckets are currently available in Public Alpha for Pro projects and above.
Currently supported in the following regions:
More regions will be added in the near future.
We’re using this phase to refine the APIs, scaling behaviour, and search experience based on real workloads. Limits may evolve as we learn from how you use the feature in production.
Vector Buckets are free to use (fair use policy applies) during Public Alpha. Egress costs still apply.
You can try Vector Buckets in your project today:
Create a Vector Bucket
Dashboard → Storage → Create bucket → Vector Bucket.
Create an index
Pick a dimension that matches your embedding model and choose a distance metric.
Store vectors
Use Supabase clients to upsert vectors with metadata.
Query vectors
Build endpoints for semantic search, recommendations, or retrieval-augmented generation.
Layer with pgvector
Keep your hottest, most latency-sensitive vectors in pgvector, and store large archives and media-heavy datasets in Vector Buckets.
We’re excited to see what you build with this new vector storage tier.
As you try Vector Buckets during the Public Alpha, please send feedback—what works, what’s confusing, and what you’d like to see next will directly shape where we take this feature.