Quick Start
from ison_graph import ISONGraph
from ison_graph.query import QueryEngine
# Create graph and add data
graph = ISONGraph()
graph.add_node('person', 'alice', name='Alice', age=30, city='NYC')
graph.add_node('person', 'bob', name='Bob', age=25, city='LA')
graph.add_edge('KNOWS', ('person', 'alice'), ('person', 'bob'), since=2020)
# Create query engine
engine = QueryEngine(graph)
# Execute string queries
result = engine.execute("NODES person WHERE age > 25")
# Or use fluent API
result = engine.match("person").where("age", ">", 25).execute()NODES Query
Select and filter nodes by type and conditions.
NODES <type> [WHERE <conditions>] [ORDER BY <field> [ASC|DESC]] [LIMIT <n>]Examples
# All person nodes
NODES person
# Filter by age
NODES person WHERE age > 25
# Multiple conditions
NODES person WHERE age > 25 AND city = "NYC"
# With ordering and limit
NODES person WHERE active = true ORDER BY name ASC LIMIT 10
# String matching
NODES person WHERE name STARTS_WITH "A"EDGES Query
Select and filter edges by relationship type.
EDGES <rel_type> [WHERE <conditions>] [LIMIT <n>]Examples
# All KNOWS relationships
EDGES KNOWS
# Filter by property
EDGES KNOWS WHERE since > 2020
# Limit results
EDGES PURCHASED WHERE amount > 100 LIMIT 50TRAVERSE Query
Graph traversal from a starting node.
TRAVERSE <type>:<id> -> <rel_type> -> <target_type> [MAX <hops>]Examples
# Direct neighbors
TRAVERSE person:alice -> KNOWS -> person
# Multi-hop traversal (up to 3 hops)
TRAVERSE person:alice -> KNOWS -> person MAX 3
# Follow any relationship
TRAVERSE person:alice -> * -> * MAX 2PATH Query
Find shortest path between two nodes.
PATH <type>:<id> TO <type>:<id> [VIA <rel_type>] [MAX <hops>]Examples
# Find any path
PATH person:alice TO person:charlie
# Path via specific relationship
PATH person:alice TO person:charlie VIA KNOWS
# With max hops
PATH person:alice TO person:charlie VIA KNOWS MAX 5COUNT Query
Count nodes matching criteria.
COUNT <type> [WHERE <conditions>]Examples
# Count all persons
COUNT person
# Count with filter
COUNT person WHERE age > 25
# Count active users
COUNT user WHERE active = trueAggregation Queries
Compute aggregates on node properties.
SUM|AVG|MIN|MAX <type>.<field> [WHERE <conditions>]Examples
# Average age
AVG person.age
# Sum with filter
SUM order.total WHERE status = "completed"
# Min and max
MIN product.price
MAX product.price WHERE category = "electronics"Operators
| Operator | Description | Example |
|---|---|---|
= | Equal | age = 30 |
!= | Not equal | status != "inactive" |
> | Greater than | age > 25 |
>= | Greater or equal | age >= 18 |
< | Less than | price < 100 |
<= | Less or equal | price <= 50 |
IN | In list | city IN ["NYC", "LA"] |
NOT IN | Not in list | status NOT IN ["banned"] |
CONTAINS | String contains | name CONTAINS "son" |
STARTS_WITH | String prefix | name STARTS_WITH "A" |
ENDS_WITH | String suffix | email ENDS_WITH ".com" |
MATCHES | Regex match | email MATCHES ".*@gmail\\.com" |
EXISTS | Field exists | bio EXISTS |
NOT EXISTS | Field missing | deleted NOT EXISTS |
Fluent API - Node Queries
engine.match("person")
.where("age", ">", 25)
.where("city", "=", "NYC")
.order_by("name", "ASC")
.limit(10)
.execute()Available Methods
| Method | Description |
|---|---|
.where(field, op, value) | Add condition |
.order_by(field, direction) | Sort results |
.limit(n) | Limit results |
.offset(n) | Skip results |
.execute() | Run query |
Fluent API - Edge Queries
engine.match_edges("KNOWS")
.where("since", ">", 2020)
.limit(50)
.execute()Query Result
Query results are iterable and provide metadata:
result = engine.execute("NODES person WHERE age > 25")
# Iterate results
for item in result:
print(item)
# Convert to list
items = result.to_list()
# Get first item
first = result.first()
# Access metadata
print(f"Count: {result.count}")
print(f"Execution time: {result.execution_time_ms}ms")