Eventually Consistent Full-Text Indexing, Freshness Expectations, and Operational Monitoring

AtlasMart’s merchandising team updates a product title and immediately searches for the new wording. With a synchronous full-text index, commit completion includes the index update. With eventual consistency enabled, the graph commit can succeed before the new text becomes searchable. That is not “random stale data”; it is an explicit queueing trade-off that must be paired with a freshness SLO, measurement, queue/backpressure awareness, and deterministic test barriers.

Learning outcomes

Lab contract and exact assumptions

Direct-entry setup

Run the core fixture if necessary. The freshness experiment uses a separate SearchProbe index so it cannot change the catalog ranking experiment.

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
CREATE FULLTEXT INDEX ch21_freshness_ft IF NOT EXISTS
FOR (n:SearchProbe) ON EACH [n.text]
OPTIONS {indexConfig: {
  `fulltext.analyzer`: 'standard-no-stop-words',
  `fulltext.eventually_consistent`: true
}};
CALL db.awaitIndexes(300);
MERGE (n:SearchProbe {probeId:'CH21-FRESH-1'})
SET n.text='baseline marker', n.labTag='ch21';
CALL db.index.fulltext.awaitEventuallyConsistentIndexRefresh();

1. Default mode is synchronous

Current Neo4j defaults db.index.fulltext.eventually_consistent=false. A new full-text index inherits that default unless its index configuration says otherwise. In this mode, the index update is part of commit completion. This reduces search staleness but means Lucene write work participates in the performance-critical commit path.

2. Eventual mode has a queue, not a magic “fast writes” switch

Neo4j queues updates from all eventually consistent full-text indexes and applies them in background threads. Current configuration includes an update-queue maximum; when the queue fills, commits can block waiting for room. That means overload is delayed, not abolished. Do not copy the current default queue length or thread counts as universal tuning advice—measure update volume, heap, write latency and freshness.

CYPHER 25
SHOW SETTINGS YIELD name, value, defaultValue, description
WHERE name STARTS WITH 'db.index.fulltext.eventually_consistent'
RETURN name, value, defaultValue, description
ORDER BY name;

3. Safe freshness experiment: absence before the barrier is allowed, not guaranteed

After Transaction A commits the sentinel update, the immediate full-text query may already see it because the background applier can run quickly. Therefore the lesson does not fabricate a stale result. The evidence is two timestamps and two candidate sets: “immediate visibility observed?” and “visibility after the supported await barrier?”.

// Transaction A — commit a unique marker.
CYPHER 25
MATCH (n:SearchProbe {probeId:'CH21-FRESH-1'})
SET n.text='baseline marker violet-freshness-sentinel';

// Transaction B — query immediately and record whether it is visible.
CYPHER 25
CALL db.index.fulltext.queryNodes('ch21_freshness_ft','violet-freshness-sentinel')
YIELD node, score
RETURN node.probeId, score;
// It MAY already be visible; absence is allowed because the index is eventually consistent.

// Transaction C — test synchronization barrier, then query again.
CYPHER 25
CALL db.index.fulltext.awaitEventuallyConsistentIndexRefresh();
CALL db.index.fulltext.queryNodes('ch21_freshness_ft','violet-freshness-sentinel')
YIELD node, score
RETURN node.probeId, score;
// After the await procedure returns, the fixture expects CH21-FRESH-1 to be visible.

4. What to monitor in Community vs Enterprise

SHOW FULLTEXT INDEXES is the portable database-level evidence used here: state, populationPercent, options, lastRead, readCount and failure information. Neo4j’s built-in metrics framework—including counters such as full-text queried/populated—is documented as Enterprise Edition. Community learners can still measure application latency/freshness, OS CPU/disk, query counts in their harness and index state; do not claim Enterprise metrics exist locally when they do not.

CYPHER 25
SHOW FULLTEXT INDEXES
YIELD name, state, populationPercent, lastRead, readCount,
      options, failureMessage
WHERE name STARTS WITH 'ch21_'
RETURN name, state, populationPercent, lastRead, readCount,
       options, failureMessage
ORDER BY name;

5. Freshness SLO design

Do not define freshness as “eventually.” Define a percentile and failure behavior: for example, a product rename should become searchable within a measured budget under normal write load; if not, the search UI may query by durable product ID, show a “recent update pending” state, or temporarily read the graph directly for the edited item. The exact budget comes from product requirements and measured distributions.

6. Wrong approach → failure → repair

7. Verification checklist

• The probe full-text index is ONLINE and explicitly configured eventual=true.
• Immediate visibility is recorded as observed yes/no, not predetermined.
• After awaitEventuallyConsistentIndexRefresh, the sentinel is retrievable.
• The application records commit-to-search visibility latency over repeated probes.
• Community and Enterprise monitoring capabilities are labeled correctly.

8. Production judgment

Summary and next step

Freshness is now an explicit system property: commit timing, background queue, visibility probe and SLO. Lesson 4 takes the lexical candidate set and adds what the index cannot know—stock, category, active state, permissions and graph relationships—while keeping source ranking evidence observable.

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.