Guides¶

KGLite has a set of how-to guides. Most projects only need three.

Coming from 0.13? The code-graph builder (now codingest) and dataset loaders (now kglite-datasets) moved out of the wheel in 0.14 — see the 0.13 → 0.14 migration guide.

Start here (the load-bearing path)¶

Every project that loads its own data and queries it goes through these three, in this order:


Data Loading	Shape DataFrames, bulk-load with `add_nodes` / `add_connections`, conflict handling, hierarchies. The day-1 “I have a CSV, now what?” answer.
Cypher Queries	The query surface — MATCH/WHERE/RETURN, aggregations, subqueries, mutations. Every other guide leans on this one.
MCP Servers	Ship the graph to Claude / Cursor / any MCP-capable agent. The bundled `kglite-mcp-server` CLI + the YAML manifest for adding custom tools without forking.
Authoring MCP skills	Teach agents how and when to use each tool with bundled/operator skills — methodology that injects into tool descriptions, gated per-graph. Use this instead of hand-rolling `instructions:`.

Add as needed¶

Domain-specific surfaces — pull them in when your data has the shape:

Guide	Read this if…
Durable embedded apps	…the graph is long-lived state your app reopens across runs. `open()` load-or-create lifecycle, checkpoint-on-close, and crash-safe `durable=True` write-ahead-log writes.
OKF Ingestion	…your “data” is a markdown knowledge base — an OKF bundle, a Claude memory dir, a skills folder, an Obsidian vault. Frontmatter → nodes, links → typed edges.
Spatial Operations	…your nodes have coordinates. R-tree indexing, distance-based filters, GeoJSON I/O.
Timeseries	…property values change over time. Snapshot history, valid_at / valid_during temporal filters.
Semantic Search	…you want fuzzy / meaning-based lookup. `text_score()` in Cypher, embedding model registration.
Graph Algorithms	…you need PageRank, community detection, shortest paths, centrality.
Traversal Hierarchy	…your graph has parent-child / ancestor structure. `set_parent_type`, `*` walks, hierarchical Cypher.

Power-user / less common¶

Guide	When
Querying (Fluent API)	The fluent-API alternative to Cypher (`select` / `where` / `traverse` / `collect`). Useful for programmatic graph construction.
Blueprints	Declarative graph schemas — nodes/edges defined once in a CSV-driven config. Best for repeated builds of the same shape.
Import and Export	Round-trip with Neo4j, JSON, N-Triples; CSV bulk export.
Using with AI Agents	`describe()` XML schema for system prompts. Read this if you’re building agent stacks beyond MCP.
Common Recipes	Short snippets for “how do I do X” patterns that span multiple guides.

If you want to know why¶

Background reading — not required, but the design decisions explain why APIs look the way they do:

Core Concepts — storage modes (memory / mapped / disk), return types, the fluent / Cypher split.
Architecture — Rust core + PyO3 bindings + petgraph, where each subsystem lives.
Design decisions — the label model, columnar storage, Cypher subset choices.