Open
Conversation
Owner
Author
|
I'm keeping the If you have concerns about performance or security with our stream-parse-execute model, we have documentation covering these topics: 📊 Performance
🔒 Security
Our stream-parse-execute model provides both performance benefits (no upfront AST overhead) and security guarantees (identifier validation, parameterization) documented in detail above. |
added 4 commits
December 5, 2025 14:40
- Add NORNICDB_EXECUTOR_MODE env var (default: hybrid) - nornic: Fast string-based parser (original) - antlr: Full ANTLR AST-based parser (for LLM features) - hybrid: Fast execution + background AST building (best of both) New files: - pkg/config/executor_mode.go: Config for executor mode - pkg/cypher/executor_factory.go: Factory to create executors - pkg/cypher/hybrid_executor.go: Hybrid executor implementation - pkg/cypher/executor_interface.go: CypherExecutor interface + ABExecutor - pkg/cypher/antlr/*.go: ANTLR grammar and parser files Test coverage: - executor_factory_test.go: Factory tests - executor_mode_test.go: Comprehensive mode comparison tests - hybrid_executor_test.go: Hybrid-specific tests - ab_test.go: A/B performance comparison tests Performance (M3 Max): - nornic: ~422 ns/op - hybrid: ~433 ns/op (~3% overhead) - All modes pass identical query tests
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Cypher Executor Modes: Architecture Overview
Architecture Diagram
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1f6feb', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'secondaryColor': '#238636', 'tertiaryColor': '#21262d', 'background': '#0d1117', 'mainBkg': '#161b22', 'textColor': '#c9d1d9'}}}%% flowchart TB subgraph ENV["🔧 Configuration"] direction LR E1["NORNICDB_EXECUTOR_MODE"] E2["nornic | antlr | hybrid"] end Q[/"Cypher Query"/] Q --> FACTORY["NewCypherExecutor()"] FACTORY --> |"mode=nornic"| NORNIC FACTORY --> |"mode=antlr"| ANTLR FACTORY --> |"mode=hybrid"| HYBRID subgraph NORNIC["⚡ Nornic Mode"] direction TB N1["String Parser"] N2["Regex + indexOf"] N3["Direct Execution"] N1 --> N2 --> N3 end subgraph ANTLR["🌳 ANTLR Mode"] direction TB A1["ANTLR Lexer"] A2["ANTLR Parser"] A3["Full AST"] A4["AST Walker"] A1 --> A2 --> A3 --> A4 end subgraph HYBRID["🔀 Hybrid Mode (Default)"] direction TB H1["Query Arrives"] H2["String Executor<br/>(Fast Path)"] H3["Background Worker"] H4["AST Cache"] H1 --> H2 H1 -.-> |"async"| H3 H3 --> H4 style H2 fill:#238636,stroke:#3fb950 style H3 fill:#1f6feb,stroke:#58a6ff style H4 fill:#6e40c9,stroke:#a371f7 end NORNIC --> RESULT[("Result")] ANTLR --> RESULT HYBRID --> RESULT HYBRID -.-> |"cached AST for<br/>LLM features"| LLM["🤖 LLM Integration"] style ENV fill:#21262d,stroke:#30363d style NORNIC fill:#161b22,stroke:#f85149 style ANTLR fill:#161b22,stroke:#a371f7 style HYBRID fill:#161b22,stroke:#3fb950 style RESULT fill:#238636,stroke:#3fb950 style LLM fill:#1f6feb,stroke:#58a6ffQuery Flow Comparison
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1f6feb', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'secondaryColor': '#238636', 'tertiaryColor': '#21262d'}}}%% sequenceDiagram participant C as Client participant N as Nornic participant A as ANTLR participant H as Hybrid participant S as Storage participant Cache as AST Cache rect rgb(22, 27, 34) Note over C,S: Nornic Mode (fastest) C->>N: MATCH (n) RETURN n N->>N: String parse (~0.1µs) N->>S: Execute S-->>C: Results (~0.4µs total) end rect rgb(22, 27, 34) Note over C,S: ANTLR Mode (richest AST) C->>A: MATCH (n) RETURN n A->>A: Lexer + Parser (~15µs) A->>A: Build full AST A->>A: Walk AST (~50µs) A->>S: Execute S-->>C: Results (~70µs total) end rect rgb(22, 27, 34) Note over C,Cache: Hybrid Mode (best of both) C->>H: MATCH (n) RETURN n par Fast Path H->>H: String parse H->>S: Execute S-->>C: Results (~0.4µs) and Background H-->>Cache: Queue AST build Cache->>Cache: ANTLR parse (async) end Note over Cache: AST ready for LLM features endMode Comparison
Detailed Pros & Cons
⚡ Nornic Mode (
NORNICDB_EXECUTOR_MODE=nornic)Pros:
Cons:
Use When:
🌳 ANTLR Mode (
NORNICDB_EXECUTOR_MODE=antlr)Pros:
Cons:
Use When:
🔀 Hybrid Mode (
NORNICDB_EXECUTOR_MODE=hybrid) ← DEFAULTPros:
Cons:
Use When:
Performance Benchmarks (M3 Max)
Configuration Examples
Startup Banner
When NornicDB starts, you'll see:
LLM Integration Architecture
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1f6feb', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'secondaryColor': '#238636', 'tertiaryColor': '#21262d'}}}%% flowchart LR subgraph USER["User Input"] Q1["Malformed Query"] Q2["Natural Language"] end subgraph LLM["🤖 LLM Processing"] direction TB L1["Query Correction"] L2["AST Analysis"] L3["Safe Manipulation"] end subgraph HYBRID["🔀 Hybrid Executor"] direction TB AST["Cached AST"] EXEC["Fast Execution"] end Q1 --> L1 Q2 --> L1 L1 --> L2 AST --> L2 L2 --> L3 L3 --> EXEC EXEC --> R[("Results")] style USER fill:#21262d,stroke:#f85149 style LLM fill:#1f6feb,stroke:#58a6ff style HYBRID fill:#238636,stroke:#3fb950 style R fill:#238636,stroke:#3fb950Related Files
pkg/config/executor_mode.go- Configurationpkg/cypher/executor_factory.go- Factory functionpkg/cypher/hybrid_executor.go- Hybrid implementationpkg/cypher/ast_executor.go- ANTLR implementationpkg/cypher/executor.go- Nornic (string) implementationQuestions? Open an issue or check the test files for usage examples:
pkg/cypher/executor_mode_test.go- Comprehensive mode testspkg/cypher/hybrid_executor_test.go- Hybrid-specific testsANTLR
NORNIC
HYBRID
These are great real-world benchmarks! Let me update the documentation with the actual numbers:
[3 tools called]
Here's your updated GitHub Issue with real benchmark data:
Title:
feat: Configurable Cypher Executor Modes (nornic/antlr/hybrid)NornicDB now supports three Cypher executor modes via
NORNICDB_EXECUTOR_MODE.Architecture
%%{init: {'theme': 'dark', 'themeVariables': { 'primaryColor': '#1f6feb', 'primaryTextColor': '#c9d1d9', 'primaryBorderColor': '#30363d', 'lineColor': '#8b949e', 'secondaryColor': '#238636', 'tertiaryColor': '#21262d', 'background': '#0d1117', 'mainBkg': '#161b22'}}}%% flowchart TB Q[/"Cypher Query"/] --> FACTORY["NewCypherExecutor()"] FACTORY --> |"mode=nornic"| NORNIC FACTORY --> |"mode=antlr"| ANTLR FACTORY --> |"mode=hybrid"| HYBRID subgraph NORNIC["⚡ Nornic Mode"] N1["String Parser"] --> N2["Direct Execution"] end subgraph ANTLR["🌳 ANTLR Mode"] A1["ANTLR Lexer"] --> A2["Full AST"] --> A3["AST Walker"] end subgraph HYBRID["🔀 Hybrid Mode (Default)"] H1["Query"] --> H2["String Executor<br/>(Fast Path)"] H1 -.-> |"async"| H3["Background AST Builder"] H3 --> H4["AST Cache"] style H2 fill:#238636,stroke:#3fb950 style H3 fill:#1f6feb,stroke:#58a6ff style H4 fill:#6e40c9,stroke:#a371f7 end NORNIC & ANTLR & HYBRID --> RESULT[("Result")] HYBRID -.-> |"cached AST"| LLM["🤖 LLM Features"] style NORNIC fill:#161b22,stroke:#f85149 style ANTLR fill:#161b22,stroke:#a371f7 style HYBRID fill:#161b22,stroke:#3fb950Real-World Benchmarks (Northwind Database)
Total test suite:
Mode Comparison
Key Findings
Configuration
Startup Banner
TL;DR: Use
hybrid(default). You get Nornic speed with async AST for LLM features.