milvusql-django

A Django database backend for Milvus, built on the milvusql DBAPI.

📚 Documentation · PyPI · milvusql

Model/Field CRUD and filtering go through Django's normal query compiler; vector search goes through an explicit helper instead of a queryset method, because Milvus needs an index built and the collection loaded before a vector column is searchable at all — see API below. Relation lookups (filter(related__field=...)), .values().annotate(...) grouping and Exists(... OuterRef(...)) (correlated EXISTS, decorrelated into a semi/anti join) all plan through the DBAPI's relational engine, and a TextField is Milvus's analyzer-enabled full-text input.

Installation

pip install milvusql-django

Quick start

# settings.py
DATABASES = {
    "default": {
        "ENGINE": "milvusql_django",
        "NAME": "/path/to/items.db",  # or HOST/PORT/USER/PASSWORD for a real server
    }
}

# models.py
from django.db import models
from milvusql_django.fields import VectorField

class Item(models.Model):
    embedding = VectorField(dim=768)
    category = models.CharField(max_length=64)

# after migrating: build the index and load the collection once
from django.db import connection
from milvusql_django.schema import create_index_and_load

create_index_and_load(
    connection, "myapp_item", "embedding",
    using="HNSW", metric_type="COSINE",
)

# CRUD/filtering: the normal ORM
Item.objects.filter(category="book").values("id")

# vector search: a raw SQL escape hatch, not a queryset method
with connection.cursor() as cursor:
    cursor.execute(
        'SELECT id FROM "myapp_item" ORDER BY embedding <=> %s LIMIT 5',
        [[0.1] * 768],
    )
    rows = cursor.fetchall()

API

VectorField

A standard Django Field, not a fake-column shim — round-trips list[float] <-> VECTOR(n):

from milvusql_django.fields import VectorField

class Item(models.Model):
    embedding = VectorField(dim=768)   # dim is optional; omit for an unconstrained VECTOR

milvusql_django.schema.create_index_and_load()

create_index_and_load(
    connection,          # a Django database connection
    table,                # collection/table name
    field_name,            # the VectorField's column
    *,
    using="HNSW",
    metric_type="COSINE",
    **index_params,        # e.g. M=16, ef_construction=200
)

The explicit follow-up step CreateModel deliberately doesn't do automatically — index method/metric is a query-shape decision (HNSW vs. IVF, COSINE vs. L2), not something a generic schema migration should guess. Call it once, after defining the model, before querying it.

Schema & migrations

This is a first cut, not full Django migration parity:

See Schema & Migrations for the full picture.

Development

From the workspace root (requires Python 3.12+, uv, task):

task install
task django:lint
task django:test    # integration tests need Docker (testcontainers)

License

MIT