IronGraph for Python

Python access to a CPU graph database with built-in streaming and queues.

Use Cypher to query graph structure, search text and vectors, inspect property history, and administer the database. Built-in Kafka-compatible Streams and AMQP-compatible Queues handle event and message workloads. The irongraph package provides native embedded access and remote Query API/Bolt clients for Python. IronGraph is open-source software released under the Apache License 2.0.

Performance at a glance

Graph queries execute on the CPU against one shared canonical graph. Local text inference can use Metal or CUDA independently. Measure complete queries separately from individual graph operations; latency depends on the workload, graph size, indexes, and host.

Database capabilities

Cypher handles graph operations, temporal analysis, search, and stream/queue administration. Message producers and consumers use the supported Kafka or AMQP protocols through the instance's configured listeners. The SDK query interface does not replace those protocol clients.

Explicit projects and the OBSERVED, KNOWLEDGE, and WORKSPACE layers organize data. Indexes and unique constraints, transactions, asynchronous write-ahead logging, recovery, and periodic snapshots are part of the database.

The standalone instance serves its web console at http://127.0.0.1:18484/web/ by default and also supports local MCP access. Start the official standalone distribution before opening that address. Opening an embedded database through Python, Node.js, or Rust does not start a web server or expose the console. For a configured remote instance, use its HTTPS address followed by /web/, with the required browser-managed client certificate.

Temporal reads apply to declared properties within their retention window. Graph topology and ordinary properties are read in their current state.

Install

You need Python 3.9 or later and an official wheel. Native release targets are macOS 15+ ARM64 and Linux with glibc 2.28+ on ARM64 or AMD64. These are package build baselines; check your release's qualification results before deploying. After configuring the official package source supplied with your release:

python -m pip install --only-binary=:all: irongraph

The matching wheel must be published to that source. Installation uses a compiled database binary and does not require a Rust compiler.

Store and read a text document

Use a writable directory exclusively owned by your application process. Default startup downloads and verifies the local embedding model if absent, then loads and warms it. Allow network access and sufficient disk space on first use.

from irongraph import EmbeddedDatabase

with EmbeddedDatabase("./irongraph-data", device="cpu") as database:
    database.query("CREATE PROJECT IF NOT EXISTS notes")
    result = database.query(
        """USE notes
        MERGE (document:Document {id: $id})
        SET document.body = $body
        RETURN document.body AS body""",
        parameters={"id": "welcome", "body": "Graphs connect facts."},
    )
    print(result["rows"][0][0]["value"])

Expected output: Graphs connect facts. The context manager closes the database and the text document persists. Run the example again to update the same text document.

The example selects CPU across native release targets and keeps automatic text embedding enabled. Select embedding_device="metal" on a supported Mac to accelerate text inference.

Next, declare an embedding index on the text document body and use MATCH … SEARCH … RETURN to combine vector retrieval with graph filters. The same query method supports text document updates, indexes, temporal data, graph algorithms, and topic, queue, exchange, and binding administration. Text documents are ordinary graph nodes; their complete text remains on the owning node.

Use an async application

Use the async methods in an asyncio application. Concurrent calls share the same embedded database and graph, and database work runs outside the event loop.

import asyncio
from irongraph import EmbeddedDatabase

async def main():
    database = await EmbeddedDatabase.open_async("./irongraph-data", device="cpu")
    async with database:
        await database.query_async("CREATE PROJECT IF NOT EXISTS notes")
        result = await database.query_async("USE notes MATCH (n) RETURN count(n)")
        print(len(result["rows"]))

asyncio.run(main())

Expected output: 1. The async context manager closes the database. Async variants also cover streaming, status, cancellation, snapshots, and flushing. Concurrent data calls wait asynchronously for an available worker without a configurable operation quota.

Operate the database

Choose projects explicitly with USE or project_id; there is no implicit default. Each project has OBSERVED, KNOWLEDGE, and WORKSPACE layers for source facts, curated facts, and working data. Transactions, asynchronous write-ahead logging, recovery, and snapshots apply to embedded data as they do in a standalone instance.

One process uses one shared CPU graph and one active embedded instance. Text inference selects its CPU, Metal, or CUDA device independently; CUDA requires a CUDA-enabled release. Parallel reads do not wait for writers and may observe mixed values during a multi-record write. Keep the database open for the application's lifetime. IronGraph embeds text locally and does not run generative language models.

For remote access, use Client.api_mtls or Client.bolt_mtls with a client certificate, private-key path, and trusted certificate authority. Plain connections are loopback-only; remote access requires mutual TLS and a credential authorized for the project and operations.

License

IronGraph is licensed under the Apache License 2.0. Third-party components and the embedding model retain their own terms.