# OpenCypher Grammar Comparison Report

## Final Results

**Our Lark Grammar: 97.5% pass rate** (1742/1787 real Cypher queries)

Source: grammars-v4/cypher ANTLR4 grammar, converted to Lark and enhanced.

## Grammar Sources

| Source | Format | Rules | Status |
|--------|--------|-------|--------|
| **grammars-v4** | ANTLR4 → Lark | 518 | **Working (97.5%)** |
| **openCypher XML** | XML → Lark | 144 | Converted, needs work |
| **libcypher-parser** | PEG | 241 | Reference only |

## Feature Comparison: Our Grammar vs libcypher-parser

### Core Clauses (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| MATCH/OPTIONAL MATCH | ✓ | ✓ |
| CREATE/MERGE | ✓ | ✓ |
| DELETE/DETACH DELETE | ✓ | ✓ |
| SET/REMOVE | ✓ | ✓ |
| WITH/RETURN | ✓ | ✓ |
| UNWIND | ✓ | ✓ |
| UNION/UNION ALL | ✓ | ✓ |
| FOREACH | ✓ | ✓ |
| CALL/YIELD | ✓ | ✓ |
| WHERE clause | ✓ | ✓ |
| ORDER BY/SKIP/LIMIT | ✓ | ✓ |

### Pattern Matching (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| Node patterns | ✓ | ✓ |
| Relationship patterns | ✓ | ✓ |
| Variable-length paths | ✓ | ✓ |
| Labels and types | ✓ | ✓ |
| Properties | ✓ | ✓ |
| shortestPath/allShortestPaths | ✓ | ✓ |

### Expressions (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| Parameters ($param) | ✓ | ✓ |
| Legacy parameters ({param}) | ✓ | ✓ |
| CASE expressions | ✓ | ✓ |
| List comprehension | ✓ | ✓ |
| Pattern comprehension | ✓ | ✓ |
| ALL/ANY/NONE/SINGLE | ✓ | ✓ |
| FILTER/EXTRACT (legacy) | ✓ | ✓ |
| REDUCE expression | ✓ | ✓ |
| Boolean operators | ✓ | ✓ |
| Comparison operators | ✓ | ✓ |
| Arithmetic operators | ✓ | ✓ |
| String operators | ✓ | ✓ |
| Regex operator (=~) | ✓ | ✓ |
| List operators (IN, []) | ✓ | ✓ |
| IS NULL/IS NOT NULL | ✓ | ✓ |
| count(*) / count(DISTINCT *) | ✓ | ✓ |

### Schema Commands (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| CREATE INDEX | ✓ | ✓ |
| DROP INDEX | ✓ | ✓ |
| CREATE CONSTRAINT | ✓ | ✓ |
| DROP CONSTRAINT | ✓ | ✓ |

### Query Options & Hints (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| CYPHER version prefix | ✓ | ✓ |
| PROFILE/EXPLAIN | ✓ | ✓ |
| USING INDEX | ✓ | ✓ |
| USING SCAN | ✓ | ✓ |
| USING JOIN ON | ✓ | ✓ |

### Legacy Features (All Supported)

| Feature | Our Grammar | libcypher-parser |
|---------|:-----------:|:----------------:|
| START clause | ✓ | ✓ |
| CREATE UNIQUE | ✓ | ✓ |
| LOAD CSV | ✓ | ✓ |
| Client commands (:help) | ✓ | ✓ |

### Features Not Fully Implemented

| Feature | Our Grammar | libcypher-parser | Notes |
|---------|:-----------:|:----------------:|-------|
| Map projection | ✗ | ✓ | `a{.x, y, .*}` |
| USING PERIODIC COMMIT | ✗ | ✓ | Batch import hint |
| YIELD - (void) | ✗ | ✓ | Edge case |
| Multiple statements | Partial | ✓ | Single per parse |
| Error recovery | ✗ | ✓ | Extensive in libcypher |

## Remaining Test Failures (2.5%)

The 45 failures categorize as:

### Invalid/Malformed Syntax (Intentional Test Cases)
- Em-dash (—) instead of minus (-)
- Unbalanced brackets `[[[]]`
- Empty collections with comma `[, ]`, `{, }`
- Hash in identifiers

### Incomplete Query Fragments
- `MATCH (n)` without RETURN
- `WITH *` without continuation

### Multiple Statements
- `return 1; return 2; return 3`
- Would need script-level multi-statement support

### Map Projection Syntax
- `RETURN a{}`, `RETURN map{.x, y, .*}`
- Advanced feature not in base openCypher

## File Locations

```
grammars/
├── lark_grammars/                # Lark grammars (renamed from lark/)
│   └── cypher_from_grammars_v4.lark  # Main working grammar
├── antlr4/                       # ANTLR4 source grammars
├── libcypher-peg/                # Reference PEG grammar
├── opencypher-xml/               # Official XML grammar
├── tck-queries/                  # Test queries (1962 total)
├── test_filtered.py              # Test runner
├── analyze_failures.py           # Failure analysis
└── GRAMMAR_COMPARISON.md         # This file
```

## Conclusion

Our Lark grammar achieves **97.5% compatibility** with the TCK test suite. It supports all core openCypher features plus legacy features. The remaining 2.5% failures are:
- Intentionally malformed test cases
- Incomplete query fragments
- Advanced features (map projection) not in base openCypher

For practical use, the grammar covers all standard Cypher query patterns.
