Home › Getting Started

Getting Started

This guide will help you install gcyphrq and run your first Cypher query against an in-memory graph.

Prerequisites

Installation

Global CLI

npm install -g gcyphrq

This makes the gcyphrq command available globally on your PATH.

Project dependency

npm install gcyphrq

From source

git clone https://github.com/plelevier/gcyphrq.git
cd gcyphrq
npm install
npm run build
npm link

Your First Query

1. Create a graph file

Create a file called social-graph.json:

{
  "nodes": [
    { "key": "alice", "attributes": { "label": "User", "name": "Alice", "age": 30 } },
    { "key": "bob",   "attributes": { "label": "User", "name": "Bob",   "age": 25 } },
    { "key": "charlie","attributes": { "label": "User", "name": "Charlie","age": 35 } }
  ],
  "edges": [
    { "source": "alice", "target": "bob", "attributes": { "type": "FRIEND" } },
    { "source": "bob", "target": "charlie", "attributes": { "type": "FRIEND" } }
  ]
}

2. Run a query

gcyphrq -g social-graph.json -e 'MATCH (u:User) RETURN u.name, u.age'

Output:

[
  { "name": "Alice", "age": 30 },
  { "name": "Bob", "age": 25 },
  { "name": "Charlie", "age": 35 }
]

Note: When the query returns only scalar values (property access, aggregations), the CLI outputs rows format automatically. When returning full nodes or edges, the default output is graph format — a {nodes, edges} structure that can be piped back into gcyphrq. Use --format rows to force row-based output.

3. Pipe to jq

The CLI outputs raw JSON, so you can pipe it directly to jq:

gcyphrq -g social-graph.json -e 'MATCH (u:User) RETURN u.name' | jq '.[].name'

Graph File Format

Graphs use the Graphology JSON format. See examples/README.md for the full specification.

See also the Example Graphs page for ready-to-run queries against bundled graphs.

Reading from stdin

Instead of a file, you can pipe the graph from stdin using -g -:

cat my-graph.json | gcyphrq -g - -e 'MATCH (u:User) RETURN u'

Using as a Library

For programmatic access, import gcyphrq in your TypeScript or Node.js project:

import { executeQuery } from 'gcyphrq';

const graphData = {
  nodes: [
    { key: 'alice', attributes: { label: 'User', name: 'Alice', age: 30 } },
    { key: 'bob', attributes: { label: 'User', name: 'Bob', age: 25 } },
  ],
  edges: [
    { source: 'alice', target: 'bob', attributes: { type: 'FRIEND' } },
  ],
};

const results = await executeQuery(graphData, 'MATCH (u:User) RETURN u.name, u.age');
console.log(results);
// [ { name: 'Alice', age: 30 }, { name: 'Bob', age: 25 } ]

Loading Data from CSV

Build a full graph from CSV files — one for nodes, one for edges — using LOAD CSV with CALL { ... } subqueries. Example CSV files are bundled in examples/csv/.

Pipe an empty graph via stdin and populate it entirely from CSV:

echo '{"nodes":[],"edges":[]}' | gcyphrq -g - -e "CALL { LOAD CSV WITH HEADERS FROM 'examples/csv/services.csv' AS s CREATE (:Service {name: s.name, type: s.type, team: s.team, status: s.status}) RETURN count(*) AS _ } CALL { LOAD CSV WITH HEADERS FROM 'examples/csv/dependencies.csv' AS d MATCH (src:Service {name: d.source}) MATCH (tgt:Service {name: d.target}) CREATE (src)-[:DEPENDS_ON {protocol: d.protocol, latency: toInteger(d.latency_ms)}]->(tgt) RETURN count(*) AS _ } MATCH (a)-[r]->(b) RETURN a, r, b"

See the Query Guide — LOAD CSV for full syntax reference.

Next Steps