or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-vectors.mddatabase-drivers.mddjango-integration.mdindex.mdpeewee-integration.mdsqlalchemy-integration.md
tile.json

tessl/pypi-pgvector

PostgreSQL pgvector extension support for Python with vector operations and similarity search across multiple database libraries

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pgvector@0.4.x

To install, run

npx @tessl/cli install tessl/pypi-pgvector@0.4.0

index.mddocs/

pgvector

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.

Package Information

  • Package Name: pgvector
  • Language: Python
  • Installation: pip install pgvector
  • Dependencies: numpy (required)

Core Imports

from pgvector import Vector, HalfVector, SparseVector, Bit

Framework-specific imports:

# Django integration
from pgvector.django import VectorField, HalfVectorField, SparseVectorField, BitField
from pgvector.django import L2Distance, CosineDistance, MaxInnerProduct, L1Distance
from pgvector.django import HammingDistance, JaccardDistance, IvfflatIndex, HnswIndex

# SQLAlchemy integration  
from pgvector.sqlalchemy import VECTOR, HALFVEC, SPARSEVEC, BIT
from pgvector.sqlalchemy import avg, sum

# Database drivers
from pgvector.psycopg import register_vector, register_vector_async
from pgvector.psycopg2 import register_vector
from pgvector.asyncpg import register_vector

Basic Usage

import numpy as np
from pgvector import Vector, HalfVector, SparseVector, Bit

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

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

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

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

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

# Database serialization
text_format = vector.to_text()  # PostgreSQL text format
binary_format = vector.to_binary()  # PostgreSQL binary format

Architecture

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

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

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

Capabilities

Core Vector Types

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.

class Vector:
    def __init__(self, value): ...
    def dimensions(self) -> int: ...
    def to_list(self) -> list: ...
    def to_numpy(self) -> np.ndarray: ...

class HalfVector:
    def __init__(self, value): ...
    def dimensions(self) -> int: ...
    def to_list(self) -> list: ...

class SparseVector:
    def __init__(self, value, dimensions=None): ...
    def dimensions(self) -> int: ...
    def indices(self) -> list: ...
    def values(self) -> list: ...

class Bit:
    def __init__(self, value): ...
    def to_list(self) -> list: ...
    def to_numpy(self) -> np.ndarray: ...

Core Vector Types

Django Integration

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

class VectorField(Field): ...
class HalfVectorField(Field): ...
class SparseVectorField(Field): ...
class BitField(Field): ...

class L2Distance(Func): ...
class CosineDistance(Func): ...
class HnswIndex(Index): ...
class IvfflatIndex(Index): ...

Django Integration

SQLAlchemy Integration

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

class VECTOR(TypeDecorator): ...
class HALFVEC(TypeDecorator): ...
class SPARSEVEC(TypeDecorator): ...
class BIT(TypeDecorator): ...

def avg(*args): ...
def sum(*args): ...

SQLAlchemy Integration

Database Driver Support

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

# Psycopg 3
def register_vector(context): ...
def register_vector_async(context): ...

# Psycopg 2, asyncpg, pg8000
def register_vector(connection): ...

Database Drivers

Peewee Integration

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

class VectorField(Field): ...
class HalfVectorField(Field): ...
class SparseVectorField(Field): ...
class FixedBitField(Field): ...

Peewee Integration