Create accepts a single pattern, a list of patterns or a list of a list of patterns. Each pattern represents a single part of a cypher pattern. For example: (people:Person { age: 30 }) would be a node pattern and -[:FriendsWith]-> would be a relationship pattern.

If an array of patterns is provided, they are joined together to form a composite pattern. For example:

query.create([
  node('people', 'Person', { age: 30 }),
  relation('out', '', 'FriendsWith'),
  node('friend', 'Friend'),
])

Would equate to the cypher pattern

CREATE (people:Person { age: 30 })-[:FriendsWith]->(friend:Friend)

The create method also accepts a unique option which will cause a CREATE UNIQUE clause to be emitted instead.

query.create([node('people', 'Person', { age: 30 })], { unique: true });
// CREATE UNIQUE (people:Person { age: 30 })

Delete accepts a single string or an array of them and all of them are joined together with commas. Note that these strings are not escaped or passed to Neo4j using parameters, therefore you should not pass user input into this clause without escaping it first.

You can set detach: true in the options to make it a DETACH DELETE clause.

Match accepts a single pattern, a list of patterns or a list of a list of patterns. Each pattern represents a single part of a cypher pattern. For example: (people:Person { age: 30 }) would be a node pattern and -[:FriendsWith]-> would be a relationship pattern.

If an array of patterns is provided, they are joined together to form a composite pattern. For example:

query.match([
  node('people', 'Person', { age: 30 }),
  relation('out', '', 'FriendsWith'),
  node('friends'),
])

Would equate to the cypher pattern

MATCH (people:Person { age: 30 })-[:FriendsWith]->(friends)

If an array of an array of patterns is provided each array is joined together like above, and then each composite pattern is joined with a comma to allow matching of multiple distinct patterns. Note: matching many distinct patterns will produce a cross product of the results as noted in the cypher docs.

You can also provide optional: true in the options to create and OPTIONAL MATCH clause.

query.merge([
  node('user', 'User', { id: 1 }),
  relation('out', 'rel', 'OwnsProject'),
  node('project', 'Project', { id: 20 }),
])
.onMatch.setVariables({ 'rel.updatedAt': `timestamp` });
// MERGE (user:User { id: 1 })-[rel:OwnsProject]->(project:Project { id: 20 })
// ON MATCH SET rel.updatedAt = timestamp()

Pass a single string or an array of strings to order by.

query.orderBy([
  'name',
  'occupation',
])
// ORDER BY name, occupation

You can control the sort direction by adding a direction to each property.

query.orderBy([
  ['name', 'DESC'],
  'occupation', // Same as ['occupation', 'ASC']
])
// ORDER BY name DESC, occupation

The second parameter is the default search direction for all properties that don't have a direction specified. So the above query could instead be written as:

query.orderBy([
  'name',
  ['occupation', 'ASC']
], 'DESC')
// ORDER BY name DESC, occupation

It is also acceptable to pass an object where each key is the property and the value is a direction. Eg:

query.orderBy({
  name: 'DESC',
  occupation: 'ASC',
})

However, the underlying iteration order is not always guaranteed and it may cause subtle bugs in your code. It is still accepted but it is recommended that you use the array syntax above.

Valid values for directions are DESC, DESCENDING, ASC, ASCENDING. true and false are also accepted (true being the same as DESC and false the same as ASC), however they should be avoided as they are quite ambiguous. Directions always default to ASC as it does in cypher.

query.raw('MATCH (:Event { date: $date }', { date: '2017-01-01' })

raw can also be used as a template tag

query.matchNode('event', 'Event', { id: 1 })
 .raw`SET event.finishedAt = ${Date.now()}`

But note that using template parameters where they are not supported in a query will produce an malformed query.

query.raw`SET node.${property} = 'value'`
// Invalid query:
// SET node.$param1 = 'value'

Pass objects containing the list of properties and labels to remove from a node. Each key in an object is the name of a node and the values are the names of the labels and properties to remove. The values of each object can be either a single string, or an array of strings.

query.remove({
  labels: {
    coupon: 'Active',
  },
  properties: {
    customer: ['inactive', 'new'],
  },
});
// REMOVE coupon:Active, customer.inactive, customer.new

Both labels and properties objects are optional, but you must provide at least one of them for the query to be syntatically valid.

query.remove({

});
// Invalid query:
// REMOVE

If you only need to remove labels or properties, you may find removeProperties or removeLabels more convenient.

Pass an object containing the list of labels to remove from a node. Each key in the object is the name of a node and the values are the names of the labels to remove. The values can be either a single string, or an array of strings.

query.remove({
  customer: ['Inactive', 'New'],
  coupon: 'Available',
});
// REMOVE customer:Inactive, customer:New, coupon:Available

Pass an object containing the list of properties to remove from a node. Each key in the object is the name of a node and the values are the names of the properties to remove. The values can be either a single string, or an array of strings.

query.remove({
  customer: ['inactive', 'new'],
  coupon: 'available',
});
// REMOVE customer.inactive, customer.new, coupon.available

There are many different ways to pass arguments to return so each is documented in turn below.

A single string:

query.return('people')
// RETURN people

An array of strings to return multiple variables:

query.return([ 'people', 'pets' ])
// RETURN people, pets

A single object to rename variables:

query.return({ people: 'employees' })
// RETURN people AS employees

A single object with an array for each value:

query.return({
  people: [ 'name', 'age' ],
  pets: [ 'name', 'breed' ],
})
// RETURN people.name, people.age, pets.name, pets.breed

This gives you a shortcut to specifying many node properties. You can also rename each property by adding an object inside the array or by providing an object as the value:

query.return({
  people: [{ name: 'personName' }, 'age' ],
})
// RETURN people.name AS personName, people.age

or

query.return({
  people: {
    name: 'personName',
    age: 'personAge',
  },
})
// RETURN people.name AS personName, people.age AS personAge

You can also pass an array of any of the above methods.

The return method also accepts a distinct option which will cause a RETURN DISTINCT clause to be emitted instead.

query.return('people', { distinct: true })
// RETURN DISTINCT people

set lets you updates a nodes labels and properties in one clause. Most of the time it will be easier to use one of the variants such as setLabels, setValues or setVariables.

This function accepts three different kind of properties, each of which is described in more detail in the variants.

query.set({
  labels: {
    sale: 'Active',
  },
  variables: {
    sale: {
      activatedAt: 'timestamp()',
    },
  },
  values: {
    sale: {
      activatedBy: user.id,
    },
  },
})
// SET sale:Active, sale.activatedAt = timestamp(), sale.activatedBy = $userId

set also accepts an options object which currently only contains a single setting: override. Override controls whether the = or += operator is used in the set clause. true causes the existing object to be cleared and replaced by the new object. false on the other hand will merge the existing and new objects together, with new properties replacing the ones on the existing object. The default value of override is a little inconsistent and it will be improved in the next major version. If you don't pass any settings object, override will default to true. If you pass an options object without an override key, override will be false. In future versions, override will always default to false to be more consistent with setVariables and setValues.

query.setLabels({
  sale: 'Active',
})
// SET sale:Active

setLabels accepts a dictionary where the keys are nodes to be updated and the value is a single label or an array of labels to add to the node.

query.setValues({
  'sale.activatedBy': user.id,
})
// SET sale.activatedBy += $userId

setValues accepts a dictionary where the keys are nodes or property names to be updated.

To use the += operator to merge properties of a node, you can pass true to the merge option.

query.setValues({
  'sale': { active: true },
}, true)
// SET sale += $sale

query.setVariables({
  'sale.activatedAt': 'timestamp()',
})
// SET sale.activatedAt = timestamp()

Note how values are inserted into the query, as is.

To use the += operator to merge properties of a node, you can pass true to the merge option.

query.setVariables({
  'sale': 'newSaleDetails'
}, true)
// SET sale += newSaleDetails

query.matchNode('people', 'People')
  .return({ 'people.name': 'name' })
  .union()
  .matchNode('departments', 'Department')
  .return({ 'departments.name': 'name' });
// MATCH (people:People)
// RETURN people.name AS name
// UNION
// MATCH (departments:Department)
// RETURN departments.name AS name

query.matchNode('people', 'People')
  .return({ 'people.name': 'name' })
  .unionAll()
  .matchNode('departments', 'Department')
  .return({ 'departments.name': 'name' });
// MATCH (people:People)
// RETURN people.name AS name
// UNION ALL
// MATCH (departments:Department)
// RETURN departments.name AS name

where is probably the most complex clause in this package because of the flexible ways to combine conditions. A handy rule of thumb is when you see an array it becomes an OR and when you see a dictionary, it becomes an AND. The many different ways of specifying your constraints are listed below.

As a simple object, the comparison of each property is just ANDed together.

query.where({
  name: 'Alan',
  age: 54,
})
// WHERE name = 'Alan' AND age = 54

You can wrap your constraints in a top level dictionary in which case the key of the outer dictionary will be considered the name of the node.

query.where({
  person: {
    name: 'Alan',
    age: 54,
  },
})
// WHERE person.name = 'Alan' AND person.age = 54

Using an array, you can generate ORed conditions.

query.where([
  { name: 'Alan' },
  { age: 54 },
])
// WHERE name = 'Alan' OR age = 54

Arrays can be placed at many levels in the conditions.

query.where({
  name: [ 'Alan', 'Steve', 'Bob' ],
})
// WHERE name = 'Alan' OR name = 'Steve' OR name = 'Bob'

query.where({
  person: [
    { name: 'Alan' },
    { age: 54 },
  ],
})
// WHERE person.name = 'Alan' OR person.age = 54

query.where([
  { employee: { name: 'Alan' } },
  { department: { code: 765 } },
})
// WHERE employee.name = 'Alan' OR department.code = 765

For more complex comparisons, you can use the comparator functions such as:

query.where({
  age: greaterThan(30),
})
// WHERE age > 30

The full list of comparators currently supported are:

• between
• contains
• endsWith
• equals
• exists
• greaterEqualTo
• greaterThan
• hasLabel
• inArray
• isNull
• lessEqualTo
• lessThan
• regexp
• startsWith

You can import the comparisons one at a time or all at once.

import { greaterThan, regexp } from 'cypher-query-builder';
// or
import { comparisons } form 'cypher-query-builder';

For convenience you can also pass a Javascript RegExp object as a value, which will then be converted into a string before it is passed to cypher. However, beware that the cypher regexp syntax is inherited from java, and may have slight differences to the Javascript syntax. If you would prefer, you can use the regexp comparator and use strings instead of RegExp objects. For example, Javascript RegExp flags will not be preserved when sent to cypher.

query.where({
  name: /[A-Z].*son/,
})
// WHERE age =~ '[A-Z].*son'

All the binary operators including xor and not are available as well and can also be imported individually or all at once.

import { xor, and } from 'cypher-query-builder';
// or
import { operators } form 'cypher-query-builder';

The operators can be placed at any level of the query.

query.where({
  age: xor([lessThan(12), greaterThan(65)])
})
// WHERE age < 12 XOR age > 65

There are many different ways to pass arguments to with so each is documented in turn below.

A single string:

query.with('people')
// WITH people

An array of strings to return multiple variables:

query.with([ 'people', 'pets' ])
// WITH people, pets

A single object to rename variables:

query.with({ people: 'employees' })
// WITH people AS employees

A single object with an array for each value:

query.with({
  people: [ 'name', 'age' ],
  pets: [ 'name', 'breed' ],
})
// WITH people.name, people.age, pets.name, pets.breed

This gives you a shortcut to specifying many node properties. You can also rename each property by adding an object inside the array or by providing an object as the value:

query.with({
  people: [{ name: 'personName' }, 'age' ],
})
// WITH people.name AS personName, people.age

or

query.with({
  people: {
    name: 'personName',
    age: 'personAge',
  },
})
// WITH people.name AS personName, people.age AS personAge

You can also pass an array of any of the above methods.