ison-graph
ISONGraph - A token-efficient property graph store with ISON persistence for Rust.
Features
- Property Graph Model: Nodes and edges with typed properties
- O(1) Lookups: Fast node access by (type, id)
- Multi-Hop Traversal: 1-hop, N-hop, and range queries
- Path Finding: BFS shortest path
- ISONQL Query Language: Declarative graph queries
- Schema Validation: Type-safe graph constraints
- ISON Persistence: Token-efficient serialization
- Zero Dependencies: Only thiserror and regex
Installation
[]
= "1.4.1"
Quick Start
use ;
API Reference
ISONGraph
let mut graph = new;
let mut graph = undirected;
Node Operations
| Method | Description |
|---|---|
add_node(type, id, props) |
Add a node |
get_node(type, id) |
Get a node |
has_node(type, id) |
Check if exists |
remove_node(type, id) |
Remove node and edges |
update_node(type, id, props) |
Update properties |
node_count() |
Count all nodes |
node_count_of_type(type) |
Count nodes of type |
node_types() |
Get all types |
nodes() |
Iterate over all nodes |
nodes_of_type(type) |
Iterate over nodes of type |
Edge Operations
| Method | Description |
|---|---|
add_edge(rel, src, tgt, props) |
Add an edge |
has_edge(rel, src, tgt) |
Check if exists |
remove_edge(rel, src, tgt) |
Remove edge |
edge_count() |
Count all edges |
edge_count_of_type(type) |
Count edges of type |
ISONGraph is a simple graph: add_edge returns Err(GraphError::DuplicateEdge)
on a repeated (rel_type, source, target) triple - parallel edges aren't
representable, by design (it's what keeps canonical serialization
tie-break-free). Converting from a multigraph source? Dedupe/merge in the
converter before calling add_edge.
| edge_types() | Get all types |
| edges_of_type(type) | Iterate over edges of type |
Traversal
| Method | Description |
|---|---|
neighbors(ref, rel?, dir) |
Get neighbors |
multi_hop(start, rel?, hops, dir) |
N-hop traverse |
multi_hop_range(start, rel?, min, max, dir) |
Range traverse |
Path Finding
| Method | Description |
|---|---|
shortest_path(start, end, rel?, max, dir) |
BFS shortest |
path_exists(start, end, rel?, max, dir) |
Check reachability |
Graph Analysis
| Method | Description |
|---|---|
in_degree(ref) |
Count incoming edges |
out_degree(ref) |
Count outgoing edges |
degree(ref) |
Total degree |
is_connected() |
Check connectivity |
has_cycle(rel?) |
Detect cycles |
Serialization
| Method | Description |
|---|---|
to_ison() |
Serialize to ISON |
to_isonl() |
Serialize to ISONL |
Output is canonical: node/edge type blocks and rows are sorted (ordinal), so the same logical graph always serializes to the same bytes regardless of insertion order - byte-identical with every other ISONGraph language port.
Types
/// Node reference: (type, id)
pub type NodeRef<'a> = ;
/// Owned node reference
/// Traversal direction
Error Handling
use GraphError;
match graph.add_node
ISONQL Query Language
ISONQL is a declarative query language for ISONGraph, providing a pure property graph query interface without external database dependencies.
Basic Usage
use ;
// Create and populate graph
let mut graph = new;
graph.add_node?;
graph.add_node?;
graph.add_node?;
graph.add_node?;
graph.add_edge?;
graph.add_edge?;
graph.add_edge?;
// Create query engine
let engine = new;
// Execute queries
let result = engine.execute?;
println!;
Supported Query Types
NODES - Query Nodes
// All nodes of a type
engine.execute?;
// With WHERE clause
engine.execute?;
// Multiple conditions
engine.execute?;
// OR conditions (AND binds tighter than OR)
engine.execute?;
// With sorting
engine.execute?;
// With pagination
engine.execute?;
// Return specific fields
engine.execute?;
// Shorthand syntax
engine.execute?;
EDGES - Query Edges
// All edges of a type
engine.execute?;
// With WHERE clause on edge properties
engine.execute?;
// With limit
engine.execute?;
TRAVERSE - Graph Traversal
// Single hop outgoing
engine.execute?;
// Single hop incoming
engine.execute?;
// Multi-hop with max depth
engine.execute?;
// Undirected traversal
engine.execute?;
// Any node type
engine.execute?;
PATH - Find Shortest Path
// Find shortest path between nodes
engine.execute?;
// Via specific relationship
engine.execute?;
// With max hops
engine.execute?;
COUNT - Count Nodes
// Count all nodes of a type
engine.execute?;
// Count with filter
engine.execute?;
Aggregations - SUM, AVG, MIN, MAX
// Sum a property
engine.execute?;
// Average with filter
engine.execute?;
// Min value
engine.execute?;
// Max value
engine.execute?;
Query Operators
| Operator | Description | Example |
|---|---|---|
=, == |
Equal | name = Alice |
!=, <> |
Not equal | city != LA |
> |
Greater than | age > 25 |
>= |
Greater or equal | age >= 25 |
< |
Less than | age < 30 |
<= |
Less or equal | age <= 30 |
IN |
In list | city IN (NYC, LA, SF) |
CONTAINS |
Contains substring | name CONTAINS ali |
STARTS_WITH |
Starts with | name STARTS_WITH A |
ENDS_WITH |
Ends with | name ENDS_WITH e |
MATCHES |
Regex match | email MATCHES ^[a-z]+@ |
EXISTS |
Field exists | EXISTS email |
NOT EXISTS |
Field missing | NOT EXISTS phone |
Working with Results
let result = engine.execute?;
// Access result metadata
println!;
println!;
println!;
// Iterate over results
for data in result.iter
Fluent Query Builder
For programmatic query construction, use the fluent builder API:
use QueryEngine;
let engine = new;
// Build and execute query fluently
let result = engine.match_nodes
.where_num
.where_cond
.order_by
.limit
.execute?;
// Count query
let count = engine.match_nodes
.where_cond
.count?;
println!;
// With field selection
let result = engine.match_nodes
.where_num
.return_fields
.offset
.limit
.execute?;
Schema Validation
The schema module provides type-safe graph validation with property constraints, relationship rules, and graph-level constraints.
Basic Usage
use ISONGraph;
use ;
// Define node types
let person = new
.id
.field
.field
.field;
let company = new
.id
.field;
// Define edge types
let knows = new
.from_node
.to_node
.no_self_loop
.unique;
let works_at = new
.from_node
.to_node
.cardinality;
// Build schema
let schema = new
.node_type
.node_type
.edge_type
.edge_type
.no_orphans;
// Validate graph
let mut graph = new;
graph.add_node.unwrap;
graph.add_node.unwrap;
graph.add_edge.unwrap;
let result = schema.validate;
if result.is_valid else
Field Types
StringField
use StringField;
// Basic string field
let field = new;
// Required field
let field = new.required;
// Length constraints
let field = new
.min // Minimum 3 characters
.max; // Maximum 100 characters
// Pattern matching (regex)
let field = new
.pattern; // Must start with capital
// Email validation
let field = new.email;
// Allowed values (enum)
let field = new
.allowed;
IntField
use IntField;
// Basic integer field
let field = new;
// Required
let field = new.required;
// Range constraints
let field = new
.min
.max;
// Or use range()
let field = new.range;
FloatField
use FloatField;
// Basic float field
let field = new;
// With constraints
let field = new
.required
.min
.max;
// Using range
let field = new.range; // e.g., longitude
BoolField
use BoolField;
// Basic boolean field
let field = new;
// Required boolean
let field = new.required;
Node Type Schema
use ;
let person = new
// Validate the ID field
.id
// Define property fields
.field
.field
.field
.field;
Edge Type Schema
use ;
// Basic edge type
let knows = new
.from_node
.to_node;
// With constraints
let works_at = new
.from_node
.to_node
.no_self_loop // Cannot connect node to itself
.unique // No duplicate edges
.cardinality; // Many persons, one company per person
// With edge properties
let reports_to = new
.from_node
.to_node
.no_self_loop
.acyclic // Must be DAG (no cycles)
.field
.field;
// Bidirectional edges
let friends_with = new
.from_node
.to_node
.no_self_loop
.bidirectional; // If A->B exists, B->A must also exist
Edge Constraints
| Constraint | Method | Description |
|---|---|---|
| No Self Loop | .no_self_loop() |
Edge cannot connect node to itself |
| Unique | .unique() |
No duplicate edges between same pair |
| Acyclic | .acyclic() |
Must form DAG (no cycles) |
| Bidirectional | .bidirectional() |
Reverse edge must exist |
| Cardinality | .cardinality(card) |
Relationship cardinality |
Cardinality Constraints
use Cardinality;
// One-to-One: Each source has exactly one target, each target has one source
// Example: person HAS_PASSPORT passport
new
.cardinality;
// One-to-Many: One source to many targets, each target has one source
// Example: company HAS_DEPARTMENT department
new
.cardinality;
// Many-to-One: Many sources to one target
// Example: person WORKS_AT company (many employees, one company per person)
new
.cardinality;
// Many-to-Many: No restrictions (default)
// Example: person KNOWS person
new
.cardinality;
Graph-Level Constraints
use GraphSchema;
let schema = new
.node_type
.edge_type
// Graph must be connected (all nodes reachable)
.connected
// No orphan nodes (all nodes must have at least one edge)
.no_orphans
// Maximum depth constraint
.max_depth;
Validation Results
let result = schema.validate;
// Check validity
if result.is_valid
// Access errors
for error in result.errors
// Access warnings
for warning in result.warnings
Error Codes
| Code | Description |
|---|---|
REQUIRED_FIELD |
Required field is missing |
INVALID_TYPE |
Value type doesn't match schema |
MIN_VALUE |
Value below minimum |
MAX_VALUE |
Value above maximum |
MIN_LENGTH |
String too short |
MAX_LENGTH |
String too long |
PATTERN_MISMATCH |
Doesn't match regex pattern |
INVALID_EMAIL |
Not a valid email format |
INVALID_ENUM |
Value not in allowed list |
REF_NOT_FOUND |
Referenced node doesn't exist |
REF_WRONG_TYPE |
Referenced node is wrong type |
SELF_LOOP |
Self-loop not allowed |
DUPLICATE_EDGE |
Duplicate edge (when unique) |
CARDINALITY_VIOLATION |
Cardinality constraint violated |
INVALID_SOURCE_TYPE |
Edge source is wrong node type |
INVALID_TARGET_TYPE |
Edge target is wrong node type |
CYCLE_DETECTED |
Cycle found (when acyclic required) |
NOT_CONNECTED |
Graph is not connected |
ORPHAN_NODE |
Node has no edges |
MAX_DEPTH_EXCEEDED |
Graph depth exceeds limit |
Complete Example
use ISONGraph;
use ;
// Define node types
let user = new
.id
.field
.field
.field;
let post = new
.id
.field
.field
.field;
let comment = new
.id
.field;
// Define edge types
let follows = new
.from_node
.to_node
.no_self_loop;
let authored = new
.from_node
.to_node
.cardinality;
let commented_on = new
.from_node
.to_node
.cardinality;
let wrote_comment = new
.from_node
.to_node
.cardinality;
// Build schema
let schema = new
.node_type
.node_type
.node_type
.edge_type
.edge_type
.edge_type
.edge_type;
// Create and populate graph
let mut graph = new;
graph.add_node.unwrap;
graph.add_node.unwrap;
graph.add_node.unwrap;
graph.add_edge.unwrap;
graph.add_edge.unwrap;
// Validate
let result = schema.validate;
if result.is_valid else
ISON Format
ISONGraph uses a token-efficient serialization format:
edges.KNOWS
since source target
2020 :person:1 :person:2
nodes.person
id age name
1 30 Alice
2 25 Bob
ISONL (Line-Oriented Format)
For streaming/appending:
edges.KNOWS|since source target|2020 :person:1 :person:2
nodes.person|id age name|1 null Alice
nodes.person|id age name|2 25 Bob
Rows in a block share the block's full field set, padded with null where a
node lacks a property - the canonical writer decides the columns, so two rows
of the same type always line up.
License
MIT License - see LICENSE for details.