gcyphrq
A Cypher graph query engine for in-memory graphs. Parse a graph from JSON, run a Cypher query, get raw JSON results.
🔍 Cypher Queries
Full support for MATCH, OPTIONAL MATCH, WHERE, WITH, RETURN, ORDER BY, SKIP, LIMIT, and mutations.
📐 Variable-Length Paths
Traverse graphs with variable-depth paths like -[r:FRIEND*1..3]- to explore connections at any depth.
📦 CLI & Library
Use as a CLI tool for quick queries or import as a TypeScript/Node.js library in your projects.
📊 Aggregations
Group and aggregate with count(), sum(), avg(), min(), max() and implicit grouping via WITH pipelining.
🔤 Scalar Functions
Transform values with toLower(), toUpper(), substring(), split(), trim(), length(), coalesce(), and more. Works in RETURN, WHERE, WITH, and ORDER BY.
🔢 Arithmetic
Calculate with +, -, *, /, %, ^ and unary -/+. Parentheses for grouping. Null propagation and safe division.
🔀 CASE Expressions
Conditional logic with CASE WHEN ... THEN ... and CASE expr WHEN val THEN .... Nested CASE, works in RETURN, WHERE, WITH, ORDER BY, and SET.
📋 List Operations
List functions head(), tail(), last(), reverse(), size() and slicing [start..end] with negative index support.
✏️ Mutations
Create, update, delete, and remove labels or properties with CREATE, SET, DELETE, and REMOVE clauses.
🔧 TypeScript
Full type declarations shipped with the package. Works seamlessly in TypeScript projects.
🛤️ Shortest Paths
Find optimal routes with shortestPath((a)-[*]->(b)) for a single path or allShortestPaths((a)-[*]->(b)) for all paths of minimum length. Supports type filtering, direction control, and variable-length bounds.
📞 CALL Subqueries
Inline subqueries with CALL { ... } syntax. Reference outer variables, use YIELD to filter exposed columns, and nest subqueries.
📄 LOAD CSV
Import data from CSV files or HTTP/HTTPS URLs. Supports WITH HEADERS, custom delimiters, and works with CREATE, MATCH, and aggregations.
Quick Start
Install and run your first query in seconds:
# Install globally
npm install -g gcyphrq
# Run a query against a JSON graph
gcyphrq -g my-graph.json -e 'MATCH (u:User) RETURN u.name'
Or use it as a library:
import { executeQuery } from 'gcyphrq';
const results = await executeQuery(graphData, 'MATCH (u:User) RETURN u.name');
Supported Cypher Features
| Feature | Status |
|---|---|
MATCH with node labels and properties |
✅ |
Multi-hop patterns MATCH (a)-[]->(b)-[]->(c) |
✅ |
Variable-length paths *min..max |
✅ |
Directional edges ->, <-, - |
✅ |
OPTIONAL MATCH |
✅ |
RETURN with aliases |
✅ |
WITH + implicit grouping |
✅ |
count(), sum(), avg(), min(), max() aggregations |
✅ |
Scalar functions (toLower, toUpper, substring, split, repl, trim, length, coalesce, head, last, tail, reverse, size, id, labels (sole RETURN), labelsOf (everywhere), nodes, relationships, reltype, toString, toInteger, toFloat) |
✅ |
Arithmetic expressions (+, -, *, /, %, ^, unary +/-) |
✅ |
List literals ['a', 'b'] |
✅ |
List slicing [start..end], [..end], [start..], [index] with negative indices |
✅ |
WHERE (on MATCH and WITH) |
✅ |
WHERE operators: =, <>, >, >=, <, <=, CONTAINS |
✅ |
WHERE logical operators: AND, OR, NOT |
✅ |
WHERE IS NULL / IS NOT NULL |
✅ |
CREATE, SET, DELETE, DETACH DELETE, REMOVE mutations (including multi-hop chains) |
✅ |
FOREACH (SET, CREATE, DELETE, DETACH DELETE, REMOVE on nodes and edges) |
✅ |
CASE ... WHEN ... END (general and simple forms, nested) |
✅ |
ORDER BY (single/multi-column) |
✅ |
SKIP / LIMIT |
✅ |
shortestPath((a)-[*]->(b)) / allShortestPaths((a)-[*]->(b)) path expressions |
✅ |
CALL { ... } subqueries (inline, YIELD, nested) |
✅ |
LOAD CSV (file paths, HTTP/HTTPS URLs, WITH HEADERS, custom delimiters) |
✅ |
| Stored procedures, APOC | ❌ |
Example Graphs
Two example graphs are bundled with the package:
social-graph.json— A small social network with three users connected byFRIENDrelationshipscloud-infra.json— A full startup cloud infrastructure with 51 nodes and 142 edges
See the Examples page for 30 ready-to-run queries with sample output.