{"id":19747978,"url":"https://github.com/tensorchord/pgvecto.rs-py","last_synced_at":"2025-09-23T21:55:00.078Z","repository":{"id":241703768,"uuid":"806435484","full_name":"tensorchord/pgvecto.rs-py","owner":"tensorchord","description":"PGVecto.rs Python library","archived":false,"fork":false,"pushed_at":"2024-10-08T02:00:25.000Z","size":74,"stargazers_count":9,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-31T22:33:02.066Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tensorchord.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-05-27T07:39:56.000Z","updated_at":"2025-01-24T13:37:39.000Z","dependencies_parsed_at":"2025-01-10T21:21:39.941Z","dependency_job_id":null,"html_url":"https://github.com/tensorchord/pgvecto.rs-py","commit_stats":null,"previous_names":["tensorchord/pgvecto.rs-py"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensorchord%2Fpgvecto.rs-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensorchord%2Fpgvecto.rs-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensorchord%2Fpgvecto.rs-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tensorchord%2Fpgvecto.rs-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tensorchord","download_url":"https://codeload.github.com/tensorchord/pgvecto.rs-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745198,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-12T02:19:41.768Z","updated_at":"2025-09-23T21:54:55.015Z","avatar_url":"https://github.com/tensorchord.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PGVecto.rs support for Python\n\n\u003cp align=center\u003e\n\u003ca href=\"https://discord.gg/KqswhpVgdU\"\u003e\u003cimg alt=\"discord invitation link\" src=\"https://dcbadge.vercel.app/api/server/KqswhpVgdU?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"https://pdm.fming.dev\"\u003e\u003cimg src=\"https://img.shields.io/badge/pdm-managed-blueviolet\" alt=\"trackgit-views\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/pgvecto_rs/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pgvecto_rs\" alt=\"trackgit-views\" /\u003e\u003c/a\u003e\n\u003ca href=\"https://pypi.org/project/pgvecto_rs/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/pgvecto_rs.svg?label=Pypi%20downloads\" alt=\"trackgit-views\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n[PGVecto.rs](https://github.com/tensorchord/pgvecto.rs) Python library, supports Django, SQLAlchemy, and Psycopg 3.\n\n|                                                        | [Vector](https://docs.pgvecto.rs/usage/indexing.html) | [Sparse Vector](https://docs.pgvecto.rs/reference/vector-types/svector.html) | [Half-Precision Vector](https://docs.pgvecto.rs/reference/vector-types/vecf16.html) | [Binary Vector](https://docs.pgvecto.rs/reference/vector-types/bvector.html) |\n| ------------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| [SQLAlchemy](https://github.com/sqlalchemy/sqlalchemy) | ✅Insert                                               | ✅Insert                                                      | ✅Insert                                                      | ✅Insert                                                      |\n| [Psycopg3](https://github.com/psycopg/psycopg)         | ✅Insert ✅Copy                                         | ✅Insert ✅Copy                                                | ✅Insert ✅Copy                                                | ✅Insert ✅Copy                                                |\n| [Django](https://github.com/django/django)             | ✅Insert                                               | ✅Insert                                                      | ✅Insert                                                      | ✅Insert                                                      |\n\n## Usage\n\nInstall from PyPI:\n```bash\npip install pgvecto_rs\n```\n\nAnd use it with your database library:\n- [SQLAlchemy](#sqlalchemy)\n- [Psycopg3](#psycopg3)\n- [Django](#django)\n\nOr as a standalone SDK:\n- [usage of SDK](#sdk)\n\n### Requirements\n\nTo initialize a pgvecto.rs instance, you can run our official image by [Quick start](https://github.com/tensorchord/pgvecto.rs?tab=readme-ov-file#quick-start):\n\nYou can get the latest tags from the [Release page](https://github.com/tensorchord/pgvecto.rs/releases). For example, it might be:\n\n```bash\ndocker run \\\n  --name pgvecto-rs-demo \\\n  -e POSTGRES_PASSWORD=mysecretpassword \\\n  -p 5432:5432 \\\n  -d tensorchord/pgvecto-rs:pg16-v0.3.0\n```\n\n### SQLAlchemy\n\nInstall dependencies:\n```bash\npip install \"pgvecto_rs[sqlalchemy]\"\n```\n\nInitialize a connection\n```python\nfrom sqlalchemy import create_engine\nfrom sqlalchemy.orm import Session\n\nURL = \"postgresql://postgres:mysecretpassword@localhost:5432/postgres\"\nengine = create_engine(URL)\nwith Session(engine) as session:\n    pass\n```\n\nEnable the extension\n```python\nfrom sqlalchemy import text\n\nsession.execute(text('CREATE EXTENSION IF NOT EXISTS vectors'))\n```\n\nCreate a model\n```python\nfrom pgvecto_rs.sqlalchemy import Vector\n\nclass Item(Base):\n    embedding = mapped_column(Vector(3))\n```\n\nAll supported types are shown in this table\n\n| Native types | Types for SQLAlchemy | Correspond to pgvector-python |\n| ------------ | -------------------- | ----------------------------- |\n| vector       | VECTOR               | VECTOR                        |\n| svector      | SVECTOR              | SPARSEVEC                     |\n| vecf16       | VECF16               | HALFVEC                       |\n| bvector      | BVECTOR              | BIT                           |\n\nInsert a vector\n```python\nfrom sqlalchemy import insert\n\nstmt = insert(Item).values(embedding=[1, 2, 3])\nsession.execute(stmt)\nsession.commit()\n```\n\nAdd an approximate index\n```python\nfrom sqlalchemy import Index\nfrom pgvecto_rs.types import IndexOption, Hnsw, Ivf\n\nindex = Index(\n    \"emb_idx_1\",\n    Item.embedding,\n    postgresql_using=\"vectors\",\n    postgresql_with={\n        \"options\": f\"$${IndexOption(index=Ivf(), threads=1).dumps()}$$\"\n    },\n    postgresql_ops={\"embedding\": \"vector_l2_ops\"},\n)\n# or\nindex = Index(\n    \"emb_idx_2\",\n    Item.embedding,\n    postgresql_using=\"vectors\",\n    postgresql_with={\n        \"options\": f\"$${IndexOption(index=Hnsw()).dumps()}$$\"\n    },\n    postgresql_ops={\"embedding\": \"vector_l2_ops\"},\n)\n# Apply changes\nindex.create(session.bind)\n```\n\nGet the nearest neighbors to a vector\n```python\nfrom sqlalchemy import select\n\nsession.scalars(select(Item.embedding).order_by(Item.embedding.l2_distance(target.embedding)))\n```\n\nAlso supports `max_inner_product`, `cosine_distance` and `jaccard_distance(for BVECTOR)`\n\nGet items within a certain distance\n```python\nsession.scalars(select(Item).filter(Item.embedding.l2_distance([3, 1, 2]) \u003c 5))\n```\n\nSee [examples/sqlalchemy_example.py](examples/sqlalchemy_example.py) and [tests/test_sqlalchemy.py](tests/test_sqlalchemy.py) for more examples\n\n### Psycopg3\n\nInstall dependencies:\n```bash\npip install \"pgvecto_rs[psycopg3]\"\n```\n\nInitialize a connection\n```python\nimport psycopg\n\nURL = \"postgresql://postgres:mysecretpassword@localhost:5432/postgres\"\nwith psycopg.connect(URL) as conn:\n    pass\n```\n\nEnable the extension and register vector types\n```python\nfrom pgvecto_rs.psycopg import register_vector\n\nconn.execute('CREATE EXTENSION IF NOT EXISTS vectors')\nregister_vector(conn)\n# or asynchronously\n# await register_vector_async(conn)\n```\n\nCreate a table\n```python\nconn.execute('CREATE TABLE items (embedding vector(3))')\n```\n\nInsert or copy vectors into table\n```python\nconn.execute('INSERT INTO items (embedding) VALUES (%s)', ([1, 2, 3],))\n# or faster, copy it\nwith conn.cursor() as cursor, cursor.copy(\n    \"COPY items (embedding) FROM STDIN (FORMAT BINARY)\"\n) as copy:\n    copy.write_row([np.array([1, 2, 3])])\n```\n\nAdd an approximate index\n```python\nfrom pgvecto_rs.types import IndexOption, Hnsw, Ivf\n\nconn.execute(\n    \"CREATE INDEX emb_idx_1 ON items USING \\\n        vectors (embedding vector_l2_ops) WITH (options=$${}$$);\".format(\n        IndexOption(index=Hnsw(), threads=1).dumps()\n    ),\n)\n# or\nconn.execute(\n    \"CREATE INDEX emb_idx_2 ON items USING \\\n        vectors (embedding vector_l2_ops) WITH (options=$${}$$);\".format(\n        IndexOption(index=Ivf()).dumps()\n    ),\n)\n# Apply all changes\nconn.commit()\n```\n\nGet the nearest neighbors to a vector\n```python\nconn.execute('SELECT * FROM items ORDER BY embedding \u003c-\u003e %s LIMIT 5', (embedding,)).fetchall()\n```\n\nGet the distance\n```python\nconn.execute('SELECT embedding \u003c-\u003e %s FROM items \\\n    ORDER BY embedding \u003c-\u003e %s', (embedding, embedding)).fetchall()\n```\n\nGet items within a certain distance\n```python\nconn.execute('SELECT * FROM items WHERE embedding \u003c-\u003e %s \u003c 1.0 \\\n    ORDER BY embedding \u003c-\u003e %s', (embedding, embedding)).fetchall()\n```\n\nSee [examples/psycopg_example.py](examples/psycopg_example.py) and [tests/test_psycopg.py](tests/test_psycopg.py) for more examples\n\n### Django\n\nInstall dependencies:\n\n```bash\npip install \"pgvecto_rs[django]\"\n```\n\nCreate a migration to enable the extension\n\n```python\nfrom pgvecto_rs.django import VectorExtension\n\nclass Migration(migrations.Migration):\n    operations = [\n        VectorExtension()\n    ]\n```\n\nAdd a vector field to your model\n\n```python\nfrom pgvecto_rs.django import VectorField\n\nclass Document(models.Model):\n    embedding = VectorField(dimensions=3)\n```\n\nAll supported types are shown in this table\n\n| Native types | Types for Django   | Correspond to pgvector-python |\n| ------------ | ------------------ | ----------------------------- |\n| vector       | VectorField        | VectorField                   |\n| svector      | SparseVectorField  | SparseVectorField             |\n| vecf16       | Float16VectorField | HalfVectorField               |\n| bvector      | BinaryVectorField  | BitField                      |\n\nInsert a vector\n```python\nItem(embedding=[1, 2, 3]).save()\n```\n\nAdd an approximate index\n```python\nfrom django.db import models\nfrom pgvecto_rs.django import HnswIndex, IvfIndex\nfrom pgvecto_rs.types import IndexOption, Hnsw\n\n\nclass Item(models.Model):\n    class Meta:\n        indexes = [\n            HnswIndex(\n                name=\"emb_idx_1\",\n                fields=[\"embedding\"],\n                opclasses=[\"vector_l2_ops\"],\n                m=16,\n                ef_construction=100,\n                threads=1,\n            )\n            # or\n            IvfIndex(\n                name=\"emb_idx_2\",\n                fields=[\"embedding\"],\n                nlist=3,\n                opclasses=[\"vector_l2_ops\"],\n            ),\n        ]\n```\n\nGet the nearest neighbors to a vector\n```python\nfrom pgvecto_rs.django import L2Distance\n\nItem.objects.order_by(L2Distance('embedding', [3, 1, 2]))[:5]\n```\n\nAlso supports `MaxInnerProduct`, `CosineDistance` and `JaccardDistance(for BinaryVectorField)`\n\nGet the distance\n```python\nItem.objects.annotate(distance=L2Distance('embedding', [3, 1, 2]))\n```\n\nGet items within a certain distance\n```python\nItem.objects.alias(distance=L2Distance('embedding', [3, 1, 2])).filter(distance__lt=5)\n```\n\nSee [examples/django_example.py](examples/django_example.py) and [tests/test_django.py](tests/test_django.py) for more examples.\n\n### SDK\n\nOur SDK is designed to use the pgvecto.rs out-of-box. You can exploit the power of pgvecto.rs to do similarity search or retrieve with filters, without writing any SQL code.\n\nInstall dependencies:\n```bash\npip install \"pgvecto_rs[sdk]\"\n```\n\nA minimal example:\n\n```Python\nfrom pgvecto_rs.sdk import PGVectoRs, Record\n\n# Create a client\nclient = PGVectoRs(\n    db_url=\"postgresql+psycopg://postgres:mysecretpassword@localhost:5432/postgres\",\n    collection_name=\"example\",\n    dimension=3,\n)\n\ntry:\n    # Add some records\n    client.insert(\n        [\n            Record.from_text(\"hello 1\", [1, 2, 3]),\n            Record.from_text(\"hello 2\", [1, 2, 4]),\n        ]\n    )\n\n    # Search with default operator (sqrt_euclid).\n    # The results is sorted by distance\n    for rec, dis in client.search([1, 2, 5]):\n        print(rec.text)\n        print(dis)\nfinally:\n    # Clean up (i.e. drop the table)\n    client.drop()\n```\n\nOutput:\n```\nhello 2\n1.0\nhello 1\n4.0\n```\n\nSee [examples/sdk_example.py](examples/sdk_example.py) and [tests/test_sdk.py](tests/test_sdk.py) for more examples.\n\n\n\n\n## Development\n\nThis package is managed by [PDM](https://pdm.fming.dev).\n\nSet up things:\n```bash\npdm venv create\npdm use # select the venv inside the project path\npdm sync -d -G :all --no-isolation\n\n# lock requirement\n# need pdm \u003e=2.17: https://pdm-project.org/latest/usage/lock-targets/#separate-lock-files-or-merge-into-one\npdm lock -d -G :all --python=\"\u003e=3.9\"\npdm lock -d -G :all --python=\"\u003c3.9\" --append\n# install package to local\n# `--no-isolation` is required for scipy\npdm install -d --no-isolation\n```\n\nRun lint:\n```bash\npdm run format\npdm run fix\npdm run check\n```\n\nRun test in current environment:\n```bash\npdm run test\n```\n\n\n## Test\n\n[Tox](https://tox.wiki) is used to test the package locally.\n\nRun test in all environment:\n```bash\ntox run\n```\n\n## Acknowledgement\n\nWe would like to express our gratitude to the creators and contributors of the [pgvector-python](https://github.com/pgvector/pgvector-python) repository for their valuable code and architecture, which greatly influenced the development of this repository.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftensorchord%2Fpgvecto.rs-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftensorchord%2Fpgvecto.rs-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftensorchord%2Fpgvecto.rs-py/lists"}