Cypher Parser Modes¶

Environment Variable: NORNICDB_PARSER
Options: nornic (default) | antlr

NornicDB supports two Cypher parser implementations that can be switched at runtime.

Architecture¶

%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1f6feb', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'secondaryColor': '#238636', 'tertiaryColor': '#21262d', 'background': '#0d1117', 'mainBkg': '#161b22'}}}%%

flowchart TB
    subgraph ENV["🔧 Configuration"]
        direction LR
        E1["NORNICDB_PARSER"]
        E2["nornic | antlr"]
    end

    Q[/"Cypher Query"/]

    Q --> VALIDATE["validateSyntax()"]

    VALIDATE --> |"NORNICDB_PARSER=nornic"| NORNIC
    VALIDATE --> |"NORNICDB_PARSER=antlr"| ANTLR

    subgraph NORNIC["⚡ Nornic Parser (Default)"]
        direction TB
        N1["String-based validation"]
        N2["Regex + indexOf"]
        N3["Direct execution"]
        N1 --> N2 --> N3
    end

    subgraph ANTLR["🌳 ANTLR Parser"]
        direction TB
        A1["ANTLR Lexer"]
        A2["ANTLR Parser"]
        A3["Full Parse Tree"]
        A4["Syntax Validation"]
        A1 --> A2 --> A3 --> A4
    end

    NORNIC --> EXEC["Execute Query"]
    ANTLR --> EXEC
    EXEC --> RESULT[("Result")]

    style ENV fill:#21262d,stroke:#30363d
    style NORNIC fill:#161b22,stroke:#238636
    style ANTLR fill:#161b22,stroke:#a371f7
    style RESULT fill:#238636,stroke:#3fb950

Real-World Benchmarks (Northwind Database)¶

Total test suite time: | Mode | Time | |------|------| | ⚡ Nornic | 17.5s | | 🌳 ANTLR | 35.3s (2x slower) |

Mode Comparison¶

Note: both modes share a single converged execution pipeline. There are no legacy alternate executors or text re-dispatch fallbacks: every statement runs through the same typed router (Handled / NotApplicable / ParseRejected / Failed), and unhandled statements fail with Neo4j's Neo.ClientError.Statement.SyntaxError classification rather than being re-routed.

Nornic validation is TCK-vetted¶

The Nornic scanner uses a recursive key scanner with lightweight lexing only where needed (pkg/cypher/keyword_scan.go), with quote/comment/bracket-aware fragment consumption shared by all callers. The official OpenCypher TCK is pinned at revision 370fe27f and the ratchet records 7794/7794 scenario/mode outcomes passing with zero expected gaps, setup blocks or harness errors (make cypher-tck-ratchet, make cypher-tck-vetted). Rejections are classified with Neo4j Bolt status codes and error positions are restored from the original query text, including CR/CRLF/LF line counting.

Configuration¶

# Production (default) - fastest
export NORNICDB_PARSER=nornic

# Development/Debugging - strict validation, better errors
export NORNICDB_PARSER=antlr

Programmatic Switching¶

import "github.com/orneryd/nornicdb/pkg/config"

// Check current parser
if config.IsNornicParser() {
    // Using fast Nornic parser
}

// Switch to ANTLR temporarily
cleanup := config.WithANTLRParser()
defer cleanup()
// ... queries use ANTLR parser here

// Direct set
config.SetParserType(config.ParserTypeANTLR)
config.SetParserType(config.ParserTypeNornic)

When to Use Each Parser¶

⚡ Nornic Parser (NORNICDB_PARSER=nornic) — Default¶

Use when: - Production deployments - Maximum performance is critical - Simple, well-tested query patterns - High-throughput workloads

Pros: - Fastest execution — 3,000-4,200 ops/sec - 💾 Lowest memory — No parse tree allocation - 🔧 Battle-tested — Original implementation, converged single pipeline - ⚡ Zero parsing overhead — recursive key scanner, lightweight lexing only as needed

Cons: - 🐛 No structured parse tree — debugging uses restored positions, not AST inspection - 📝 Semantic scope checks are clause-targeted rather than grammar-derived; the TCK ratchet gates the supported surface

🌳 ANTLR Parser (NORNICDB_PARSER=antlr)¶

Use when: - Development and debugging - Need detailed syntax error messages - Strict OpenCypher compliance required - Building query analysis tools

Pros: - ✅ Strict validation — Full OpenCypher grammar - 📍 Detailed errors — Line and column numbers - 🌳 Full parse tree — For analysis/tooling - 🛠️ Extensible — Easy to add new features

Cons: - 🐢 Much slower — 50-5000x slower than Nornic - 💾 Higher memory — Full parse tree allocation - ⏱️ Not for production — Too slow for high-throughput

Error Message Comparison¶

Invalid query: MATCH (n RETURN n (missing closing paren)

Make Targets¶

# Run entire test suite with ANTLR parser
make antlr-test

# Run cypher tests with both parsers
make test-parsers

# Regenerate ANTLR parser from grammar
make antlr-generate

Files¶

TL;DR: Use nornic (default) for production. Use antlr only for development/debugging when you need detailed error messages.