WITH

It is important to note that WITH affects variables in scope. Any variables not included in the WITH clause are not carried over to the rest of the query.

Introduction

Using WITH, you can manipulate the output before it is passed on to the following query parts. The manipulations can be of the shape and/or number of entries in the result set.

One common usage of WITH is to limit the number of entries that are then passed on to other MATCH clauses. By combining ORDER BY and LIMIT, it’s possible to get the top X entries by some criteria, and then bring in additional data from the graph.

Another use is to filter on aggregated values. WITH is used to introduce aggregates which can then be used in predicates in WHERE. These aggregate expressions create new bindings in the results. WITH can also, like RETURN, alias expressions that are introduced into the results using the aliases as the binding name.

WITH is also used to separate reading from updating of the graph. Every part of a query must be either read-only or write-only. When going from a writing part to a reading part, the switch must be done with a WITH clause.

Graph
  N0 [
    label = "name = \'Anders\'\l"
  ]
  N0 -> N2 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "BLOCKS\n"
  ]
  N0 -> N1 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "KNOWS\n"
  ]
  N1 [
    label = "name = \'Bossman\'\l"
  ]
  N1 -> N3 [
    color = "#2e3436"
    fontcolor = "#2e3436"
    label = "BLOCKS\n"
  ]
  N1 -> N4 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "KNOWS\n"
  ]
  N2 [
    label = "name = \'Caesar\'\l"
  ]
  N2 -> N4 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "KNOWS\n"
  ]
  N3 [
    label = "name = \'David\'\l"
  ]
  N3 -> N0 [
    color = "#4e9a06"
    fontcolor = "#4e9a06"
    label = "KNOWS\n"
  ]
  N4 [
    label = "name = \'George\'\l"
  ]

Filter on aggregate function results

Aggregated results have to pass through a WITH clause to be able to filter on.

Query
MATCH (david { name: 'David' })--(otherPerson)-->()
WITH otherPerson, count(*) AS foaf
WHERE foaf > 1
RETURN otherPerson.name

The name of the person connected to 'David' with the at least more than one outgoing relationship will be returned by the query.

Table 1. Result
otherPerson.name

"Anders"

1 row

Sort results before using collect on them

You can sort your results before passing them to collect, thus sorting the resulting list.

Query
MATCH (n)
WITH n
ORDER BY n.name DESC LIMIT 3
RETURN collect(n.name)

A list of the names of people in reverse order, limited to 3, is returned in a list.

Table 2. Result
collect(n.name)

["George","David","Caesar"]

1 row

You can match paths, limit to a certain number, and then match again using those paths as a base, as well as any number of similar limited searches.

Query
MATCH (n { name: 'Anders' })--(m)
WITH m
ORDER BY m.name DESC LIMIT 1
MATCH (m)--(o)
RETURN o.name

Starting at 'Anders', find all matching nodes, order by name descending and get the top result, then find all the nodes connected to that top result, and return their names.

Table 3. Result
o.name

"Bossman"

"Anders"

2 rows