@neo4j/cypher-builder

Cypher Builder

Cypher Builder is a JavaScript programmatic API to create Cypher queries for Neo4j.

• Documentation

import Cypher from "@neo4j/cypher-builder";

const movieNode = new Cypher.Node();
const pattern = new Cypher.Pattern(movieNode, { labels: ["Movie"] });

const matchQuery = new Cypher.Match(pattern)
    .where(movieNode, {
        title: new Cypher.Param("The Matrix"),
    })
    .return(movieNode.property("title"));

const { cypher, params } = matchQuery.build();

console.log(cypher);
console.log(params);

Cypher

MATCH (this0:Movie)
WHERE this0.title = $param0
RETURN this0.title

Params

{
    "param0": "The Matrix",
}

Examples

You can find usage examples in the examples folder.

This library is for JavaScript and TypeScript only. If you are using Java, check Neo4j Cypher DSL.

Changelog

2.0.0

Major Changes

• #389 88f4928 Thanks @angrykoala! - Patterns no longer create a variable by default

  const pattern = new Cypher.Pattern();
  

  Before:

  (this0)
  

  Now:

  ()
  

• #390 038d8b5 Thanks @angrykoala! - Clause build options are now passed as an object rather than parameters:

  myClause.build({
      prefix: "another-this",
      extraParams: {
          myParam: "hello",
      },
      labelOperator: "&",
  });
  

  All parameters are optional, and build can still be called without parameters

• #389 f5135f5 Thanks @angrykoala! - Remove support for adding new columns into an existing with clause with .with, the method addColumns should be used instead

• #408 bba9d81 Thanks @angrykoala! - Escape literal strings if they contain invalid characters:

  new Cypher.Literal(`Hello "World"`);
  

  Would get translated into the following Cypher:

  "Hello \"World\""
  

• #409 adf599f Thanks @angrykoala! - Cypher.Raw no longer exposes Cypher.Environment variable. It provides a CypherRawContext instance with a compile method to compile nested elements in custom cypher instead

• #407 88a300a Thanks @angrykoala! - Remove method Cypher.concat, Cypher.utils.concat should be used instead

• #447 b82be57 Thanks @angrykoala! - Remove Path and NamedPath in favor of PathVariable and NamedPathVariable

• #389 f5135f5 Thanks @angrykoala! - Removes the following deprecated features:

  • pointDistance
  • utils.compileCypher
  • RawCypher
  • onCreate method in Merge clauses
  • innerWith method in Call clauses
  • PatternComprehension second parameter
  • cdc namespace:
    • cdc.current
    • cdc.earliest
    • cdc.query
  • rTrim and lTrim
  • Pattern.withoutLabels
  • Pattern.withoutVariable
  • Pattern.withProperties
  • Pattern.withVariables
  • Pattern.related().withoutType
  • Pattern.related().withDirection
  • Pattern.related().withLength
  • Pattern.related().getVariables
  • Relationship.type
  • Labels, types and properties in Node and Relationship classes
  • Using Node directly in constructor of clauses

• #453 f8a8120 Thanks @angrykoala! - Remove support for fine-grained prefix configuration

  No longer supported:

  myClause.build({
      variable: "var_prefix_",
      params: "param_prefix_",
  });
  

• #410 961933f Thanks @angrykoala! - Removes previous argument from Pattern constructor. This argument was never meant to be used externally and now it is not accessible

• #391 d416ee6 Thanks @angrykoala! - Fix TypeScript typings for boolean operators when using array spread:

  • Cypher.and
  • Cypher.or
  • Cypher.xor

  The following:

  const predicates: Cypher.Predicate[] = [];
  const andPredicate = Cypher.and(...predicates);
  

  Will now return the correct type Cypher.Predicate | undefined. This change means that additional checks may be needed when using boolean operators:

  const predicates = [Cypher.true, Cypher.false];
  const andPredicate = Cypher.and(...predicates); // type Cypher.Predicate | undefined
  

  Passing parameters without spread will still return a defined type

• #447 b82be57 Thanks @angrykoala! - Remove assignToPath method from clauses, in favor of assignTo in Patterns for the following clauses:

  • Match
  • Merge
  • Create

  Before:

  new Cypher.Match(pattern).assignToPath(pathVariable).return(pathVariable);
  

  Now:

  new Cypher.Match(pattern.assignTo(pathVariable)).return(pathVariable);
  

  Generates the Cypher:

  MATCH p = ()-[]-()
  RETURN p
  

Patch Changes

• #389 f5135f5 Thanks @angrykoala! - Improves error message when multiple clauses are added to the same clause

• #389 f5135f5 Thanks @angrykoala! - Add support for passing an existing With clause to With.with

• #448 253a6df Thanks @angrykoala! - Support for Variable | undefined as an input for Patterns