piggie 0.5.0

Python SDK for Apache AGE + pgvector — graph and vector queries on PostgreSQL

Piggie

Python SDK for Apache AGE + pgvector on PostgreSQL.

Graph queries, vector search, and hybrid graph+vector operations — all in one PostgreSQL instance.

Quick Start

import piggie

db = piggie.connect("postgresql://localhost:5433/piggie", graph="my_graph")

# Cypher queries → DataFrames
df = db.cypher("MATCH (n:Person) RETURN n.name, n.age").to_df()

# Vector search
results = db.vector_search("documents", "embedding", query_vec, k=10).to_df()

# Hybrid: graph traversal + vector similarity
results = db.hybrid_search(
    cypher="MATCH (p:Paper)-[:CITES]->(cited) RETURN cited",
    vector_table="papers",
    vector_column="abstract_embedding",
    query_vector=query_vec,
    k=10,
).to_df()

Installation

pip install piggie

# With pandas support
pip install piggie[pandas]

# With all optional dependencies
pip install piggie[all]

Benchmarks

We benchmarked AGE + pgvector against Neo4j, Kuzu, and NebulaGraph across 12 workloads at three scales (10K, 100K, 1M). AGE won all 12 workloads at every scale. At 1M nodes:

Workload	AGE	Neo4j	Speedup
Point Lookup	0.29ms	0.97ms	3x
Pattern Match	0.14ms	1.8ms	13x
VLE Traversal	0.18ms	0.62ms	3x
Concurrent Queries	52ms	1,323ms	25x
Bulk Load	59ms	133ms	2x

The Piggie SDK also won 14/16 algorithm benchmarks against Neo4j GDS, using igraph (C) and networkit (C++) backends.

Read the full analysis: Can One PostgreSQL Replace Your Graph Database and Your Vector Database?

Graph Algorithms

19 algorithms across 7 categories with automatic backend selection:

# Auto-selects igraph C backend
df = db.centrality(measure="betweenness")

# Auto-selects networkit C++ backend
df = db.centrality(measure="closeness")

# Community detection
df = db.community(method="louvain")

Backends: igraph (C), networkit (C++), NetworkX (Python). The SDK detects installed backends and routes each algorithm to the fastest available implementation.

Integrations

• LangChain — PiggieVectorStore and PiggieGraphStore for RAG pipelines
• LlamaIndex — PiggieGraphStore (triplets) and PiggiePropertyGraphStore (labeled property graph)
• NetworkX — to_networkx() conversion + built-in PageRank, community detection, shortest path, centrality
• PyTorch Geometric — FeatureStore and GraphStore for GNN training on AGE data

Notebooks

Notebook	Description
Quickstart	Getting started with Piggie
Hybrid Search	Graph + vector search combined
Bulk Load	Bulk load and export
Algorithms	Graph algorithms with igraph/networkit backends
RAG Pipeline	RAG with LlamaIndex and LangChain
GNN Training	GNN training with PyTorch Geometric

Documentation

• Quick Start — 5-minute getting-started guide
• API Reference — full method signatures and parameters
• Graph Algorithms — algorithm catalog and backend selection
• Integrations — LangChain, LlamaIndex, NetworkX, PyG

Community

• GitHub Discussions — questions, ideas, show and tell
• Issue Tracker — bug reports and feature requests
• Contributing Guide — how to set up and contribute

Requirements

• Python 3.10+
• PostgreSQL with Apache AGE and pgvector extensions

License

Apache 2.0