Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: document filtering vector search by metadata column (#45310)

Katerina Skroumpelou81049969d9b1
diff --git a/apps/docs/content/guides/ai/semantic-search.mdx b/apps/docs/content/guides/ai/semantic-search.mdx
index 3d6188ad603..76f77ac3582 100644
--- a/apps/docs/content/guides/ai/semantic-search.mdx
+++ b/apps/docs/content/guides/ai/semantic-search.mdx
@@ -150,6 +150,56 @@ from match_documents(
In this scenario, you'll likely use a Postgres client library to establish a direct connection from your application to the database. It's best practice to parameterize your arguments before executing the query.
+### Filtering vector search by metadata
+
+In real applications you usually want to combine the similarity search with a filter on another column, for example only matching documents in a given category, owned by a specific user, or carrying matching metadata in a `jsonb` column. The recommended pattern is to push the filter into the SQL function so the planner can combine it with the vector predicate. Chaining `.eq()` after `rpc()` is applied by PostgREST as an outer filter on the function's result, _after_ the function has already executed its similarity ranking and `limit` — so the vector planner can't use it, and selective filters can leave you with fewer than `match_count` rows.
+
+Assuming you've added a `category text` column to `documents`, you can extend the cosine variant of `match_documents` with a typed filter parameter:
+
+```sql
+-- Match documents in a given category using cosine distance (<=>)
+create or replace function match_documents (
+ query_embedding extensions.vector(512),
+ match_threshold float,
+ match_count int,
+ filter_category text
+)
+returns setof documents
+language sql
+as $$
+ select *
+ from documents
+ where documents.category = filter_category
+ and documents.embedding <=> query_embedding < 1 - match_threshold
+ order by documents.embedding <=> query_embedding asc
+ limit least(match_count, 200);
+$$;
+```
+
+If you store side data in a `jsonb metadata` column instead of dedicated columns, the same pattern works with the `@>` containment operator:
+
+```sql
+where documents.metadata @> filter_metadata
+ and documents.embedding <=> query_embedding < 1 - match_threshold
+```
+
+Call the filtered function from your application by passing the extra parameter:
+
+```tsx
+const { data: documents } = await supabase.rpc('match_documents', {
+ query_embedding: embedding,
+ match_threshold: 0.78,
+ match_count: 10,
+ filter_category: 'blog',
+})
+```
+
+<Admonition type="note">
+
+When the filter is selective enough that the post-filter result set falls below `match_count`, an HNSW index can return fewer rows than expected. From `pgvector` 0.8.0, the planner supports iterative index scans that re-enter the index to gather more candidates. See [Filtering with HNSW indexes](/docs/guides/ai/vector-indexes/hnsw-indexes#filtering-with-hnsw-indexes) for details.
+
+</Admonition>
+
## Next steps
As your database scales, you will need an index on your vector columns to maintain fast query speeds. See [Vector indexes](/docs/guides/ai/vector-indexes) for an in-depth guide on the different types of indexes and how they work.
diff --git a/apps/docs/content/guides/ai/vector-columns.mdx b/apps/docs/content/guides/ai/vector-columns.mdx
index 340b09656e7..6ca1aa54955 100644
--- a/apps/docs/content/guides/ai/vector-columns.mdx
+++ b/apps/docs/content/guides/ai/vector-columns.mdx
@@ -157,6 +157,12 @@ In this example `embedding` would be another embedding you wish to compare again
<Admonition type="tip">
+To filter your vector search by another column from the JS client, extend the function above with an extra parameter and `where` clause. See [Filtering vector search by metadata](/docs/guides/ai/semantic-search#filtering-vector-search-by-metadata) for a worked example.
+
+</Admonition>
+
+<Admonition type="tip">
+
Be sure to use embeddings produced from the same embedding model when calculating distance. Comparing embeddings from two different models will produce no meaningful result.
</Admonition>
diff --git a/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx b/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx
index 906e2b9c9a2..6390b7260bb 100644
--- a/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx
+++ b/apps/docs/content/guides/ai/vector-indexes/hnsw-indexes.mdx
@@ -114,6 +114,19 @@ HNSW should be your default choice when creating a vector index. Add the index w
Unlike IVFFlat indexes, you are safe to build an HNSW index immediately after the table is created. HNSW indexes are based on graphs which inherently are not affected by the same limitations as IVFFlat. As new data is added to the table, the index will be filled automatically and the index structure will remain optimal.
+## Filtering with HNSW indexes
+
+Adding a `where` clause to a vector query does not bypass the HNSW index. The Postgres planner picks between using the index and a sequential scan based on the selectivity of the filter and the size of the table. When the index is used, the filter is applied as the index returns candidates.
+
+The trade-off shows up when the filter is selective: an HNSW scan returns the top `k` rows by distance, and if most of those are filtered out you can end up with fewer rows than your `LIMIT`. From `pgvector` 0.8.0, the planner supports **iterative index scans** that automatically scan more of the index until enough results are found, controlled by the `hnsw.iterative_scan` GUC. The default is `off`. The two enabled modes are:
+
+- `strict_order` preserves exact distance ordering across iterations.
+- `relaxed_order` allows slight reordering across iterations for better recall.
+
+`hnsw.max_scan_tuples` (default 20,000) and `hnsw.scan_mem_multiplier` (default 1) bound how far the iterative scan goes. See the [pgvector iterative scans documentation](https://github.com/pgvector/pgvector#iterative-index-scans) for the full reference.
+
+For an end-to-end JavaScript example of filtering a vector search by another column, see [Filtering vector search by metadata](/docs/guides/ai/semantic-search#filtering-vector-search-by-metadata).
+
## Resources
Read more about indexing on `pgvector`'s [GitHub page](https://github.com/pgvector/pgvector#indexing).