FROM PREVIOUS

Generic Description

FROM PREVIOUS imports the result rows from the immediately previous statement in a semicolon-delimited Cypher script. It must be the first clause of the statement that consumes those rows.

MATCH (u:User) RETURN u.uid AS uid, u.name AS name;

FROM PREVIOUS AS row
MATCH (o:Order {user_uid: row.uid})
RETURN row.name AS name, o.order_id AS order_id

Consumer-Level Explanation

Use FROM PREVIOUS AS row when the output of one statement should become the input table for the next statement. Each imported row is exposed as a map. The map keys are the column names returned by the previous statement.

If the previous statement returns uid and name, the next statement can read row.uid and row.name.

More Detailed Explanation

FROM PREVIOUS creates one input row per previous result row. The alias names that row map, not each individual column. This keeps the handoff explicit and avoids accidentally merging column scopes from separate statements.

The clause is script-local:

• it requires a previous statement result in the same submitted script
• it can only refer to the immediately previous statement
• it must appear before MATCH, WITH, RETURN, CALL, writes, or any other clause in the consuming statement
• it is read-only by itself, though the consuming statement may still include normal read or write clauses according to the surrounding execution rules

Advanced Example

MATCH (d:Document)
WHERE cosine_similarity(d.embedding, vector([0.22, 0.18, 0.44])) > 0.82
RETURN d.doc_id AS doc_id, d.title AS title;

FROM PREVIOUS AS hit
MATCH (d:Document {doc_id: hit.doc_id})-[:MENTIONS]->(p:Person)
RETURN
  hit.title AS document_title,
  p.name AS person,
  count(*) AS mentions
ORDER BY mentions DESC, person

The first statement performs a semantic-style narrowing step. The second statement uses only those result rows to expand into the graph and produce a relationship-oriented result.

Real Use Cases

• Feed a small candidate set from a semantic, vector, temporal, or analytical lookup into a graph expansion.
• Compute a global comparison value, such as latest timestamp, maximum score, average spend, cohort baseline, or threshold, once and compare later graph rows against it.
• Keep a staged assistant query readable when the first result shape is easier to inspect as a named map.
• Join previous business identifiers to graph nodes without relying on hidden server-side state or frontend-side orchestration.
• Chain a write verification read after a preceding statement that returned affected identifiers.

Real Limitations And Tradeoffs

• FROM PREVIOUS is not a global script variable store. It carries only the immediately previous statement's rows.
• The imported alias is a map value, so field names depend on explicit previous result column aliases. Prefer RETURN expression AS stable_name before consuming the result.
• Large previous results are materialized before the next statement consumes them. Keep the previous statement selective when using it as a handoff. The runtime avoids cloning previous result rows while handing them to the next statement, but the rows still need to fit the normal materialized result budget.
• It is not available inside a normal single statement or inside CALL { ... } as a substitute for WITH; use normal Cypher scoping within one statement.
• Running FROM PREVIOUS as the first statement is a semantic error because there is no previous result to import.