pgvector 0.3.6__tar.gz → 0.4.0__tar.gz

{pgvector-0.3.6 → pgvector-0.4.0}/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021-2024 Andrew Kane
+Copyright (c) 2021-2025 Andrew Kane
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{pgvector-0.3.6 → pgvector-0.4.0}/PKG-INFO

@@ -1,11 +1,11 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: pgvector
-Version: 0.3.6
+Version: 0.4.0
 Summary: pgvector support for Python
 Author-email: Andrew Kane <andrew@ankane.org>
 License: MIT
 Project-URL: Homepage, https://github.com/pgvector/pgvector-python
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Requires-Dist: numpy
@@ -14,7 +14,7 @@ Requires-Dist: numpy
 
 [pgvector](https://github.com/pgvector/pgvector) support for Python
 
-Supports [Django](https://github.com/django/django), [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy), [SQLModel](https://github.com/tiangolo/sqlmodel), [Psycopg 3](https://github.com/psycopg/psycopg), [Psycopg 2](https://github.com/psycopg/psycopg2), [asyncpg](https://github.com/MagicStack/asyncpg), and [Peewee](https://github.com/coleifer/peewee)
+Supports [Django](https://github.com/django/django), [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy), [SQLModel](https://github.com/tiangolo/sqlmodel), [Psycopg 3](https://github.com/psycopg/psycopg), [Psycopg 2](https://github.com/psycopg/psycopg2), [asyncpg](https://github.com/MagicStack/asyncpg), [pg8000](https://github.com/tlocke/pg8000), and [Peewee](https://github.com/coleifer/peewee)
 
 [![Build Status](https://github.com/pgvector/pgvector-python/actions/workflows/build.yml/badge.svg)](https://github.com/pgvector/pgvector-python/actions)
 
@@ -34,6 +34,7 @@ And follow the instructions for your database library:
 - [Psycopg 3](#psycopg-3)
 - [Psycopg 2](#psycopg-2)
 - [asyncpg](#asyncpg)
+- [pg8000](#pg8000)
 - [Peewee](#peewee)
 
 Or check out some examples:
@@ -45,6 +46,7 @@ Or check out some examples:
 - [Hybrid search](https://github.com/pgvector/pgvector-python/blob/master/examples/hybrid_search/cross_encoder.py) with SentenceTransformers (cross-encoder)
 - [Sparse search](https://github.com/pgvector/pgvector-python/blob/master/examples/sparse_search/example.py) with Transformers
 - [Late interaction search](https://github.com/pgvector/pgvector-python/blob/master/examples/colbert/exact.py) with ColBERT
+- [Visual document retrieval](https://github.com/pgvector/pgvector-python/blob/master/examples/colpali/exact.py) with ColPali
 - [Image search](https://github.com/pgvector/pgvector-python/blob/master/examples/image_search/example.py) with PyTorch
 - [Image search](https://github.com/pgvector/pgvector-python/blob/master/examples/imagehash/example.py) with perceptual hashing
 - [Morgan fingerprints](https://github.com/pgvector/pgvector-python/blob/master/examples/rdkit/example.py) with RDKit
@@ -145,6 +147,36 @@ class Item(models.Model):
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+#### Half-Precision Indexing
+
+Index vectors at half-precision
+
+```python
+from django.contrib.postgres.indexes import OpClass
+from django.db.models.functions import Cast
+from pgvector.django import HnswIndex, HalfVectorField
+
+class Item(models.Model):
+    class Meta:
+        indexes = [
+            HnswIndex(
+                OpClass(Cast('embedding', HalfVectorField(dimensions=3)), name='halfvec_l2_ops'),
+                name='my_index',
+                m=16,
+                ef_construction=64
+            )
+        ]
+```
+
+Note: Add `'django.contrib.postgres'` to `INSTALLED_APPS` to use `OpClass`
+
+Get the nearest neighbors
+
+```python
+distance = L2Distance(Cast('embedding', HalfVectorField(dimensions=3)), [3, 1, 2])
+Item.objects.order_by(distance)[:5]
+```
+
 ## SQLAlchemy
 
 Enable the extension
@@ -226,6 +258,77 @@ index.create(engine)
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+#### Half-Precision Indexing
+
+Index vectors at half-precision
+
+```python
+from pgvector.sqlalchemy import HALFVEC
+from sqlalchemy.sql import func
+
+index = Index(
+    'my_index',
+    func.cast(Item.embedding, HALFVEC(3)).label('embedding'),
+    postgresql_using='hnsw',
+    postgresql_with={'m': 16, 'ef_construction': 64},
+    postgresql_ops={'embedding': 'halfvec_l2_ops'}
+)
+```
+
+Get the nearest neighbors
+
+```python
+order = func.cast(Item.embedding, HALFVEC(3)).l2_distance([3, 1, 2])
+session.scalars(select(Item).order_by(order).limit(5))
+```
+
+#### Arrays
+
+Add an array column
+
+```python
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import ARRAY
+
+class Item(Base):
+    embeddings = mapped_column(ARRAY(Vector(3)))
+```
+
+And register the types with the underlying driver
+
+For Psycopg 3, use
+
+```python
+from pgvector.psycopg import register_vector
+from sqlalchemy import event
+
+@event.listens_for(engine, "connect")
+def connect(dbapi_connection, connection_record):
+    register_vector(dbapi_connection)
+```
+
+For [async connections](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html) with Psycopg 3, use
+
+```python
+from pgvector.psycopg import register_vector_async
+from sqlalchemy import event
+
+@event.listens_for(engine.sync_engine, "connect")
+def connect(dbapi_connection, connection_record):
+    dbapi_connection.run_async(register_vector_async)
+```
+
+For Psycopg 2, use
+
+```python
+from pgvector.psycopg2 import register_vector
+from sqlalchemy import event
+
+@event.listens_for(engine, "connect")
+def connect(dbapi_connection, connection_record):
+    register_vector(dbapi_connection, arrays=True)
+```
+
 ## SQLModel
 
 Enable the extension
@@ -238,10 +341,9 @@ Add a vector column
 
 ```python
 from pgvector.sqlalchemy import Vector
-from sqlalchemy import Column
 
 class Item(SQLModel, table=True):
-    embedding: Any = Field(sa_column=Column(Vector(3)))
+    embedding: Any = Field(sa_type=Vector(3))
 ```
 
 Also supports `HALFVEC`, `BIT`, and `SPARSEVEC`
@@ -287,7 +389,7 @@ Also supports `sum`
 Add an approximate index
 
 ```python
-from sqlalchemy import Index
+from sqlmodel import Index
 
 index = Index(
     'my_index',
@@ -326,6 +428,15 @@ from pgvector.psycopg import register_vector
 register_vector(conn)
 ```
 
+For [connection pools](https://www.psycopg.org/psycopg3/docs/advanced/pool.html), use
+
+```python
+def configure(conn):
+    register_vector(conn)
+
+pool = ConnectionPool(..., configure=configure)
+```
+
 For [async connections](https://www.psycopg.org/psycopg3/docs/advanced/async.html), use
 
 ```python
@@ -464,6 +575,51 @@ await conn.execute('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+## pg8000
+
+Enable the extension
+
+```python
+conn.run('CREATE EXTENSION IF NOT EXISTS vector')
+```
+
+Register the vector type with your connection
+
+```python
+from pgvector.pg8000 import register_vector
+
+register_vector(conn)
+```
+
+Create a table
+
+```python
+conn.run('CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))')
+```
+
+Insert a vector
+
+```python
+embedding = np.array([1, 2, 3])
+conn.run('INSERT INTO items (embedding) VALUES (:embedding)', embedding=embedding)
+```
+
+Get the nearest neighbors to a vector
+
+```python
+conn.run('SELECT * FROM items ORDER BY embedding <-> :embedding LIMIT 5', embedding=embedding)
+```
+
+Add an approximate index
+
+```python
+conn.run('CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)')
+# or
+conn.run('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)')
+```
+
+Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
+
 ## Peewee
 
 Add a vector column
@@ -521,6 +677,99 @@ Item.add_index('embedding vector_l2_ops', using='hnsw')
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+## Reference
+
+### Half Vectors
+
+Create a half vector from a list
+
+```python
+vec = HalfVector([1, 2, 3])
+```
+
+Or a NumPy array
+
+```python
+vec = HalfVector(np.array([1, 2, 3]))
+```
+
+Get a list
+
+```python
+lst = vec.to_list()
+```
+
+Get a NumPy array
+
+```python
+arr = vec.to_numpy()
+```
+
+### Sparse Vectors
+
+Create a sparse vector from a list
+
+```python
+vec = SparseVector([1, 0, 2, 0, 3, 0])
+```
+
+Or a NumPy array
+
+```python
+vec = SparseVector(np.array([1, 0, 2, 0, 3, 0]))
+```
+
+Or a SciPy sparse array
+
+```python
+arr = coo_array(([1, 2, 3], ([0, 2, 4],)), shape=(6,))
+vec = SparseVector(arr)
+```
+
+Or a dictionary of non-zero elements
+
+```python
+vec = SparseVector({0: 1, 2: 2, 4: 3}, 6)
+```
+
+Note: Indices start at 0
+
+Get the number of dimensions
+
+```python
+dim = vec.dimensions()
+```
+
+Get the indices of non-zero elements
+
+```python
+indices = vec.indices()
+```
+
+Get the values of non-zero elements
+
+```python
+values = vec.values()
+```
+
+Get a list
+
+```python
+lst = vec.to_list()
+```
+
+Get a NumPy array
+
+```python
+arr = vec.to_numpy()
+```
+
+Get a SciPy sparse array
+
+```python
+arr = vec.to_coo()
+```
+
 ## History
 
 View the [changelog](https://github.com/pgvector/pgvector-python/blob/master/CHANGELOG.md)

{pgvector-0.3.6 → pgvector-0.4.0}/README.md

@@ -2,7 +2,7 @@
 
 [pgvector](https://github.com/pgvector/pgvector) support for Python
 
-Supports [Django](https://github.com/django/django), [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy), [SQLModel](https://github.com/tiangolo/sqlmodel), [Psycopg 3](https://github.com/psycopg/psycopg), [Psycopg 2](https://github.com/psycopg/psycopg2), [asyncpg](https://github.com/MagicStack/asyncpg), and [Peewee](https://github.com/coleifer/peewee)
+Supports [Django](https://github.com/django/django), [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy), [SQLModel](https://github.com/tiangolo/sqlmodel), [Psycopg 3](https://github.com/psycopg/psycopg), [Psycopg 2](https://github.com/psycopg/psycopg2), [asyncpg](https://github.com/MagicStack/asyncpg), [pg8000](https://github.com/tlocke/pg8000), and [Peewee](https://github.com/coleifer/peewee)
 
 [![Build Status](https://github.com/pgvector/pgvector-python/actions/workflows/build.yml/badge.svg)](https://github.com/pgvector/pgvector-python/actions)
 
@@ -22,6 +22,7 @@ And follow the instructions for your database library:
 - [Psycopg 3](#psycopg-3)
 - [Psycopg 2](#psycopg-2)
 - [asyncpg](#asyncpg)
+- [pg8000](#pg8000)
 - [Peewee](#peewee)
 
 Or check out some examples:
@@ -33,6 +34,7 @@ Or check out some examples:
 - [Hybrid search](https://github.com/pgvector/pgvector-python/blob/master/examples/hybrid_search/cross_encoder.py) with SentenceTransformers (cross-encoder)
 - [Sparse search](https://github.com/pgvector/pgvector-python/blob/master/examples/sparse_search/example.py) with Transformers
 - [Late interaction search](https://github.com/pgvector/pgvector-python/blob/master/examples/colbert/exact.py) with ColBERT
+- [Visual document retrieval](https://github.com/pgvector/pgvector-python/blob/master/examples/colpali/exact.py) with ColPali
 - [Image search](https://github.com/pgvector/pgvector-python/blob/master/examples/image_search/example.py) with PyTorch
 - [Image search](https://github.com/pgvector/pgvector-python/blob/master/examples/imagehash/example.py) with perceptual hashing
 - [Morgan fingerprints](https://github.com/pgvector/pgvector-python/blob/master/examples/rdkit/example.py) with RDKit
@@ -133,6 +135,36 @@ class Item(models.Model):
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+#### Half-Precision Indexing
+
+Index vectors at half-precision
+
+```python
+from django.contrib.postgres.indexes import OpClass
+from django.db.models.functions import Cast
+from pgvector.django import HnswIndex, HalfVectorField
+
+class Item(models.Model):
+    class Meta:
+        indexes = [
+            HnswIndex(
+                OpClass(Cast('embedding', HalfVectorField(dimensions=3)), name='halfvec_l2_ops'),
+                name='my_index',
+                m=16,
+                ef_construction=64
+            )
+        ]
+```
+
+Note: Add `'django.contrib.postgres'` to `INSTALLED_APPS` to use `OpClass`
+
+Get the nearest neighbors
+
+```python
+distance = L2Distance(Cast('embedding', HalfVectorField(dimensions=3)), [3, 1, 2])
+Item.objects.order_by(distance)[:5]
+```
+
 ## SQLAlchemy
 
 Enable the extension
@@ -214,6 +246,77 @@ index.create(engine)
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+#### Half-Precision Indexing
+
+Index vectors at half-precision
+
+```python
+from pgvector.sqlalchemy import HALFVEC
+from sqlalchemy.sql import func
+
+index = Index(
+    'my_index',
+    func.cast(Item.embedding, HALFVEC(3)).label('embedding'),
+    postgresql_using='hnsw',
+    postgresql_with={'m': 16, 'ef_construction': 64},
+    postgresql_ops={'embedding': 'halfvec_l2_ops'}
+)
+```
+
+Get the nearest neighbors
+
+```python
+order = func.cast(Item.embedding, HALFVEC(3)).l2_distance([3, 1, 2])
+session.scalars(select(Item).order_by(order).limit(5))
+```
+
+#### Arrays
+
+Add an array column
+
+```python
+from pgvector.sqlalchemy import Vector
+from sqlalchemy import ARRAY
+
+class Item(Base):
+    embeddings = mapped_column(ARRAY(Vector(3)))
+```
+
+And register the types with the underlying driver
+
+For Psycopg 3, use
+
+```python
+from pgvector.psycopg import register_vector
+from sqlalchemy import event
+
+@event.listens_for(engine, "connect")
+def connect(dbapi_connection, connection_record):
+    register_vector(dbapi_connection)
+```
+
+For [async connections](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html) with Psycopg 3, use
+
+```python
+from pgvector.psycopg import register_vector_async
+from sqlalchemy import event
+
+@event.listens_for(engine.sync_engine, "connect")
+def connect(dbapi_connection, connection_record):
+    dbapi_connection.run_async(register_vector_async)
+```
+
+For Psycopg 2, use
+
+```python
+from pgvector.psycopg2 import register_vector
+from sqlalchemy import event
+
+@event.listens_for(engine, "connect")
+def connect(dbapi_connection, connection_record):
+    register_vector(dbapi_connection, arrays=True)
+```
+
 ## SQLModel
 
 Enable the extension
@@ -226,10 +329,9 @@ Add a vector column
 
 ```python
 from pgvector.sqlalchemy import Vector
-from sqlalchemy import Column
 
 class Item(SQLModel, table=True):
-    embedding: Any = Field(sa_column=Column(Vector(3)))
+    embedding: Any = Field(sa_type=Vector(3))
 ```
 
 Also supports `HALFVEC`, `BIT`, and `SPARSEVEC`
@@ -275,7 +377,7 @@ Also supports `sum`
 Add an approximate index
 
 ```python
-from sqlalchemy import Index
+from sqlmodel import Index
 
 index = Index(
     'my_index',
@@ -314,6 +416,15 @@ from pgvector.psycopg import register_vector
 register_vector(conn)
 ```
 
+For [connection pools](https://www.psycopg.org/psycopg3/docs/advanced/pool.html), use
+
+```python
+def configure(conn):
+    register_vector(conn)
+
+pool = ConnectionPool(..., configure=configure)
+```
+
 For [async connections](https://www.psycopg.org/psycopg3/docs/advanced/async.html), use
 
 ```python
@@ -452,6 +563,51 @@ await conn.execute('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+## pg8000
+
+Enable the extension
+
+```python
+conn.run('CREATE EXTENSION IF NOT EXISTS vector')
+```
+
+Register the vector type with your connection
+
+```python
+from pgvector.pg8000 import register_vector
+
+register_vector(conn)
+```
+
+Create a table
+
+```python
+conn.run('CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3))')
+```
+
+Insert a vector
+
+```python
+embedding = np.array([1, 2, 3])
+conn.run('INSERT INTO items (embedding) VALUES (:embedding)', embedding=embedding)
+```
+
+Get the nearest neighbors to a vector
+
+```python
+conn.run('SELECT * FROM items ORDER BY embedding <-> :embedding LIMIT 5', embedding=embedding)
+```
+
+Add an approximate index
+
+```python
+conn.run('CREATE INDEX ON items USING hnsw (embedding vector_l2_ops)')
+# or
+conn.run('CREATE INDEX ON items USING ivfflat (embedding vector_l2_ops) WITH (lists = 100)')
+```
+
+Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
+
 ## Peewee
 
 Add a vector column
@@ -509,6 +665,99 @@ Item.add_index('embedding vector_l2_ops', using='hnsw')
 
 Use `vector_ip_ops` for inner product and `vector_cosine_ops` for cosine distance
 
+## Reference
+
+### Half Vectors
+
+Create a half vector from a list
+
+```python
+vec = HalfVector([1, 2, 3])
+```
+
+Or a NumPy array
+
+```python
+vec = HalfVector(np.array([1, 2, 3]))
+```
+
+Get a list
+
+```python
+lst = vec.to_list()
+```
+
+Get a NumPy array
+
+```python
+arr = vec.to_numpy()
+```
+
+### Sparse Vectors
+
+Create a sparse vector from a list
+
+```python
+vec = SparseVector([1, 0, 2, 0, 3, 0])
+```
+
+Or a NumPy array
+
+```python
+vec = SparseVector(np.array([1, 0, 2, 0, 3, 0]))
+```
+
+Or a SciPy sparse array
+
+```python
+arr = coo_array(([1, 2, 3], ([0, 2, 4],)), shape=(6,))
+vec = SparseVector(arr)
+```
+
+Or a dictionary of non-zero elements
+
+```python
+vec = SparseVector({0: 1, 2: 2, 4: 3}, 6)
+```
+
+Note: Indices start at 0
+
+Get the number of dimensions
+
+```python
+dim = vec.dimensions()
+```
+
+Get the indices of non-zero elements
+
+```python
+indices = vec.indices()
+```
+
+Get the values of non-zero elements
+
+```python
+values = vec.values()
+```
+
+Get a list
+
+```python
+lst = vec.to_list()
+```
+
+Get a NumPy array
+
+```python
+arr = vec.to_numpy()
+```
+
+Get a SciPy sparse array
+
+```python
+arr = vec.to_coo()
+```
+
 ## History
 
 View the [changelog](https://github.com/pgvector/pgvector-python/blob/master/CHANGELOG.md)

{pgvector-0.3.6 → pgvector-0.4.0}/pgvector/asyncpg/__init__.py

@@ -1,5 +1,7 @@
 from .register import register_vector
-from ..utils import Vector, HalfVector, SparseVector
+
+# TODO remove
+from .. import Vector, HalfVector, SparseVector
 
 __all__ = [
     'register_vector',

{pgvector-0.3.6 → pgvector-0.4.0}/pgvector/asyncpg/register.py

@@ -1,4 +1,4 @@
-from ..utils import Vector, HalfVector, SparseVector
+from .. import Vector, HalfVector, SparseVector
 
 
 async def register_vector(conn, schema='public'):