Skip to main content

⚡ PolyVector

High-Performance, In-Engine Multi-Field Hybrid Search for PostgreSQL.
Native vector embeddings + length-normalized BM25 full-text search combined in a single unified SQL query—100% local, zero API tokens, and universal ORM compatibility.


📊 Comprehensive Benchmark (100,000 Documents)

PolyVector was rigorously evaluated against Elasticsearch 8.x and PostgreSQL Native Full-Text Search (FTS) on an un-cached catalog of 100,000 records using CPU-only inference (BAAI/bge-small-en-v1.5, 384 dimensions).

📌 Scalability Note: All numbers below reflect the verified 100,000-document benchmark. A final stress test on 1,000,000 records (1M) is scheduled following the library stabilization to verify continuous linear scaling and memory bounds.

1. Performance & Relevance Summary Table

Metric PostgreSQL Native FTS Elasticsearch 8.x (Hybrid) PolyVector (In-Engine Hybrid) Advantage of PolyVector
Median Latency (p50) 51.66 ms 132.07 ms 40.40 ms (16–25 ms pooled) 3.2× faster than Elasticsearch Hybrid
95th Percentile (p95) 67.95 ms 316.85 ms 82.29 ms 3.8× faster than Elasticsearch Hybrid
99th Percentile (p99) 75.98 ms 351.79 ms 124.83 ms Predictable tail latencies under heavy load
Throughput (QPS) 19.50 QPS 6.82 QPS 20.17 QPS 2.9× higher throughput than Elasticsearch
RAM Consumed (Engine) ~256 MB (shared buffers) ~2.5 GB – 4.0 GB (JVM heap) ~350 MB (Postgres RAM) ~85% less memory than Elasticsearch
Index Size on Disk 4.75 MB 767.01 MB 298.87 MB 61% smaller storage footprint than ES
Infrastructure Stack 1 Engine (PostgreSQL) 2 Engines + Sync Pipeline 1 Engine (PostgreSQL) Zero sync pipelines, zero split-brain risk
NDCG@10 (Ranking Quality) 0.6696 0.9696 0.9253 +38.2% over Postgres FTS, near-parity with ES
MRR (First Result Accuracy) 0.7143 1.0000 1.0000 Perfect first-hit accuracy (same as ES)
Precision@10 0.6349 0.9286 0.8714 +37.2% over Postgres FTS
Recall@100 (Coverage) 0.4471 0.9471 0.8343 +86.6% over Postgres FTS

📖 Benchmark Terms Explained

  • p50 / p95 / p99 Latency: 50%, 95%, and 99% of user search queries completed in under this time.
  • QPS (Queries Per Second): Sustained query throughput executed per single engine core.
  • RAM Occupied: Active operating memory allocated by the search service to keep indexes and caches hot.
  • Storage on Disk: Combined physical footprint of the inverted index, vector graph (HNSW), and metadata.
  • Infrastructure Stack: Number of independent stateful systems required to operate search in production.
  • NDCG@10 (Normalized Discounted Cumulative Gain at 10): Measures ranking quality. Rewards algorithms that place the most relevant items at the top of the list.
  • MRR (Mean Reciprocal Rank): Measures how quickly a user finds their first relevant hit ($1 / \text{rank}$). A score of 1.0000 means rank #1 hit on all queries.
  • Precision@10: The proportion of top-10 returned documents that are genuinely relevant.
  • Recall@100: The percentage of truly relevant documents retrieved within the top 100 candidates.

💡 Why PolyVector?

  1. Zero API Tokens / 100% Local ONNX Inference:
    PolyVector runs local embeddings directly on your application CPU via ONNX Runtime (fastembed in Python, @xenova/transformers in JS/TS). Your data never leaves your VPC, you incur $0 in third-party API fees, and you never hit rate limits.
  2. Partial HNSW Vector Indexes:
    Instead of maintaining a massive single vector table, PolyVector partitions vector graphs by field (WHERE field_name = 'name'). Each graph stays compact, cache-resident in RAM, and searches significantly faster.
  3. In-Engine Single Query Fusion:
    Eliminates application-side Reciprocal Rank Fusion (RRF) round-trips. PolyVector compiles candidate branches (UNION ALL) and computes weighted linear score fusion (SUM(partial_score) GROUP BY entity_id) directly inside PostgreSQL.
  4. Length-Normalized BM25:
    Standard full-text search often biases long documents. PolyVector incorporates ts_rank_cd(fts_doc, query, 32) to eliminate document length bias, matching Elasticsearch's BM25 accuracy.
  5. Universal ORM & Driver Agnostic:
    Outputs pure, ANSI-compliant SQL with parameterized bindings (:param or %(param)s), working natively with Prisma, Drizzle, SQLAlchemy, Django, or raw database drivers.

🐍 Python Guide

1. Installation

# Core package (psycopg2 + fastembed)
pip install polyvector

# Optional: with SQLAlchemy adapter
pip install "polyvector[sqlalchemy]"

2. Complete Setup & Search Flow

from polyvector import PolyVectorIndex, ConnectionPool

# 1. Initialize persistent connection pool
pool = ConnectionPool(
    config="postgresql://postgres:postgres@localhost:5432/my_database",
    minconn=2,
    maxconn=10
)

# 2. Define the index configuration
index = PolyVectorIndex(
    table="products",
    id_column="id",
    embeddings_table="product_embeddings",
    fields={
        "name": {"weight": 0.45, "type": "vector"},
        "description": {"weight": 0.20, "type": "vector"},
        "fts_doc": {"weight": 0.35, "type": "bm25"}
    },
    distinct_on="name",                    # Deduplicate variants
    filter_fields=["category", "price"],    # Tier-1/Tier-2 filterable fields
    connection_pool=pool
)

# 3. Create tables, pgvector extensions, and partial HNSW indexes
index.setup()

# 4. Ingest documents (Local ONNX embeds automatically on CPU)
documents = [
    {
        "id": "item_101",
        "name": "Men's Waterproof Trail Runner 4",
        "description": "All-terrain running shoes with Gore-Tex lining.",
        "category": "Footwear",
        "price": 149.99
    }
]
index.index(documents)

# 5. Hybrid Search with Decoupled Latency Metrics
response = index.search(
    query="waterproof trail runner",
    filters={"price": {"lte": 160.0}},
    limit=5
)

print(f"Total: {response.total_latency_ms:.2f}ms "
      f"[Model: {response.embed_latency_ms:.2f}ms | DB: {response.db_latency_ms:.2f}ms]")

for item in response.items:
    print(f"[{item.score:.4f}] ID: {item.id}")

🟨 JavaScript & TypeScript Guide (@polyvector/core)

PolyVector is designed with identical architecture for Node.js, Bun, and Deno using @xenova/transformers for local ONNX CPU inference.

1. Installation

npm install @polyvector/core
# or
pnpm add @polyvector/core

2. TypeScript Quickstart

import { PolyVectorIndex } from "@polyvector/core";
import { Pool } from "pg";

const pgPool = new Pool({
  connectionString: "postgresql://postgres:postgres@localhost:5432/my_database"
});

const index = new PolyVectorIndex({
  table: "products",
  idColumn: "id",
  embeddingsTable: "product_embeddings",
  fields: {
    name: { weight: 0.45, type: "vector" },
    description: { weight: 0.20, type: "vector" },
    fts_doc: { weight: 0.35, type: "bm25" }
  },
  distinctOn: "name",
  filterFields: ["category", "price"],
  pool: pgPool
});

// Setup schema
await index.setup();

// Execute search
const results = await index.search("waterproof trail runner", {
  filters: { price: { lte: 160.0 } },
  limit: 5
});

console.log(`Executed in ${results.totalLatencyMs}ms`);
for (const item of results.items) {
  console.log(`[${item.score.toFixed(4)}] ID: ${item.id}`);
}

🔌 Universal ORM Integration Examples

Because PolyVector compiles pure, ANSI-standard parameterized SQL, you are never trapped by ORM limitations or proprietary query builders.


Example 1: Prisma (TypeScript)

Use PolyVector's compileQuery() to generate the parameterized SQL, then execute it directly via Prisma's $queryRawUnsafe:

import { PrismaClient } from "@prisma/client";
import { PolyVectorIndex } from "@polyvector/core";

const prisma = new PrismaClient();
const index = new PolyVectorIndex({
  table: "Product",
  idColumn: "id",
  fields: {
    name: { weight: 0.5, type: "vector" },
    description: { weight: 0.5, type: "bm25" }
  }
});

async function searchProducts(searchTerm: string, maxPrice: number) {
  // 1. Compile pure SQL & bind parameters (:vec, :q, :limit)
  const { sql, params } = await index.compileQuery(searchTerm, {
    filters: { price: { lte: maxPrice } },
    limit: 10,
    paramStyle: "named"
  });

  // 2. Execute via Prisma's native raw interface
  // Prisma maps results seamlessly into your type-safe model structure
  const rankedItems = await prisma.$queryRawUnsafe<Array<{ id: string; score: number }>>(
    sql,
    params
  );

  return rankedItems;
}

Example 2: Drizzle ORM (TypeScript)

Drizzle provides native raw execution via sql.raw or db.execute:

import { drizzle } from "drizzle-orm/node-postgres";
import { sql } from "drizzle-orm";
import { PolyVectorIndex } from "@polyvector/core";

const db = drizzle(process.env.DATABASE_URL!);
const index = new PolyVectorIndex({
  table: "products",
  fields: {
    title: { weight: 0.6, type: "vector" },
    content: { weight: 0.4, type: "bm25" }
  }
});

async function searchWithDrizzle(queryText: string) {
  // Compile SQL with named parameters
  const { sql: querySql, params } = await index.compileQuery(queryText, {
    limit: 10,
    paramStyle: "named"
  });

  // Execute using Drizzle's sql template
  const results = await db.execute(sql.raw(querySql, params));
  return results.rows;
}

Example 3: Universal Pure SQL Execution (Any ORM / Raw Driver)

Whether you use SQLAlchemy, Django ORM, TypeORM, or raw psycopg3 / pg, PolyVector gives you the exact query string and parameter format required:

A. SQLAlchemy / SQLModel (Python)

from sqlalchemy import create_engine
from sqlalchemy.orm import Session
from polyvector import PolyVectorIndex, SQLAlchemyAdapter

engine = create_engine("postgresql+psycopg2://user:pass@localhost:5432/db")

with Session(engine) as session:
    results = SQLAlchemyAdapter.search(
        index=index,
        session=session,
        query="trail runner",
        filters={"category": "Footwear"},
        limit=10
    )
    for row in results:
        print(row.id, row.score)

B. Django ORM (Python)

from myapp.models import Product

sql, params = index.compile_query("trail runner", limit=10, param_style="pyformat")

# Hydrate directly into Django model instances
products = Product.objects.raw(sql, params)
for p in products:
    print(p.name, p.price)

C. Raw node-postgres (pg driver)

const { sql, params } = await index.compileQuery("trail runner", { limit: 10 });
const { rows } = await client.query(sql, Object.values(params));

Why this works universally:
PolyVector uses standard ANSI CAST(:vec AS vector) and CAST(:meta AS jsonb) instead of dialect-specific operators (::vector), ensuring that PostgreSQL parses parameters correctly across every single ORM and database driver.


🛠️ Advanced Customization: text_extractor

When indexing data, you often want to combine multiple columns or parse nested JSON before generating vectors. Use text_extractor:

index = PolyVectorIndex(
    table="books",
    fields={
        # Enriches the vector with author and year context
        "rich_content": {
            "weight": 0.6,
            "extractor": lambda r: f"{r['title']} by {r['author']} ({r['published_year']})"
        },
        # Extracts nested JSON specification
        "specs_vector": {
            "weight": 0.4,
            "extractor": lambda r: f"{r['specs']['format']} edition, {r['specs']['pages']} pages"
        }
    }
)

🧪 Testing

Run the test suite against a live PostgreSQL instance:

pytest -v tests/test_polyvector_library.py

📄 License

MIT License. Free for commercial and open-source use.

Metadata

Release files for polyvector 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polyvector 0.1.0
File Size Uploaded Provenance Actions
polyvector-0.1.0.tar.gz 20.6 kB Without provenance Details for polyvector-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for polyvector 0.1.0
File Interpreter ABI Platform Actions
polyvector-0.1.0-py3-none-any.whl Python 3 none any Details for polyvector-0.1.0-py3-none-any.whl

Total release size: 37.5 kB

Release files / polyvector-0.1.0.tar.gz

Download URL polyvector-0.1.0.tar.gz
Size 20.6 kB
Tags Source
SHA-256 checksum
How to use checksums
aae94913b89ca8d1bdaa427000523bdaebecdcbe3ede5c23f23df9b666fae34a
BLAKE2b-256 checksum
How to use checksums
c58149032c59500f203f805829ba9db46e3da9b45caade458467ba66ec716d77
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Release files / polyvector-0.1.0-py3-none-any.whl

Download URL polyvector-0.1.0-py3-none-any.whl
Size 16.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a007fcd3954345dab00c70c2225bcb06a69e21122c4c1910e7b756d44fc2dcc5
BLAKE2b-256 checksum
How to use checksums
82ffee6a3764fff619423d5049b2ea836e8b179265359dd9ba2c553a1adba0a5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.3

Security for polyvector 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page