Guide Overview

This guide is the basic-usage path: install GraphForge, run your first queries, and cover everyday workflows. For architecture, research, and deeper narratives, see the Book. The public documentation map lists published trees.

Start here

Page	Purpose
Installation	Install via pip or uv
Quick Start	First graph in five minutes
Tutorial	Step-by-step walkthrough

Everyday workflows

Cypher Query Language

Learn the openCypher query language — GraphForge’s primary interface for working with graphs.

Graph Construction

Build graphs programmatically using the Python API.

Analytics Integration

Export graphs to NetworkX, igraph, and pandas for further analysis.

Ranking Nodes — forge.rank()

Score every node with a graph centrality algorithm (PageRank, betweenness, closeness, degree, clustering coefficient, or triangle count). Returns an Arrow Table with node properties plus a score column. Pass write_property to persist scores back to the graph. See the tutorial for examples.

Clustering Nodes — forge.cluster()

Assign community membership using Louvain or connected-components algorithms. Returns an Arrow Table with node properties plus a community_id column. Pass write_property to persist assignments back to the graph. See the tutorial for examples.

Finding Nodes — forge.find()

Full-text, vector similarity, or hybrid search over node properties. Bring your own vectors — GraphForge stores and queries them but does not generate embeddings. Returns an Arrow Table with node properties plus score and matched_on columns. See the tutorial for examples.

Reference (not everyday)

Datasets (backlog)

Planned open-dataset catalogs — not shipped in v0.5.0. Kept under Reference for readers tracking the backlog extension.

Core Concepts

Graphs

A graph consists of nodes (vertices) and relationships (edges) connecting them.

Nodes

Nodes represent entities in your graph. They can have:

• Labels - Types or categories (e.g., Person, Product)
• Properties - Key-value pairs with data

Relationships

Relationships connect nodes and can have:

• Type - The nature of the connection (e.g., KNOWS, PURCHASED)
• Direction - From one node to another
• Properties - Additional data about the relationship

Patterns

Cypher uses ASCII-art patterns to describe graph structures:

(a:Person)-[:KNOWS]->(b:Person)

This pattern matches two Person nodes connected by a KNOWS relationship.

Query Flow

1. MATCH - Find patterns in the graph
2. WHERE - Filter results
3. RETURN - Specify what to return
4. ORDER BY - Sort results
5. LIMIT - Limit number of results

Result Types

v0.5.0: ALL methods return a PyArrow Table — execute, rank, cluster, find, and schema. There are no CypherValue wrappers and no SearchHit objects. Access values via .as_py() or pass the table directly to pandas, Polars, or NetworkX, which all accept Arrow as input.

table = forge.execute("MATCH (p:Person) RETURN p.name, p.age")
# table is a pyarrow.Table — use Arrow, pandas, or Polars to consume it
import pandas as pd
df = table.to_pandas()

Next Steps

• Cypher Guide — complete query language reference
• Graph Construction — build graphs with Python
• Book — architecture, research, and deeper usage
• Architecture Overview — Rust core design