Engineering Notes

Note 03 / Architecture · Search

pgvector with Django: check filters and recall

A tenant filter limits visible data. The execution plan determines whether ANN search finds enough results.

Visibility and search quality are separate questions

PostgreSQL can keep document metadata, permissions and embeddings in one database. This simplifies relationships but replaces neither authorisation nor search tests. A WHERE condition on tenant_id limits returned data; it does not guarantee that an approximate index finds enough candidates from that tenant.

In particular, the order of filter() and order_by() in Django source does not impose physical execution order. In this example, both chains generate the same SQL query. PostgreSQL chooses the plan. With ANN indexes, filtering happens after the index scan, so selective filters can leave fewer results than expected.

A bounded ORM query

The example uses synthetic three-dimensional vectors. The supplied tenant must already be authorised. It enables HNSW iterative scans locally within a transaction, requiring pgvector 0.8.0 or later. Create the vector extension before migrating the model. Evaluate the list within the transaction so the setting actually applies.

Python · model and tenant-scoped vector search
from django.db import models, transaction, connection
from pgvector.django import VectorField, HnswIndex, CosineDistance

class VectorDocument(models.Model):
    tenant_id = models.PositiveIntegerField(db_index=True)
    embedding = VectorField(dimensions=3)

    class Meta:
        app_label = "notes_demo"
        indexes = [HnswIndex(
            name="demo_vector_hnsw", fields=["embedding"],
            opclasses=["vector_cosine_ops"])]


def nearest(authorized_tenant_id, query_vector, limit=5):
    # Small synthetic vectors for the functional test.
    if len(query_vector) != 3 or not any(query_vector):
        raise ValueError("non-zero three-dimensional vector required")
    if limit < 1:
        raise ValueError("positive limit required")
    with transaction.atomic():
        # Applies only in this transaction; requires pgvector 0.8.0 or later.
        with connection.cursor() as cursor:
            cursor.execute("SET LOCAL hnsw.iterative_scan = strict_order")
        return list(VectorDocument.objects.filter(
            tenant_id=authorized_tenant_id
        ).order_by(CosineDistance("embedding", query_vector))[:limit])

What the local test proves

The test uses an isolated PostgreSQL 16 container with pgvector 0.8.6, Django 5.2 and synthetic data. It creates the extension, table and HNSW index, checks the tenant-scoped result and compares SQL from both ORM chains. An additional plan check forces HNSW only for the fixture and checks iterative search output. This is a functional test, not a recall or load benchmark.

Check the plan, then choose the architecture

Compare approximate results with an exact reference search on a representative test corpus. Iterative scans remain bounded by search and memory limits; they do not guarantee complete recall. A B-tree on the filter column, a partial index or partitioning may help depending on data distribution. Many partial indexes increase operational work.

A separate vector database adds synchronisation, permission logic and recovery work. Decide using your data and measurements rather than a universal document-count threshold. Version the embedding model and dimensions when they change; this example does not automatically generate embeddings on save.