iris-vector-graph
Turn InterSystems IRIS into a graph + vector database — openCypher queries, HNSW/BM25 hybrid search, temporal property graph, RDF/SHACL/PROV-O semantic layer, and Neo4j Bolt protocol compatibility.
Getting Started
Five minutes from zero to running graph queries.
1. Start IRIS
docker compose up -d
Starts IRIS Community Edition on localhost:1972. No license required.
Default credentials: _SYSTEM / SYS.
2. Install
pip install iris-vector-graph
3. Run your first query
import iris
from iris_vector_graph.engine import IRISGraphEngine
conn = iris.connect("localhost", 1972, "USER", "_SYSTEM", "SYS")
engine = IRISGraphEngine(conn, embedding_dimension=768)
engine.initialize_schema()
engine.create_node("alice", labels=["Person"], properties={"name": "Alice"})
engine.create_node("bob", labels=["Person"], properties={"name": "Bob"})
engine.create_edge("alice", "KNOWS", "bob")
result = engine.execute_cypher(
"MATCH (a {node_id:$id})-[:KNOWS]->(b) RETURN b.name AS name",
{"id": "alice"}
)
print(result["rows"]) # [('Bob',)]
Note:
initialize_schema()prints compile warnings on Community Edition — safe to ignore. Enterprise-only classes (Graph.KG.MCPService,Graph.KG.MCPToolSet) are not required.
What It Does
| Feature | Notes |
|---|---|
| openCypher | MATCH, CREATE, MERGE, DELETE, WITH, UNWIND, variable-length paths, subqueries |
| Temporal property graph | Time-windowed edges, pre-aggregated bucket analytics, O(1) window queries |
| Vector search | HNSW (native IRIS VECTOR), IVFFlat, PLAID multi-vector, BM25 full-text |
| Graph analytics | Betweenness, closeness, eigenvector, degree centrality; Leiden community detection; SCC; k-core; PPR |
| Shortest path | Unweighted BFS (shortestPath), weighted Dijkstra (ivg.shortestPath.weighted) |
| NKG fast-path | [*1..N] Cypher patterns route to integer-keyed ^NKG index, bypassing SQL translation |
| Bulk loader | 190–312K edges/s direct ^KG write; incremental ^NKG rebuild |
| FHIR bridge | ICD-10 → knowledge graph mapping via FHIR R4 |
| Bolt protocol | neo4j-driver compatible wire protocol (TCP + WebSocket) |
| Embedded Python | Graph algorithms run server-side via IRIS embedded Python (igraph, leidenalg) |
| IPM / ZPM | ObjectScript-only install via InterSystems Package Manager |
| RDF export | export_rdf() — full or filtered graph to Turtle/NT/NQuads/JSON-LD |
| SHACL validation | validate_shacl() — SHACL Core via PySHACL; ValidationReport dataclass |
| PROV-O | prov_export() — temporal edges as W3C PROV-O provenance graph |
Performance
Hardware: M3 Ultra, Community IRIS 2026.1, ARM64 Docker.
Query latency
| Query | Latency | Notes |
|---|---|---|
| 1-hop neighbor lookup | ~0.4ms | $Order on ^KG |
NKG fast-path [*1..N], hops 2–5 |
1.4–2.0ms | 4.9–13.4x faster than SQL path |
| IC3 2-hop with LIMIT (LDBC SF10) | 1.2ms | 3.5x faster than GES/GraphScope |
| IC13 shortest path (LDBC SF10) | 2.1–3.2ms | Comparable to GES at SF1000 on cluster |
| HNSW vector search (768-dim) | 1.7ms | Native IRIS VECTOR index |
| BM25 full-text (174 nodes, 3-term) | 0.3ms | Posting-list $Order |
| Temporal window query | 0.1ms | O(results), B-tree |
| Pre-aggregated bucket (24hr/288 buckets) | 0.16ms | O(buckets), not O(edges) |
Algorithm comparison (vs Neo4j GDS and networkx)
IVG is competitive with or faster than Neo4j GDS on degree centrality, betweenness, and Leiden community detection, producing results identical to networkx (Pearson r = 1.0). Validated on DRKG biomedical KG (~97K nodes / ~5.9M edges).
Full methodology and numbers: docs/performance/BENCHMARKS.md and docs/performance/GRAPH_ALGORITHMS.md.
Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ iris-vector-graph v2.1.0 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────────┐ │
│ │ Python SDK │ │ Cypher/AQL │ │ Bolt (wire) │ │
│ │ IRISGraph │ │ translator │ │ neo4j-driver │ │
│ │ Engine │ │ + executor │ │ compatible │ │
│ └───────┬───────┘ └───────┬───────┘ └────────┬──────────┘ │
│ └──────────────┬────┘ │ │
│ ▼ │ │
│ ┌────────────────────────┐ │ │
│ │ GraphStore protocol │◄─────────────┘ │
│ │ (pluggable backend) │ │
│ └───────────┬────────────┘ │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌──────────┐ ┌───────────────┐ │
│ │ SQL layer │ │ ^KG │ │ ^NKG │ │
│ │ Graph_KG.* │ │ globals │ │ integer adj │ │
│ │ (nodes, │ │ (edges, │ │ index │ │
│ │ edges, │ │ temp, │ └───────┬───────┘ │
│ │ vectors) │ │ PPR) │ │ │
│ └─────────────┘ └──────────┘ │ │
│ ▼ │
│ ┌────────────────────┐ │
│ │ Algorithm tiers │ │
│ ├────────────────────┤ │
│ │ 1. Rust accelerator│ ← fastest │
│ │ (rayon parallel)│ │
│ │ 2. ObjectScript │ │
│ │ parallel 8× │ │
│ │ 3. Python LazyKG │ ← always works│
│ └────────────────────┘ │
│ │
│ Centrality: betweenness (Brandes) · closeness · eigenvector │
│ degree │
│ Community: Leiden · triangle count · SCC · k-core │
│ Search: vector (HNSW/IVF/PLAID) · BM25 · temporal · PPR │
│ │
└─────────────────────────────────────────────────────────────────────┘
Full schema and ObjectScript class reference: docs/architecture/ARCHITECTURE.md.
Semantic Layer (RDF / SHACL / PROV-O)
pip install 'iris-vector-graph[rdf]'
# Export graph as Turtle (full or filtered)
engine.export_rdf("kg.ttl")
engine.export_rdf("proteins.nt", format="nt", label_filter=["Protein", "Disease"])
engine.export_rdf_from_cypher("MATCH (p:Patient)-[r]->(e) RETURN p,r,e", "patients.ttl")
# Persistent namespace prefixes
engine.register_namespace("fhir", "http://hl7.org/fhir/")
# SHACL Core validation
report = engine.validate_shacl("shapes/patient.ttl")
if not report.conforms:
for v in report.violations:
print(f"{v.focus_node}: {v.message} [{v.severity}]")
# PROV-O temporal provenance
engine.prov_export("provenance.ttl", ts_start=1700000000)
prov = engine.prov_as_dict(edge_id=42)
Every write to ivg is stored as W3C-aligned SPO triples (rdf_edges, rdf_props, rdf_labels)
with OWL 2 RL inference, named graph support, and RDF-star style edge qualifiers.
See docs/SEMANTIC_LAYER.md for the full guide: format
reference, SHACL shape writing, PROV-O vocabulary mapping, and integration patterns.
Documentation
| Document | Contents |
|---|---|
| User Guide | Cypher examples, temporal edges, vector search, bulk loader |
| Admin Guide | Container setup, schema management, index rebuilding |
| Admin API | Python API reference for engine administration |
| Benchmarks | Full methodology, LDBC SNB results, ingestion throughput |
| Graph Algorithms | Centrality and community detection benchmark details |
| Semantic Layer | RDF export, SHACL validation, PROV-O provenance |
| Changelog | Full version history |
AI Agent Development
When building agents that use IVG as a knowledge graph backend, install the iris-agentic-dev MCP toolkit for ObjectScript compilation, global inspection, and IRIS method invocation from your agent's tool loop:
pip install iris-agentic-dev
This gives your agent iris_compile, iris_execute, iris_global, and related tools
that work alongside IVG's Python API.
Skill files with agent-oriented quickstarts:
skills/iris-vector-graph/SKILL.md— IVG API, temporal edges, SHACL, globals, container setup, common gotchasskills/ivg-arno/SKILL.md— Arno Rust acceleration, BFS at scale, enterprise container, ASQ query syntax
License
MIT. See LICENSE.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file iris_vector_graph-2.7.0.tar.gz.
File metadata
- Download URL: iris_vector_graph-2.7.0.tar.gz
- Upload date:
- Size: 31.2 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
2920900b03da9ac449dcb44ae72af621bc5000b24cef1c0ac1e7f3d1c9b6b89c
|
|
| MD5 |
b5c35dc813214269a2e57a1c6fbd9435
|
|
| BLAKE2b-256 |
3538a20b6b27616eab66ada5e60a1fb598f0e23203bfd1ff031ecc9ef0339de5
|
File details
Details for the file iris_vector_graph-2.7.0-py3-none-any.whl.
File metadata
- Download URL: iris_vector_graph-2.7.0-py3-none-any.whl
- Upload date:
- Size: 451.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
32e21daa8a1dbd6c104ee431cd41f20502341ae997713e4d8bb1365ef6f127c0
|
|
| MD5 |
df2c0a4110fffee4caec272b5cb8f5e5
|
|
| BLAKE2b-256 |
ab0a40c9464a3924a51a7f16a5ed3e78485d4f930a168d32317d8955a5b686ea
|
