Browser rejects CREATE VECTOR INDEX with a syntax error: grammar lacks VECTOR keyword and OPTIONS clause

[dragnot]

Summary

The browser rejects valid CREATE VECTOR INDEX statements with a client side Syntax error before the query is ever sent to the server. The same query succeeds against FalkorDB via redis-cli and via the Python client, so this is a browser grammar gap rather than a server limitation.

Reproduction

Run this in the browser query editor:

CREATE VECTOR INDEX FOR (u:User) ON (u.hdc_index_2048)
OPTIONS { dimension: 2048, similarityFunction: 'cosine' }

Result: Syntax error reported by the editor.

The identical query via redis-cli succeeds:

$ redis-cli GRAPH.QUERY vec_idx_test "CREATE VECTOR INDEX FOR (u:User) ON (u.hdc_index_2048) OPTIONS { dimension: 2048, similarityFunction: 'cosine' }"
Indices created: 1
Query internal execution time: 8.280917 milliseconds

Verified the index is fully functional afterwards: CALL db.indexes() reports OPERATIONAL, 2048 dimension vectors insert correctly with vecf32(), and db.idx.vector.queryNodes returns correctly ranked KNN results.

Tested against FalkorDB graph module 42003.

Root cause

lib/falkordb-cypher/generated/.grammar-src/Cypher.g4 lines 50 to 53:

oC_CreateIndex
           :  CREATE SP ( FULLTEXT SP )? INDEX SP?
              ( ( FOR SP? oC_IndexEntity SP? ON SP? oC_IndexProperties )
                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) ) ;

Two gaps:

1. No VECTOR keyword. The rule accepts an optional FULLTEXT qualifier only. There is no VECTOR token defined anywhere in the grammar (grep -c "^VECTOR" Cypher.g4 returns 0), so CREATE VECTOR INDEX cannot parse.
2. No OPTIONS { ... } clause. The rule ends after oC_IndexProperties, so even if VECTOR were accepted, the trailing options map would still fail to parse. OPTIONS is required for vector indexes since dimension and similarityFunction are mandatory.

oC_DropIndex at lines 55 to 58 has the identical shape, so DROP VECTOR INDEX is affected the same way.

Worth noting the spec file already knows about vector search at the procedure level. lib/falkordb-cypher/falkordbSpec.ts lists db.idx.vector.queryNodes and db.idx.vector.queryRelationships, so querying a vector index is supported while creating one is not.

Suggested fix

Add a VECTOR lexer token, allow it as an alternative to FULLTEXT in both oC_CreateIndex and oC_DropIndex, and add an optional OPTIONS map clause. Roughly:

oC_CreateIndex
           :  CREATE SP ( ( FULLTEXT | VECTOR ) SP )? INDEX SP?
              ( ( FOR SP? oC_IndexEntity SP? ON SP? oC_IndexProperties )
                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) )
              ( SP? OPTIONS SP? oC_MapLiteral )? ;

VECTOR and OPTIONS will also need adding to the non reserved keyword list around line 737, alongside the existing INDEX and FULLTEXT entries, so they remain usable as identifiers.

The parser is ANTLR generated, so generated/CypherParser.ts and generated/CypherLexer.ts need regenerating from the grammar source.

Impact

Vector indexes cannot be created from the browser at all. Users have to drop to redis-cli or a client library, which is a poor experience for anyone evaluating vector or GraphRAG capabilities in the UI.

Environment

• Repo branch: staging
• FalkorDB graph module: 42003
• Browser: FalkorDB Browser on port 3000

[overcut-ai]

Completed Working on "Automated Ticket Triage "

✅ Triage completed for issue #2058. Labels applied: bug. No duplicate was found (no matching issue met similarity threshold ≥0.75), so duplicate label was not added. needs-info was not applied because the report contains sufficient reproduction details, environment/version context, root-cause analysis, and a concrete fix direction.

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Completed Working on "Auto Root Cause Analysis"

✅ Workflow completed successfully.

---

👉 View complete log

[overcut-ai]

Root Cause Analysis (RCA)

Summary

The reported bug is valid. The browser-side Cypher grammar does not recognize vector index DDL syntax, so valid queries are rejected client-side before reaching FalkorDB.

Specifically, the grammar only supports optional FULLTEXT in index create/drop statements and does not support an OPTIONS { ... } clause in those rules.

Evidence

• lib/falkordb-cypher/generated/.grammar-src/Cypher.g4:50-53
  • oC_CreateIndex is currently:
    • CREATE SP ( FULLTEXT SP )? INDEX ...
    • rule ends after index properties; no trailing OPTIONS map support.
• lib/falkordb-cypher/generated/.grammar-src/Cypher.g4:55-58
  • oC_DropIndex has the same shape and limitation.
• lib/falkordb-cypher/generated/.grammar-src/Cypher.g4 keyword definitions/non-reserved keyword section
  • FULLTEXT exists; VECTOR was missing.
  • non-reserved keyword alternatives included INDEX/FULLTEXT, but not VECTOR/OPTIONS.
• lib/falkordb-cypher/falkordbSpec.ts
  • Includes vector procedures (db.idx.vector.queryNodes, db.idx.vector.queryRelationships), confirming vector query support is known while DDL grammar coverage is incomplete.

Impacted Areas

• Grammar source:
  • lib/falkordb-cypher/generated/.grammar-src/Cypher.g4
• Generated parser artifacts (must be regenerated from grammar):
  • lib/falkordb-cypher/generated/CypherParser.ts
  • lib/falkordb-cypher/generated/CypherLexer.ts
  • (and any other generated outputs from the grammar generation step)

Minimal Safe Fix Suggestion

Update grammar rules to accept VECTOR in create/drop index qualifiers and optional trailing OPTIONS map.

Proposed patch (pseudo-diff, minimal scope)

diff --git a/lib/falkordb-cypher/generated/.grammar-src/Cypher.g4 b/lib/falkordb-cypher/generated/.grammar-src/Cypher.g4
@@
 oC_CreateIndex
-           :  CREATE SP ( FULLTEXT SP )? INDEX SP?
+           :  CREATE SP ( ( FULLTEXT | VECTOR ) SP )? INDEX SP?
               ( ( FOR SP? oC_IndexEntity SP? ON SP? oC_IndexProperties )
-                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) ) ;
+                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) )
+              ( SP? OPTIONS SP? oC_MapLiteral )? ;
@@
 oC_DropIndex
-           :  DROP SP ( FULLTEXT SP )? INDEX SP?
+           :  DROP SP ( ( FULLTEXT | VECTOR ) SP )? INDEX SP?
               ( ( FOR SP? oC_IndexEntity SP? ON SP? oC_IndexProperties )
-                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) ) ;
+                | ( ON SP? ':' SP? oC_LabelName SP? oC_IndexProperties ) )
+              ( SP? OPTIONS SP? oC_MapLiteral )? ;
@@
+VECTOR
+           : ( 'V' | 'v' ) ( 'E' | 'e' ) ( 'C' | 'c' ) ( 'T' | 't' ) ( 'O' | 'o' ) ( 'R' | 'r' ) ;
+OPTIONS
+           : ( 'O' | 'o' ) ( 'P' | 'p' ) ( 'T' | 't' ) ( 'I' | 'i' ) ( 'O' | 'o' ) ( 'N' | 'n' ) ( 'S' | 's' ) ;
@@
 oC_NonReservedKeyword
            : ...
            | INDEX
            | FULLTEXT
+           | VECTOR
+           | OPTIONS
            | ...
 ;

Then regenerate parser/lexer artifacts from the grammar source.

Risk Assessment

• Risk level: Low–Medium
• Why: Change is localized and backward-compatible in intent, but grammar token/non-reserved handling can have parser-wide effects after regeneration.
• Mitigation: Edit only .grammar-src/Cypher.g4, regenerate generated files, and run targeted parser regressions for existing INDEX/FULLTEXT statements.

Test Recommendations

1. Parser acceptance tests for:
   • CREATE VECTOR INDEX ... OPTIONS { dimension: 2048, similarityFunction: 'cosine' }
   • Existing syntax regressions:
     • CREATE INDEX ...
     • CREATE FULLTEXT INDEX ...
     • DROP INDEX ...
     • DROP FULLTEXT INDEX ...
2. Integration (browser editor path)
   • Ensure valid vector index query is not rejected client-side and is sent to server.
3. Manual smoke
   • Create vector index from browser, verify via CALL db.indexes(), insert vectors, and validate db.idx.vector.queryNodes.

Confidence

High (0.94)

Rationale: Direct grammar inspection confirms missing VECTOR/OPTIONS support in index DDL parsing while vector query procedures are present in spec metadata.

[overcut-ai]

Applying labels for RCA workflow outcome: rca-proposed, conf-high.

[dragnot]

No workaround exists, which raises the impact

Checked whether the older procedure form could be used instead, since CALL parses fine in the browser grammar while CREATE VECTOR INDEX does not. It cannot:

$ redis-cli GRAPH.QUERY demo_edge "CALL db.idx.vector.createNodeIndex('User','embedding2',4,'cosine')"
Procedure `db.idx.vector.createNodeIndex` is not registered

The registered procedure list shows an asymmetry between fulltext and vector:

db.idx.fulltext.createNodeIndex     <- fulltext creation via CALL is available
db.idx.fulltext.drop
db.idx.fulltext.queryNodes
db.idx.fulltext.queryRelationships
db.idx.vector.queryNodes            <- vector has query procedures only
db.idx.vector.queryRelationships

Fulltext indexes can be created through a procedure, so they are reachable from the browser. Vector indexes have no procedure equivalent, so on module 42003 the CREATE VECTOR INDEX ... OPTIONS { ... } statement is the only way to create one, and that is exactly the syntax the grammar rejects.

Net effect: vector indexes cannot be created from the browser by any means.

Sharper repro isolating the gap

Against a graph containing two :User nodes, every one of these parses and runs correctly in the browser:

CREATE (a:User {name:'Alice'})-[r:KNOWS {since:2020}]->(b:User {name:'Bob'})

MATCH (u:User {name:'Alice'}) SET u.embedding = vecf32([1.0, 0.2, 0.0, 0.1])

CALL db.idx.vector.queryNodes('User','embedding',2,vecf32([1.0,0.15,0.0,0.1]))
YIELD node, score RETURN node, score

Only the index creation fails with Syntax error:

CREATE VECTOR INDEX FOR (u:User) ON (u.embedding)
OPTIONS { dimension: 4, similarityFunction: 'cosine' }

So the browser can write vectors with vecf32() and can query a vector index, it just cannot create the index that makes the query possible. Verified working end to end via redis-cli on the same graph: index reports OPERATIONAL and KNN returns correctly ranked results (Alice 0.00117, Bob 0.95777).

[overcut-ai]

Thanks for the additional validation — this is a material impact update and it strengthens the RCA.

RCA Addendum (impact/workaround clarification)

Your new evidence is consistent with the codebase:

• In lib/falkordb-cypher/falkordbSpec.ts, FALKORDB_INDEX_PROCEDURES includes:
  • db.idx.fulltext.createNodeIndex
  • db.idx.fulltext.drop
  • db.idx.fulltext.queryNodes
  • db.idx.fulltext.queryRelationships
  • db.idx.vector.queryNodes
  • db.idx.vector.queryRelationships
• There is no db.idx.vector.createNodeIndex entry (or equivalent vector-create procedure) in that list.

So this supports your finding that on module 42003 there is no procedure-form fallback for vector index creation from the browser.

The original root cause remains unchanged and confirmed:

• lib/falkordb-cypher/generated/.grammar-src/Cypher.g4 index grammar accepts optional FULLTEXT only (no VECTOR) and does not allow trailing OPTIONS { ... } in oC_CreateIndex / oC_DropIndex.

Updated impact

This is more severe than a simple syntax gap with an in-browser workaround:

Vector indexes cannot be created from the browser by any in-browser path on module 42003.

Users can still run vector query procedures and vector value functions, but cannot issue the required index-creation DDL in the browser because the client parser blocks it.

Fix direction (unchanged)

Still the same minimal-safe correction:

1. Extend index grammar to allow (FULLTEXT | VECTOR).
2. Add optional OPTIONS oC_MapLiteral support for index DDL.
3. Add keyword/token handling for VECTOR and OPTIONS in grammar keyword sections.
4. Regenerate parser/lexer artifacts from grammar source.

Confidence for this updated RCA remains high.