django / django/new-features

Add pgvector-backed VectorField for PostgreSQL (initially in django.contrib.postgres), with a path to a cross-database core API

Open
#145 6 comments 8 reactions 0 assignees View on GitHub
Django Core Models/ORM Third Party Package
Dominant language
No language data
Stars
188
Forks
7
PR merge metrics
No merged PRs in 30d

Description

### Code of Conduct

- [x] I agree to follow Django's Code of Conduct

### Feature Description

I propose adding first-class support for storing and querying vector embeddings in Django when using PostgreSQL via the `pgvector` extension.

This proposal is intentionally PostgreSQL-focused as an initial step (implemented in `django.contrib.postgres`), with a clear path to evolve into a cross-database `VectorField` in `django.db.models` if/when additional database backends (e.g. at least 1–2 more) can be supported with comparable behavior.

**Related proposal:** This topic overlaps with the Oracle-specific proposal for a native vector type:
- https://github.com/django/new-features/issues/60

I opened this issue because #60 explicitly targets Oracle. This proposal instead targets PostgreSQL + `pgvector`, which is already widely used in production for embeddings/similarity search.

### Problem

Today, Django does not ship an official VectorField for embeddings. In practice, many projects rely on:
- raw SQL,
- ad-hoc custom fields,
- third-party integrations.

This makes vector storage and similarity search harder to standardize across projects and complicates migrations, validation, portability, and ORM-level query composition.

Meanwhile, embeddings have become a common building block (semantic search, RAG, recommendations, clustering). Many teams would benefit from a stable, Django-native API to store/query vectors “out-of-the-box”.

### Request or proposal

proposal

### Additional Details

### Proposed scope (MVP in PostgreSQL)

**1) `VectorField` in `django.contrib.postgres`**
- Backed by PostgreSQL `pgvector` extension
- Stores dense float vectors (the common embeddings case)
- Optional `dimensions` parameter (recommended), with validation
- Python-level value handling compatible with `psycopg` (psycopg3)

**2) ORM functions / expressions**
- Distance computation expressions (at least cosine and L2)
- Ordering by distance (nearest neighbors)
- Filtering based on distance thresholds

**3) Index support**
- Define an index class (or documented integration) for ANN indexes supported by pgvector (e.g. HNSW / IVF) where feasible.

### Reference implementation (existing ecosystem)

There is already a mature Python ecosystem around Postgres vectors:
- PostgreSQL extension: `pgvector` See https://github.com/pgvector/pgvector
- Python adapters + Django integration exist and are used in production (e.g. the `pgvector` Python package includes Django support) See https://github.com/pgvector/pgvector-python

I have personally used this solution multiple times in real projects and presented it in talks. The approach is solid and proven.

### Why `django.contrib.postgres` first, and a migration path to core later

Starting in `django.contrib.postgres`:
- allows database-specific behavior to live in the Postgres contrib area,
- reduces risk of locking a premature cross-database API into `django.db.models`,
- matches how Django has historically introduced DB-specific capabilities before converging on core APIs where appropriate.

If the community wants a cross-database `VectorField` eventually, we can define a path similar to how Django evolved other features (e.g. JSONField and other database-driven features): start with a PostgreSQL-backed implementation, then move/alias to `django.db.models` once other backends can provide compatible behavior.

If there are contributors who already know how to support vectors on at least one or two additional backends, I’m open to designing it directly at the ORM/core level from the start.

### Context / timing (DjangoCon Europe 2026)

I’m attending DjangoCon Europe 2026 in Athens. In multiple conversations during the conference and sprints, the idea of adding vector field support in Django came up repeatedly.

A concrete target would be to aim for Django 6.2 (subject to consensus and contributor availability) so that the community can rely on a stable Django release that supports embeddings out-of-the-box (at least for PostgreSQL/pgvector).

### Questions for the community / Steering Council

1. Is a PostgreSQL-only initial implementation in `django.contrib.postgres` the right first step?
2. What should the minimal core API be (field signature, validation, lookups/expressions)?
3. Should we treat vector indexing as part of the MVP, or follow in a later iteration?
4. Do we have volunteers to help define a cross-database design (Oracle, PostgreSQL, and possibly others) so we can converge towards `django.db.models`?

### Additional Details

Happy to:
- summarize existing third-party behavior and propose a Django-native API surface,
- draft an implementation plan and a test matrix,
- coordinate discussions and keep periodic summaries as the thread grows.

### Implementation Suggestions

_No response_

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.