parser

func IsAutoParam ¶ added in v0.11.0

func IsAutoParam(name string) bool

IsAutoParam reports whether name was produced by StripLiterals.

It exists because an auto-parameter must behave like the LITERAL it replaced, not like a parameter the caller supplied. The engine deliberately surfaces a type-incompatible user parameter as a typed error rather than silently matching nothing, while openCypher says a type-incompatible literal simply compares false and yields zero rows. Hoisting must not convert the second behaviour into the first, so the parameter type check skips these names.

func Parse ¶

func Parse(query string) (ast.Query, error)

Parse lexes and parses a Cypher query string and converts the resulting parse tree into a typed AST node. It returns the first error encountered.

Errors:

• *ParseError — syntax error from the ANTLR lexer/parser.
• *SemaError — unsupported grammar rule encountered during tree walking.

package main

import (
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)

func main() {
	q, err := parser.Parse("MATCH (n:Person) RETURN n.name")
	if err != nil {
		fmt.Println("error:", err)
		return
	}
	fmt.Println("ok, type:", fmt.Sprintf("%T", q))
}

Output:
ok, type: *ast.SingleQuery

package main

import (
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher/ast"
	"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)

func main() {
	q, err := parser.Parse("MATCH (n:Person) RETURN n.name")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	sq, ok := q.(*ast.SingleQuery)
	if !ok {
		fmt.Printf("unexpected root: %T\n", q)
		return
	}

	fmt.Println("reading clauses:", len(sq.ReadingClauses))
	fmt.Println("has RETURN:", sq.Return != nil)
	if _, isMatch := sq.ReadingClauses[0].(*ast.Match); isMatch {
		fmt.Println("first clause: MATCH")
	}
}

Output:
reading clauses: 1
has RETURN: true
first clause: MATCH

func ParseStrict ¶

func ParseStrict(query string) (ast.Query, []error)

ParseStrict lexes and parses a Cypher query string and returns all syntax errors encountered rather than only the first. When the query is syntactically valid the AST is walked for semantic errors; a single *SemaError is returned in that case.

This function is intended for tooling (editors, linters) that need the full error set. Application code should use Parse.

Errors:

• One or more *ParseError — syntax errors from lexer/parser.
• A single *SemaError — unsupported grammar rule or structural violation.

package main

import (
	"errors"
	"fmt"

	"github.com/FlavioCFOliveira/GoGraph/cypher/parser"
)

func main() {
	// Two independent syntax errors separated by a semicolon.
	_, errs := parser.ParseStrict("RETURN , ; RETURN ,")
	if len(errs) == 0 {
		fmt.Println("no errors")
		return
	}

	for _, e := range errs {
		var pe *parser.ParseError
		if errors.As(e, &pe) {
			fmt.Printf("syntax error at %d:%d\n", pe.Line, pe.Column)
		}
	}
}

Output:
syntax error at 1:7
syntax error at 1:11

func StripLiterals ¶ added in v0.11.0

func StripLiterals(query string) (stripped string, params map[string]string, ok bool)

StripLiterals rewrites query so that the string literals it can safely hoist become parameter references, and returns the rewritten text together with the values those parameters must be bound to. ok reports whether anything was hoisted; when it is false the caller must use query unchanged.

Why ¶

The plan cache is keyed on query text, so `{sk: 'a'}` and `{sk: 'b'}` are two different queries: each distinct literal re-parses and re-plans. Measured against the same query written with a parameter, that cost 65% more processor time per query (docs/cpu-vs-neo4j-memgraph-2026-08-11.md §6). Hoisting the literal collapses every spelling onto one cache entry.

It pays only because scanning is far cheaper than parsing: on the audit's point-lookup query, parsing costs 15.0 µs and analysing and translating a further ~1 µs, so avoiding the parse is nearly the whole saving. This scanner is a single pass over the bytes and costs ~330 ns.

Why a hand-written scanner ¶

The generated ANTLR lexer cannot be used for this. Its tokenisation is context-dependent in exactly the places that matter: `'p42'` arrives as ERRCHAR, ID, ERRCHAR rather than as a string token, and a bare `40` is sometimes ID and sometimes DIGIT, with the parser reinterpreting both later. Reproducing that reinterpretation here would be a second implementation of a subtle rule. Memgraph reached the same conclusion and hand-wrote its stripper rather than reuse its ANTLR lexer.

What it hoists, and what it will not ¶

Only STRING literals, and only inside a MATCH pattern or a WHERE predicate. Both limits were set by measurement rather than caution:

• Numbers are left alone. A number can appear where a parameter is invalid or plan-changing — the bounds of a variable-length pattern (`[r*1..3]`), SKIP and LIMIT — and has forms (hexadecimal, octal, exponent) the parser reinterprets from ID tokens.
• Every clause other than MATCH and WHERE is skipped. An earlier version hoisted everywhere except projections and regressed five TCK scenarios: a procedure argument (`CALL test.my.proc('Stefan', 1)`) and a map literal fed to `SET r += {...}` are both positions where a literal is not simply an expression whose value may arrive by parameter. RETURN and WITH are skipped too, because an unaliased projection is named after its own source text — `RETURN 'x'` yields a column called `'x'`.

Skipping a hoistable literal costs one cache entry. Hoisting one that should not be hoisted changes what the query means, so every uncertainty here resolves towards skipping.