Query Syntax, Scoring, Boolean/phrase/fuzzy Patterns, Result Limits, and Score Interpretation

AtlasMart launches a search box and the first demo looks excellent: “trail camera” returns sensible products. Then users type camra, operators paste Boolean syntax, and a developer adds a global rule “reject every result with score < 0.7.” These are three different problems—query parsing, typo tolerance, and score calibration. A robust search API must define which Lucene features it exposes, how many candidates it requests, and what a score means for that exact query/index/corpus.

Learning outcomes

Lab contract and exact assumptions

Direct-entry setup

If you did not complete Lesson 1 in this disposable database, run the setup now. It is idempotent for the Chapter 21 fixture.

CYPHER 25
// Safe to rerun in the disposable Chapter 21 lab.
CREATE CONSTRAINT ch21_product_id IF NOT EXISTS
FOR (p:Product) REQUIRE p.productId IS UNIQUE;
CREATE CONSTRAINT ch21_category_id IF NOT EXISTS
FOR (c:Category) REQUIRE c.categoryId IS UNIQUE;
CREATE CONSTRAINT ch21_store_id IF NOT EXISTS
FOR (s:Store) REQUIRE s.storeId IS UNIQUE;
CREATE CONSTRAINT ch21_customer_id IF NOT EXISTS
FOR (c:Customer) REQUIRE c.customerId IS UNIQUE;

MERGE (cam:Category {categoryId:'CAT-21-CAM'}) SET cam.name='Cameras', cam.labTag='ch21'
MERGE (out:Category {categoryId:'CAT-21-OUT'}) SET out.name='Outdoor', out.labTag='ch21'
MERGE (sec:Category {categoryId:'CAT-21-SEC'}) SET sec.name='Security', sec.labTag='ch21'
MERGE (acc:Category {categoryId:'CAT-21-ACC'}) SET acc.name='Accessories', acc.labTag='ch21'
MERGE (st:Store {storeId:'ST-21-CENTRAL'}) SET st.name='AtlasMart Central', st.labTag='ch21'
MERGE (c1:Customer {customerId:'C-2101'}) SET c1.name='Mina Rahimi', c1.labTag='ch21'
MERGE (c2:Customer {customerId:'C-2102'}) SET c2.name='Omid Karimi', c2.labTag='ch21';

UNWIND [
 {id:'P-2101',name:'Trail Camera Pro',description:'Weatherproof wildlife trail camera with infrared night vision and long battery life',tags:['wildlife','trail','infrared','outdoor'],active:true,category:'CAT-21-CAM',qty:5,featured:true},
 {id:'P-2102',name:'Trail Camera Mini',description:'Compact wildlife camera for trails, gardens, and backyard monitoring',tags:['wildlife','trail','compact'],active:true,category:'CAT-21-CAM',qty:0,featured:false},
 {id:'P-2103',name:'Indoor Security Camera',description:'Wi-Fi home security camera with motion alerts and night vision',tags:['security','indoor','night vision'],active:true,category:'CAT-21-SEC',qty:7,featured:false},
 {id:'P-2104',name:'Trail Running Hydration Vest',description:'Lightweight hydration vest for long trail runs and mountain races',tags:['running','trail','hydration'],active:true,category:'CAT-21-OUT',qty:11,featured:false},
 {id:'P-2105',name:'Action Camera 4K',description:'Water-resistant action sports camera for cycling, hiking, and travel',tags:['action','sports','camera'],active:true,category:'CAT-21-CAM',qty:3,featured:true},
 {id:'P-2106',name:'Wildlife Field Guide',description:'Illustrated guide to birds and mammals for outdoor observation',tags:['wildlife','book','outdoor'],active:true,category:'CAT-21-OUT',qty:6,featured:false},
 {id:'P-2107',name:'Solar Trail Charger',description:'Solar charger for outdoor cameras, sensors, and trail equipment',tags:['solar','trail','charger'],active:true,category:'CAT-21-ACC',qty:0,featured:false},
 {id:'P-2108',name:'Refurbished Trail Camera',description:'Older trail camera unit retained for support reference only',tags:['trail','camera','refurbished'],active:false,category:'CAT-21-CAM',qty:2,featured:false}
] AS row
MERGE (p:Product {productId:row.id})
SET p.name=row.name, p.description=row.description, p.tags=row.tags,
    p.active=row.active, p.featured=row.featured, p.labTag='ch21'
WITH row,p
MATCH (cat:Category {categoryId:row.category}), (st:Store {storeId:'ST-21-CENTRAL'})
MERGE (p)-[:IN_CATEGORY]->(cat)
MERGE (p)-[stock:STOCKED_AT]->(st)
SET stock.quantity=row.qty, stock.labTag='ch21';

MATCH (c1:Customer {customerId:'C-2101'}), (p1:Product {productId:'P-2101'})
MERGE (c1)-[r1:REVIEWED]->(p1)
SET r1.reviewId='REV-2101', r1.rating=5,
    r1.message='Excellent night vision for wildlife at the cabin', r1.labTag='ch21';
MATCH (c2:Customer {customerId:'C-2102'}), (p4:Product {productId:'P-2104'})
MERGE (c2)-[r2:REVIEWED]->(p4)
SET r2.reviewId='REV-2102', r2.rating=4,
    r2.message='Comfortable on long trail runs', r2.labTag='ch21';

CREATE FULLTEXT INDEX ch21_catalog_ft IF NOT EXISTS
FOR (p:Product) ON EACH [p.name, p.description, p.tags]
OPTIONS {indexConfig: {
  `fulltext.analyzer`: 'english',
  `fulltext.eventually_consistent`: false
}};

CREATE FULLTEXT INDEX ch21_reviews_ft IF NOT EXISTS
FOR ()-[r:REVIEWED]-() ON EACH [r.message]
OPTIONS {indexConfig: {`fulltext.analyzer`: 'english'}};

CALL db.awaitIndexes(300);

1. Parameterize Cypher; define the Lucene surface separately

Always pass the user search string as a Cypher parameter. This prevents the search text from becoming Cypher syntax. But the full-text procedure deliberately hands that string to Lucene’s query parser, so operators such as AND, quotes, field prefixes and fuzzy markers may still alter retrieval. Decide whether your product exposes “advanced search” or a literal/structured query builder. Escaping is an application-level Lucene concern, not a reason to concatenate Cypher.

CYPHER 25
CALL db.index.fulltext.queryNodes('ch21_catalog_ft', $q, {limit: 10})
YIELD node, score
RETURN node.productId AS productId, node.name AS name, score
ORDER BY score DESC;
// Example parameter: :param q => 'wildlife camera'
// Record actual scores; only the relative order in this result set has meaning.

2. Boolean, phrase, property and fuzzy patterns

Current Neo4j full-text procedures accept Lucene query language. Neo4j documents Boolean operators, quoted exact/phrase-style matching, and property-qualified queries; Lucene query parsing also supplies fuzzy term syntax. The fuzzy experiment below is deliberately evaluated against the fixture rather than assigned a hard-coded score.

// Run each as the $q parameter to db.index.fulltext.queryNodes.
// Boolean: both terms must participate.
'wildlife AND camera'

// Phrase: quoted terms occur as a phrase under the analyzer/query parser.
'"trail camera"'

// Exclusion: camera results except security-oriented terms.
'camera NOT security'

// Property-qualified query against a property included in the index.
'name:"Trail Camera Pro"'

// Fuzzy Lucene term: useful for a misspelling experiment.
'camra~'

// Field + Boolean composition.
'name:camera AND description:night'

3. Query-time analyzer is a precision tool, not an index rewrite

The current procedure options support skip, limit, and analyzer. Overriding the query analyzer can be useful when the application has a deliberate query-side normalization policy, but the indexed terms remain those produced at index creation. Compare results under the default and a query-side analyzer only after listing what is available.

CYPHER 25
CALL db.index.fulltext.queryNodes(
  'ch21_catalog_ft',
  'trail cameras',
  {limit: 10, analyzer: 'whitespace'}
)
YIELD node, score
RETURN node.productId, node.name, score
ORDER BY score DESC;
// Compare candidate IDs/ranks with the same query using the default index analyzer.

4. Score interpretation: rank evidence, not probability

Neo4j explicitly states that full-text scores are meaningful within the result set from a full-text query. The magnitude depends on terms, document statistics, fields, analyzer and corpus. Adding products can change document-frequency statistics and therefore scores even when one Product did not change. A threshold copied from another index, environment or vector source is not evidence.

5. Candidate limit is part of recall

If AtlasMart ultimately displays five products but graph/security/stock filters remove some lexical candidates, asking Lucene for only five can starve the post-filter stage. Retrieve a bounded sourceK based on measured survival rate and latency. The current full-text procedure supports limit directly; skip exists for pagination, but deep result browsing should still be evaluated for cost and ranking stability.

CYPHER 25
CALL db.index.fulltext.queryNodes('ch21_catalog_ft', $q, {skip: 0, limit: 20})
YIELD node, score
RETURN node.productId AS productId, node.name AS name, score
ORDER BY score DESC;

6. AtlasMart query matrix: record, do not invent

CYPHER 25
CALL db.index.fulltext.queryNodes('ch21_catalog_ft', $q, {limit: 10})
YIELD node, score
RETURN node.productId AS productId, node.name AS name, score
ORDER BY score DESC;
// Example parameter: :param q => 'wildlife camera'
// Record actual scores; only the relative order in this result set has meaning.

7. Wrong approach → failure → repair

8. Verification checklist

• All query strings are supplied as parameters to Cypher.
• The allowed Lucene grammar is documented: literal, structured, or advanced.
• Boolean, phrase, field and fuzzy experiments record IDs/ranks/latency from the current server.
• No score is described as a probability or compared directly to a vector score.
• Candidate limit is justified by downstream graph/business filtering and measured latency.

9. Production judgment

Summary and next step

Search syntax is an API contract, scores are source-local ranking evidence, and candidate limits are part of recall engineering. Lesson 3 adds the write-path decision: whether Lucene updates must be visible at commit or may enter a background queue with an explicit freshness SLO.

Authoritative references

• Current Neo4j versions — Current database release 2026.07.1 and current 5.26 LTS patch 5.26.30.
• Full-text indexes — Cypher 25 — Current schema, analyzer, query, score, eventual-consistency, SHOW FULLTEXT INDEXES and procedure semantics.
• Semantic indexes — Why full-text and vector indexes are explicit semantic retrieval systems and why raw cross-source scores should not be compared.
• Built-in full-text procedures — Current signatures for queryNodes/queryRelationships/listAvailableAnalyzers/awaitEventuallyConsistentIndexRefresh and limit/skip/query-analyzer options.
• Index configuration — Default analyzer, eventual-consistency queue model, background update settings and operational implications.
• Configuration settings — Current db.index.fulltext.* defaults, including standard-no-stop-words and eventual-consistency settings.
• Index syntax — Current CREATE/SHOW/DROP and semantic-index query syntax; SHOW FULLTEXT INDEXES is the supported filtered SHOW form.
• Security limitations for semantic indexes — Lucene-backed full-text/vector security filtering can conservatively return partial or zero results under fine-grained restrictions.
• Hybrid search developer guide — Current rank-fusion guidance for lexical, vector and structural sources; fuse ranks, not incomparable raw scores.
• Hybrid search engineering article — 2026 worked explanation of combining words, meaning and graph topology with rank-based fusion.
• Metrics — Enterprise-only built-in metrics surface and monitoring responsibilities.
• Metrics reference — Current full-text queried/populated counters; edition boundary is Enterprise.
• System requirements — Neo4j 2026.07 supported Java 21/25 and current OS/runtime boundaries.
• Python driver 6.3 — Official driver API used by the optional evaluation harness; current 6.3 supports Neo4j 2026.x.
• Vector SEARCH clause — Bridge to Chapter 22 and explicit current warning to rank vector/full-text sources independently.