LET

Overview

The LET statement allows you to define new variables and adds corresponding columns to the intermediate result table. Each variable is assigned a value using the = operator.

Syntax
<let statement> ::= 
  "LET" <let variable definition> [ { "," <let variable definition> }... ]

<let variable definition> ::= 
  <variable> "=" <value expression>

Details

• LET adds new columns to the intermediate result table without changing the number of rows.
• Re-defining an existing variable in LET overwrites its value. See Redefining Variables.
• Variables in a single LET are evaluated left to right, so a definition may reference a sibling defined before it. See Referencing Sibling Variables.

Example Graph

Create this graph, run the following query against an empty graph:

GQL
INSERT (p1:Paper {_id:'P1', title:'Efficient Graph Search', score:6}),
       (p2:Paper {_id:'P2', title:'Optimizing Queries', score:9}),
       (p3:Paper {_id:'P3', title:'Path Patterns', score:7}),
       (p1)-[:Cites]->(p2),
       (p2)-[:Cites]->(p3)

Defining Variables

GQL
LET threshold = 7
MATCH (p:Paper) WHERE p.score > threshold
RETURN p.title, p.score - threshold

Result:

Referencing Sibling Variables

Variable definitions in a single LET are evaluated left to right, so a definition may reference a sibling defined before it in the same statement:

GQL
MATCH (p:Paper)
LET base = p.score, doubled = base * 2
RETURN p.title, base, doubled ORDER BY base

Result:

Only backward references resolve. A variable referenced before its own definition is not yet bound, and the expression evaluates to null rather than raising an error:

GQL
LET y = x + 1, x = 5
RETURN x, y        -- x is 5, y is null

Write the definitions in dependency order, or use separate LET statements, which are always evaluated in sequence:

GQL
LET x = 5
LET y = x + 1
RETURN x, y        -- 5, 6

NOTE

Portability. Sibling references are the opposite of SQL's SELECT list and Cypher's WITH, where a name defined in the same clause is not visible to its siblings (WITH 1 AS x, x + 1 AS y is an error in Cypher). GQL's LET is a standalone statement rather than a projection list, so the analogy is weak — but a query ported from Cypher that relies on siblings not being visible will behave differently here. Separate LET statements carry the same meaning everywhere.

Redefining Variables

A variable that is already defined can be redefined by a later LET. The new value replaces the old one in the same column, and no extra column is added. Since values are immutable, this is also the way to derive an updated value from an existing one: the new definition may reference the variable being redefined, in which case it reads the old value row by row.

GQL
MATCH (p:Paper)
LET s = p.score
LET s = s * 2
RETURN p.title, s

Result:

The same applies to a RECORD. Use the record merge operator + to produce an updated record, where the field values on the right-hand side win:

GQL
LET conf = {retries: 3, timeout: 30}
LET conf = conf + {timeout: 60, verbose: true}
RETURN conf

Result:

The redefined value may be of a different type than the original, and if the same variable is defined more than once within a single LET, the last definition wins:

GQL
LET x = 1
LET x = 'abc'      -- INTEGER redefined as STRING
RETURN x           -- 'abc'

GQL
LET x = 1, x = 2
RETURN x           -- 2

A variable bound to a node or an edge can be redefined by LET as well. As it no longer references a graph element afterwards:

GQL
MATCH (n:Paper {_id: 'P1'})
LET n = 5
RETURN n           -- 5

Redefinition is an extension to the GQL standard, which requires each variable defined by LET to be new to the intermediate result table. Use distinct variable names to keep queries portable.

Using Queries in LET

You can assign the result of a subquery to a variable using VALUE { ... }:

GQL
MATCH (p:Paper)
LET avgScore = VALUE { MATCH (p2:Paper) RETURN avg(p2.score) }
FILTER p.score > avgScore
RETURN p.title, p.score

Result:

Referencing Variables in LET

If any variable is referenced in LET, it will be evaluated it row by row.

This query references x in LET and determines whether its score property is greater than 7:

GQL
MATCH (x:Paper)
LET recommended = x.score > 7
RETURN x.title, recommended

It is equivalent to:

GQL
MATCH (x:Paper)
CALL (x) {
  LET recommended = x.score > 7
  RETURN x, recommended
}
RETURN x.title, recommended

Result: