@dortdb/lang-cypher

A Cypher-based query language plug-in for DortDB. It adds data-selection queries for property graphs, meaning data shaped as nodes connected by relationships. It brings ASCII-art pattern matching and variable-length paths with it.

The language is a set of implementation extensions to Cypher, based on the openCypher grammar. See License and attribution below.

Installation

npm install @dortdb/core @dortdb/lang-cypher graphology

@dortdb/core and Graphology are both peer dependencies. Graphology backs the default data adapter.

Usage

import { DortDB } from '@dortdb/core';
import { defaultRules } from '@dortdb/core/optimizer';
import { Cypher, gaLabelsOrType } from '@dortdb/lang-cypher';
import { MultiDirectedGraph } from 'graphology';

const db = new DortDB({
  mainLang: Cypher({ defaultGraph: 'social' }),
  optimizer: { rules: defaultRules },
});

const graph = new MultiDirectedGraph();
graph.addNode('alice', {
  [gaLabelsOrType]: ['Person'],
  name: 'Alice',
  age: 30,
});
graph.addNode('bob', { [gaLabelsOrType]: ['Person'], name: 'Bob', age: 20 });
graph.addEdge('alice', 'bob', { [gaLabelsOrType]: 'KNOWS' });

db.registerSource(['social'], graph);

const result = db.query('MATCH (p:Person) RETURN p.name AS name ORDER BY name');
// result.data -> [{ name: 'Alice' }, { name: 'Bob' }]

Data adapter

The default adapter queries Graphology graphs. It reads node labels and edge types from the attribute keyed by the gaLabelsOrType symbol. Write { [gaLabelsOrType]: ['Person'] } on a node and { [gaLabelsOrType]: 'KNOWS' } on a relationship. The adapter does not read a plain labels property, so a pattern such as (:Person) then matches nothing and reports no error.

Choose the graph to query with the defaultGraph option, or per query with a FROM clause:

FROM myOtherGraph
MATCH (n)
RETURN n

Dialect

The parser accepts the full openCypher 9 grammar, but only the read subset runs. DortDB selects data and does not write it, so planning rejects the data-writing clauses CREATE, MERGE, SET, REMOVE, and DELETE.

This package implements a subset of the standard Cypher functions. Add your own as an extension, with addAdapterCtx: true if the function needs the graph and its adapter.

Graph traversal indices

Pattern matching built only from scans would ignore the structure of the graph, so this package ships a ConnectionIndex. The index stores nothing itself. It recognizes join conditions between nodes and relationships and resolves the connected elements through the data adapter, which is what makes traversal fast.

import { ConnectionIndex } from '@dortdb/lang-cypher';

db.createIndex(['social', 'nodes'], [], ConnectionIndex);

See Indexing & Performance.

License and attribution

This package derives from the openCypher grammar, which is licensed under the Apache License, Version 2.0, and was created by the collective efforts of the openCypher community.

The openCypher Implementers Group has not approved this work through its public consensus process. Following the openCypher attribution terms, this package is described as implementation extensions to Cypher, not as "Cypher" or "openCypher". Cypher® is a registered trademark of Neo4j, Inc.

The NOTICE file holds the full attribution, and src/parser/cypher.pegjs holds the licensed grammar.

Documentation

See the Cypher overview and the dialect reference, or the full docs at filipjezek.github.io/dortdb.