0
# Django Integration
1

2
Complete Django ORM support providing vector field types, distance functions, and indexing capabilities for building vector-powered Django applications with familiar ORM patterns.
3

4
## Capabilities
5

6
### Vector Field Types
7

8
Django model fields for storing different vector types in PostgreSQL with pgvector extension.
9

10
```python { .api }
11
class VectorField(Field):
12
    """
13
    Django field for storing Vector (float32) data.
14
    
15
    Args:
16
        dimensions (int, optional): Fixed number of dimensions
17
        **kwargs: Standard Django field parameters
18
    """
19

20
class HalfVectorField(Field):
21
    """
22
    Django field for storing HalfVector (float16) data.
23
    
24
    Args:
25
        dimensions (int, optional): Fixed number of dimensions  
26
        **kwargs: Standard Django field parameters
27
    """
28

29
class SparseVectorField(Field):
30
    """
31
    Django field for storing SparseVector data.
32
    
33
    Args:
34
        dimensions (int, optional): Fixed number of dimensions
35
        **kwargs: Standard Django field parameters
36
    """
37

38
class BitField(Field):
39
    """
40
    Django field for storing Bit vector data.
41
    
42
    Args:
43
        **kwargs: Standard Django field parameters
44
    """
45
```
46

47
**Usage Examples:**
48

49
```python
50
from django.db import models
51
from pgvector.django import VectorField, HalfVectorField, SparseVectorField, BitField
52

53
class Document(models.Model):
54
    content = models.TextField()
55
    embedding = VectorField(dimensions=1536)  # OpenAI embeddings
56
    title_embedding = HalfVectorField(dimensions=768)  # Memory efficient
57
    sparse_features = SparseVectorField(dimensions=10000)  # High-dimensional sparse
58
    binary_hash = BitField()  # Binary features
59
    
60
    class Meta:
61
        db_table = 'documents'
62

63
# Create model instances
64
from pgvector import Vector, HalfVector, SparseVector, Bit
65

66
doc = Document(
67
    content="Sample document",
68
    embedding=Vector([0.1, 0.2, 0.3] * 512),  # 1536 dimensions
69
    title_embedding=HalfVector([0.5, 0.6, 0.7] * 256),  # 768 dimensions
70
    sparse_features=SparseVector({0: 1.0, 500: 2.5}, 10000),
71
    binary_hash=Bit("1010110")
72
)
73
doc.save()
74
```
75

76
### Distance Functions
77

78
Django ORM functions for calculating vector similarities and distances in database queries.
79

80
```python { .api }
81
class L2Distance(Func):
82
    """
83
    Euclidean (L2) distance function.
84
    
85
    Args:
86
        expression: Model field or expression
87
        vector: Vector, HalfVector, SparseVector, or Value
88
        **kwargs: Additional function parameters
89
    """
90

91
class CosineDistance(Func):
92
    """
93
    Cosine distance function (1 - cosine similarity).
94
    
95
    Args:
96
        expression: Model field or expression
97
        vector: Vector, HalfVector, SparseVector, or Value
98
        **kwargs: Additional function parameters
99
    """
100

101
class MaxInnerProduct(Func):
102
    """
103
    Maximum inner product (negative inner product) function.
104
    
105
    Args:
106
        expression: Model field or expression  
107
        vector: Vector, HalfVector, SparseVector, or Value
108
        **kwargs: Additional function parameters
109
    """
110

111
class L1Distance(Func):
112
    """
113
    Manhattan (L1) distance function.
114
    
115
    Args:
116
        expression: Model field or expression
117
        vector: Vector, HalfVector, SparseVector, or Value
118
        **kwargs: Additional function parameters
119
    """
120

121
class HammingDistance(Func):
122
    """
123
    Hamming distance function for bit vectors.
124
    
125
    Args:
126
        expression: Model field or expression
127
        vector: Bit vector or binary string
128
        **kwargs: Additional function parameters
129
    """
130

131
class JaccardDistance(Func):
132
    """
133
    Jaccard distance function for bit vectors.
134
    
135
    Args:
136
        expression: Model field or expression
137
        vector: Bit vector or binary string
138
        **kwargs: Additional function parameters
139
    """
140
```
141

142
**Usage Examples:**
143

144
```python
145
from django.db.models import F
146
from pgvector.django import L2Distance, CosineDistance, MaxInnerProduct, HammingDistance
147
from pgvector import Vector, Bit
148

149
# Find documents similar to query vector
150
query_vector = Vector([0.1, 0.2, 0.3] * 512)
151

152
# L2 (Euclidean) distance search
153
similar_docs = Document.objects.annotate(
154
    distance=L2Distance('embedding', query_vector)
155
).order_by('distance')[:10]
156

157
# Cosine similarity search (lower cosine distance = higher similarity)
158
cosine_similar = Document.objects.annotate(
159
    cosine_dist=CosineDistance('embedding', query_vector)
160
).order_by('cosine_dist')[:10]
161

162
# Maximum inner product search
163
inner_product_similar = Document.objects.annotate(
164
    inner_product=MaxInnerProduct('embedding', query_vector)
165
).order_by('inner_product')[:10]
166

167
# Hamming distance for binary vectors
168
query_bits = Bit("1010110")
169
binary_similar = Document.objects.annotate(
170
    hamming_dist=HammingDistance('binary_hash', query_bits)
171
).order_by('hamming_dist')[:10]
172

173
# Filter by distance threshold
174
close_docs = Document.objects.filter(
175
    L2Distance('embedding', query_vector) < 0.5
176
)
177
```
178

179
### Index Types
180

181
Django index classes for optimizing vector similarity searches with approximate nearest neighbor algorithms.
182

183
```python { .api }
184
class IvfflatIndex(Index):
185
    """
186
    IVFFlat index for approximate nearest neighbor search.
187
    
188
    Args:
189
        fields: List of field names to index
190
        lists (int, optional): Number of inverted lists (default: computed)
191
        **kwargs: Standard Django index parameters
192
    """
193

194
class HnswIndex(Index):
195
    """
196
    HNSW (Hierarchical Navigable Small World) index for approximate nearest neighbor search.
197
    
198
    Args:
199
        fields: List of field names to index
200
        m (int, optional): Maximum connections per node (default: 16)
201
        ef_construction (int, optional): Size of candidate list during construction (default: 64)
202
        **kwargs: Standard Django index parameters
203
    """
204
```
205

206
**Usage Examples:**
207

208
```python
209
from django.db import models
210
from pgvector.django import VectorField, HnswIndex, IvfflatIndex
211

212
class Document(models.Model):
213
    content = models.TextField()
214
    embedding = VectorField(dimensions=1536)
215
    
216
    class Meta:
217
        # Add vector indexes for performance
218
        indexes = [
219
            # HNSW index for high recall approximate search
220
            HnswIndex(
221
                fields=['embedding'],
222
                name='embedding_hnsw_idx',
223
                m=16,  # connections per node
224
                ef_construction=64  # build-time search quality
225
            ),
226
            
227
            # IVFFlat index for faster build times
228
            IvfflatIndex(
229
                fields=['embedding'],
230
                name='embedding_ivfflat_idx',
231
                lists=100  # number of clusters
232
            )
233
        ]
234

235
# Indexes are automatically used by the query planner for distance searches
236
similar = Document.objects.annotate(
237
    distance=L2Distance('embedding', query_vector)
238
).order_by('distance')[:10]  # Uses index automatically
239
```
240

241
### Database Extension
242

243
Django database extension registration for pgvector functionality.
244

245
```python { .api }
246
class VectorExtension:
247
    """
248
    Django database extension for pgvector.
249
    Handles PostgreSQL extension installation and configuration.
250
    """
251
```
252

253
**Usage Examples:**
254

255
```python
256
# In Django settings.py
257
DATABASES = {
258
    'default': {
259
        'ENGINE': 'django.db.backends.postgresql',
260
        'NAME': 'your_db',
261
        # ... other settings
262
    }
263
}
264

265
# Create and run migration to enable extension
266
# python manage.py makemigrations --empty your_app_name
267

268
# In the generated migration file:
269
from django.contrib.postgres.operations import CreateExtension
270

271
class Migration(migrations.Migration):
272
    dependencies = [
273
        ('your_app', '0001_initial'),
274
    ]
275

276
    operations = [
277
        CreateExtension('vector'),  # Enable pgvector extension
278
    ]
279
```
280

281
## Complete Django Example
282

283
```python
284
# models.py
285
from django.db import models
286
from pgvector.django import VectorField, HnswIndex
287

288
class EmbeddingModel(models.Model):
289
    text = models.TextField()
290
    embedding = VectorField(dimensions=384)  # sentence-transformers dimension
291
    created_at = models.DateTimeField(auto_now_add=True)
292
    
293
    class Meta:
294
        indexes = [
295
            HnswIndex(fields=['embedding'], name='embedding_hnsw_idx')
296
        ]
297

298
# views.py
299
from django.http import JsonResponse
300
from pgvector.django import L2Distance
301
from pgvector import Vector
302

303
def similarity_search(request):
304
    query_embedding = Vector([0.1, 0.2] * 192)  # 384 dimensions
305
    
306
    # Find top 10 most similar embeddings
307
    results = EmbeddingModel.objects.annotate(
308
        distance=L2Distance('embedding', query_embedding)
309
    ).order_by('distance')[:10]
310
    
311
    return JsonResponse([{
312
        'text': item.text,
313
        'distance': float(item.distance),
314
        'created_at': item.created_at.isoformat()
315
    } for item in results], safe=False)
316
```