0
# pgvector
1

2
PostgreSQL pgvector extension support for Python, enabling high-performance vector operations and similarity search in PostgreSQL databases. pgvector provides comprehensive integration with major Python database libraries including Django, SQLAlchemy, SQLModel, Psycopg 3, Psycopg 2, asyncpg, pg8000, and Peewee.
3

4
## Package Information
5

6
- **Package Name**: pgvector
7
- **Language**: Python
8
- **Installation**: `pip install pgvector`
9
- **Dependencies**: `numpy` (required)
10

11
## Core Imports
12

13
```python
14
from pgvector import Vector, HalfVector, SparseVector, Bit
15
```
16

17
Framework-specific imports:
18

19
```python
20
# Django integration
21
from pgvector.django import VectorField, HalfVectorField, SparseVectorField, BitField
22
from pgvector.django import L2Distance, CosineDistance, MaxInnerProduct, L1Distance
23
from pgvector.django import HammingDistance, JaccardDistance, IvfflatIndex, HnswIndex
24

25
# SQLAlchemy integration  
26
from pgvector.sqlalchemy import VECTOR, HALFVEC, SPARSEVEC, BIT
27
from pgvector.sqlalchemy import avg, sum
28

29
# Database drivers
30
from pgvector.psycopg import register_vector, register_vector_async
31
from pgvector.psycopg2 import register_vector
32
from pgvector.asyncpg import register_vector
33
```
34

35
## Basic Usage
36

37
```python
38
import numpy as np
39
from pgvector import Vector, HalfVector, SparseVector, Bit
40

41
# Create standard vectors (32-bit float)
42
vector = Vector([1.5, 2.0, 3.5])
43
vector_from_numpy = Vector(np.array([1, 2, 3], dtype=np.float32))
44

45
# Create half-precision vectors (16-bit float) for memory efficiency
46
half_vector = HalfVector([1.5, 2.0, 3.5])
47

48
# Create sparse vectors for high-dimensional data with many zeros
49
sparse_vector = SparseVector({0: 1.0, 100: 2.5, 500: 3.0}, 1000)
50
sparse_from_dense = SparseVector([1.0, 0.0, 0.0, 2.5])
51

52
# Create bit vectors for binary operations
53
bit_vector = Bit([True, False, True, False])
54
bit_from_string = Bit("1010")
55

56
# Convert between formats
57
dense_list = vector.to_list()  # [1.5, 2.0, 3.5]
58
numpy_array = vector.to_numpy()  # numpy array
59
dimensions = vector.dimensions()  # 3
60

61
# Database serialization
62
text_format = vector.to_text()  # PostgreSQL text format
63
binary_format = vector.to_binary()  # PostgreSQL binary format
64
```
65

66
## Architecture
67

68
pgvector's architecture is built around four core vector types and comprehensive database integration:
69

70
- **Core Vector Types**: Vector (float32), HalfVector (float16), SparseVector (sparse), and Bit (binary) classes provide the foundation for all vector operations
71
- **Database Integrations**: Framework-specific modules provide native field types, distance functions, and indexing support for each major Python database library
72
- **Driver Registration**: Database driver modules handle PostgreSQL type registration and serialization for raw database connections
73
- **Distance Operations**: Built-in support for L2 (Euclidean), cosine, inner product, L1 (Manhattan), Hamming, and Jaccard distance calculations
74

75
This design enables seamless vector operations across the entire Python database ecosystem while maintaining high performance through PostgreSQL's native pgvector extension.
76

77
## Capabilities
78

79
### Core Vector Types
80

81
The foundation of pgvector providing four distinct vector types optimized for different use cases: standard precision vectors, memory-efficient half vectors, sparse vectors for high-dimensional data, and binary vectors for bit operations.
82

83
```python { .api }
84
class Vector:
85
    def __init__(self, value): ...
86
    def dimensions(self) -> int: ...
87
    def to_list(self) -> list: ...
88
    def to_numpy(self) -> np.ndarray: ...
89

90
class HalfVector:
91
    def __init__(self, value): ...
92
    def dimensions(self) -> int: ...
93
    def to_list(self) -> list: ...
94

95
class SparseVector:
96
    def __init__(self, value, dimensions=None): ...
97
    def dimensions(self) -> int: ...
98
    def indices(self) -> list: ...
99
    def values(self) -> list: ...
100

101
class Bit:
102
    def __init__(self, value): ...
103
    def to_list(self) -> list: ...
104
    def to_numpy(self) -> np.ndarray: ...
105
```
106

107
[Core Vector Types](./core-vectors.md)
108

109
### Django Integration
110

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

113
```python { .api }
114
class VectorField(Field): ...
115
class HalfVectorField(Field): ...
116
class SparseVectorField(Field): ...
117
class BitField(Field): ...
118

119
class L2Distance(Func): ...
120
class CosineDistance(Func): ...
121
class HnswIndex(Index): ...
122
class IvfflatIndex(Index): ...
123
```
124

125
[Django Integration](./django-integration.md)
126

127
### SQLAlchemy Integration
128

129
Native SQLAlchemy types and functions providing full vector support for SQLAlchemy applications with type safety and query builder integration.
130

131
```python { .api }
132
class VECTOR(TypeDecorator): ...
133
class HALFVEC(TypeDecorator): ...
134
class SPARSEVEC(TypeDecorator): ...
135
class BIT(TypeDecorator): ...
136

137
def avg(*args): ...
138
def sum(*args): ...
139
```
140

141
[SQLAlchemy Integration](./sqlalchemy-integration.md)
142

143
### Database Driver Support
144

145
Direct database driver integration for applications using raw PostgreSQL connections, providing vector type registration and serialization across all major Python PostgreSQL drivers.
146

147
```python { .api }
148
# Psycopg 3
149
def register_vector(context): ...
150
def register_vector_async(context): ...
151

152
# Psycopg 2, asyncpg, pg8000
153
def register_vector(connection): ...
154
```
155

156
[Database Drivers](./database-drivers.md)
157

158
### Peewee Integration
159

160
Peewee ORM field types for vector operations in Peewee-based applications with full vector type support and query integration.
161

162
```python { .api }
163
class VectorField(Field): ...
164
class HalfVectorField(Field): ...
165
class SparseVectorField(Field): ...
166
class FixedBitField(Field): ...
167
```
168

169
[Peewee Integration](./peewee-integration.md)