Full-Text Index Schema, Node vs Relationship Indexes, Analyzers, Tokenization, and Language Handling

AtlasMart product search currently uses CONTAINS over names and descriptions. It finds substrings, but it cannot express a search vocabulary such as “wildlife trail camera,” cannot stem language-specific word forms, and provides no relevance ordering. The fix is not “turn on a magic search mode.” A Neo4j full-text index is a separate Lucene-backed retrieval structure whose schema, analyzer, query parser, score and freshness contract must be designed explicitly.

Learning outcomes

Lab contract and exact assumptions

1. Full-text is a semantic index, not a normal predicate accelerator

Range/text indexes are planner-selected access paths for predicates such as equality, prefix, suffix and substring matches. Full-text indexes are different: they tokenize indexed text and must be called explicitly through db.index.fulltext.queryNodes() or queryRelationships(). The procedure returns the entity plus a Lucene relevance score already ordered from best to lower match.

2. Schema membership is OR across labels/types and fields

A node full-text index may name several labels and several properties. A node can participate if it has at least one indexed label and at least one indexed property. Relationship full-text indexes can similarly name multiple relationship types and properties. Only STRING and LIST<STRING> values contribute searchable terms; a tags list is analyzed into the same field namespace for that property.

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);

CYPHER 25
SHOW FULLTEXT INDEXES
YIELD name, state, populationPercent, entityType, labelsOrTypes,
      properties, indexProvider, options, lastRead, readCount
WHERE name STARTS WITH 'ch21_'
RETURN * ORDER BY name;

MATCH (p:Product {labTag:'ch21'})
RETURN count(p) AS products,
       count { (p)-[:STOCKED_AT]->(:Store {storeId:'ST-21-CENTRAL'}) } AS stockEdges;
// Deterministic graph invariant: products = 8 and stockEdges = 8.
// Full-text state invariant before search: both indexes are ONLINE and 100% populated.

3. Analyzer choice is part of your data contract

An analyzer determines how both indexed text and, by default, query text become terms. Current Neo4j defaults new full-text indexes to standard-no-stop-words. The Chapter 21 catalog intentionally uses english so learners can observe language-aware stemming/stop-word behavior. Analyzer names are server capabilities: list them on the exact deployment rather than copying a blog post.

CYPHER 25
CALL db.index.fulltext.listAvailableAnalyzers()
YIELD analyzer, description, stopwords
WHERE analyzer IN ['standard-no-stop-words','english','whitespace']
RETURN analyzer, description, stopwords;
// Verify the list on your exact server; do not assume every custom/language analyzer exists everywhere.

4. One analyzer is rarely a complete multilingual strategy

Language analyzers can stem terms and remove language-specific stop words, while the default analyzer is less language-specific. Do not put English, Persian, Arabic, Turkish and Urdu product text into one index and assume one stemming policy is neutral. Common strategies are separate language-specific properties/indexes, a language-neutral analyzer for fields that must mix languages, or a deliberately tested custom analyzer. The correct choice comes from judged queries per locale, not font/script similarity.

5. Node and relationship search solve different questions

The catalog index finds Products from product text. The review index finds REVIEWED edges from review-message text; after retrieving a relationship, Cypher can inspect its endpoints and graph context. This is not equivalent to copying review text onto a Product merely to make it searchable.

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.

CYPHER 25
CALL db.index.fulltext.queryRelationships('ch21_reviews_ft', 'night vision', {limit: 10})
YIELD relationship, score
RETURN relationship.reviewId AS reviewId,
       relationship.message AS message,
       score
ORDER BY score DESC;
// Expected invariant from the fixture: REV-2101 is a matching review.

6. What Neo4j is doing

1. A transaction creates/updates a STRING or LIST<STRING> value.
2. The configured analyzer turns that value into terms.
3. Lucene stores terms and postings for the qualifying node/relationship.
4. A query procedure analyzes the query string, evaluates Lucene query semantics, obtains matching entries and relevance scores, and returns entities in score order.
5. Cypher continues from those entities into normal graph predicates/traversals.

7. Deliberately wrong design: “one giant index over everything”

8. Verification checklist

• Eight Chapter 21 Product nodes and eight STOCKED_AT edges exist.
• ch21_catalog_ft and ch21_reviews_ft are ONLINE before testing.
• The analyzer list is captured from the actual server.
• A node query returns product IDs and scores; a relationship query can return REV-2101 for “night vision.”
• No expected numeric score has been copied from this lesson—the learner records current values.

9. Production judgment

Summary and next step

Full-text retrieval is an explicit Lucene-backed candidate system over carefully chosen graph fields. Lesson 2 now examines the query parser, score interpretation, Boolean/phrase/fuzzy behavior, limits, and the application boundary between safe parameterization and intentionally exposed Lucene syntax.

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.