Query Vector Indexes with the Modern Cypher SEARCH Clause and Understand Approximate-Neighbor Limits

CYPHER 25
// Disposable Chapter 22 fixture. Safe to rerun after the cleanup block.
CREATE CONSTRAINT ch22_product_id IF NOT EXISTS
FOR (p:Product) REQUIRE p.productId IS UNIQUE;
CREATE CONSTRAINT ch22_category_id IF NOT EXISTS
FOR (c:Category) REQUIRE c.categoryId IS UNIQUE;
CREATE CONSTRAINT ch22_store_id IF NOT EXISTS
FOR (s:Store) REQUIRE s.storeId IS UNIQUE;
CREATE CONSTRAINT ch22_doc_id IF NOT EXISTS
FOR (d:KnowledgeDocument) REQUIRE d.documentId IS UNIQUE;
CREATE CONSTRAINT ch22_chunk_id IF NOT EXISTS
FOR (c:Chunk) REQUIRE c.chunkId IS UNIQUE;

MERGE (cam:Category {categoryId:'CAT-22-CAM'}) SET cam.name='Cameras', cam.labTag='ch22'
MERGE (out:Category {categoryId:'CAT-22-OUT'}) SET out.name='Outdoor', out.labTag='ch22'
MERGE (sec:Category {categoryId:'CAT-22-SEC'}) SET sec.name='Security', sec.labTag='ch22'
MERGE (acc:Category {categoryId:'CAT-22-ACC'}) SET acc.name='Accessories', acc.labTag='ch22'
MERGE (st:Store {storeId:'ST-22-CENTRAL'}) SET st.name='AtlasMart Central', st.labTag='ch22';

UNWIND [
 {id:'P-2201',name:'Trail Camera Pro',description:'Weatherproof wildlife trail camera with infrared night vision and long battery life',tags:['wildlife','trail','infrared','outdoor'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:5,featured:true, emb:[0.95,0.85,0.25,0.05,0.10,0.90,0.05,0.05]},
 {id:'P-2202',name:'Trail Camera Mini',description:'Compact wildlife camera for trails, gardens, and backyard monitoring',tags:['wildlife','trail','compact'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:0,featured:false,emb:[0.90,0.80,0.15,0.05,0.05,0.82,0.05,0.05]},
 {id:'P-2203',name:'Indoor Security Camera',description:'Wi-Fi home security camera with motion alerts and night vision',tags:['security','indoor','night vision'],active:true,cat:'CAT-22-SEC',catCode:'SECURITY',region:'CENTRAL',qty:7,featured:false,emb:[0.92,0.10,0.95,0.02,0.05,0.05,0.05,0.05]},
 {id:'P-2204',name:'Trail Running Hydration Vest',description:'Lightweight hydration vest for long trail runs and mountain races',tags:['running','trail','hydration'],active:true,cat:'CAT-22-OUT',catCode:'OUTDOOR',region:'CENTRAL',qty:11,featured:false,emb:[0.02,0.88,0.02,0.95,0.10,0.10,0.05,0.02]},
 {id:'P-2205',name:'Action Camera 4K',description:'Water-resistant action sports camera for cycling, hiking, and travel',tags:['action','sports','camera'],active:true,cat:'CAT-22-CAM',catCode:'CAMERA',region:'CENTRAL',qty:3,featured:true,emb:[0.90,0.45,0.20,0.10,0.95,0.15,0.05,0.03]},
 {id:'P-2206',name:'Wildlife Field Guide',description:'Illustrated guide to birds and mammals for outdoor observation',tags:['wildlife','book','outdoor'],active:true,cat:'CAT-22-OUT',catCode:'OUTDOOR',region:'CENTRAL',qty:6,featured:false,emb:[0.05,0.55,0.05,0.05,0.05,0.95,0.05,0.02]},
 {id:'P-2207',name:'Solar Trail Charger',description:'Solar charger for outdoor cameras, sensors, and trail equipment',tags:['solar','trail','charger'],active:true,cat:'CAT-22-ACC',catCode:'ACCESSORY',region:'CENTRAL',qty:0,featured:false,emb:[0.08,0.75,0.10,0.05,0.10,0.10,0.95,0.02]},
 {id:'P-2208',name:'Refurbished Trail Camera',description:'Older trail camera unit retained for support reference only',tags:['trail','camera','refurbished'],active:false,cat:'CAT-22-CAM',catCode:'CAMERA',region:'ARCHIVE',qty:2,featured:false,emb:[0.88,0.68,0.15,0.05,0.05,0.60,0.05,0.95]}
] 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.categoryCode=row.catCode, p.region=row.region,
    p.featured=row.featured, p.embedding=row.emb,
    p.embeddingModel='atlasmart-deterministic-v1', p.embeddingVersion='2026-09-lab',
    p.labTag='ch22'
WITH row,p
MATCH (cat:Category {categoryId:row.cat}), (st:Store {storeId:'ST-22-CENTRAL'})
MERGE (p)-[:IN_CATEGORY]->(cat)
MERGE (p)-[stock:STOCKED_AT]->(st)
SET stock.quantity=row.qty, stock.labTag='ch22';

MERGE (d1:KnowledgeDocument {documentId:'DOC-22-TRAILCAM'})
SET d1.title='Trail Camera Pro field manual', d1.uri='atlasmart://manuals/P-2201', d1.version='2026.09', d1.labTag='ch22'
MERGE (d2:KnowledgeDocument {documentId:'DOC-22-SECURITY'})
SET d2.title='Camera selection guide', d2.uri='atlasmart://guides/camera-selection', d2.version='2026.09', d2.labTag='ch22';

UNWIND [
 {id:'CHK-2201',doc:'DOC-22-TRAILCAM',seq:1,text:'Trail Camera Pro is weatherproof and optimized for wildlife monitoring on outdoor trails.',emb:[0.96,0.86,0.12,0.02,0.02,0.94,0.02,0.02],products:['P-2201'],cats:['CAT-22-CAM']},
 {id:'CHK-2202',doc:'DOC-22-TRAILCAM',seq:2,text:'Infrared night vision records wildlife without visible illumination and battery life is designed for field deployment.',emb:[0.88,0.72,0.25,0.02,0.02,0.90,0.02,0.02],products:['P-2201'],cats:['CAT-22-CAM']},
 {id:'CHK-2203',doc:'DOC-22-SECURITY',seq:1,text:'Indoor Security Camera focuses on Wi-Fi motion alerts and indoor night vision rather than outdoor wildlife use.',emb:[0.84,0.08,0.96,0.02,0.02,0.06,0.02,0.02],products:['P-2203'],cats:['CAT-22-SEC']},
 {id:'CHK-2204',doc:'DOC-22-SECURITY',seq:2,text:'Choose an outdoor trail camera when weather resistance and wildlife observation matter; choose indoor security cameras for home alerting.',emb:[0.90,0.68,0.55,0.02,0.02,0.72,0.02,0.02],products:['P-2201','P-2203'],cats:['CAT-22-CAM','CAT-22-SEC']}
] AS row
MERGE (c:Chunk {chunkId:row.id})
SET c.seq=row.seq, c.text=row.text, c.embedding=row.emb,
    c.embeddingModel='atlasmart-deterministic-v1', c.embeddingVersion='2026-09-lab', c.labTag='ch22'
WITH row,c
MATCH (d:KnowledgeDocument {documentId:row.doc})
MERGE (c)-[:FROM_DOCUMENT]->(d)
WITH row,c
UNWIND row.products AS pid
MATCH (p:Product {productId:pid})
MERGE (c)-[:MENTIONS]->(p)
WITH row,c
UNWIND row.cats AS cid
MATCH (cat:Category {categoryId:cid})
MERGE (c)-[:MENTIONS]->(cat);

MATCH (a:Chunk {chunkId:'CHK-2201'}),(b:Chunk {chunkId:'CHK-2202'}) MERGE (a)-[:NEXT_CHUNK]->(b);
MATCH (a:Chunk {chunkId:'CHK-2203'}),(b:Chunk {chunkId:'CHK-2204'}) MERGE (a)-[:NEXT_CHUNK]->(b);

CREATE FULLTEXT INDEX ch22_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 VECTOR INDEX ch22_product_vector IF NOT EXISTS
FOR (p:Product)
ON p.embedding
WITH [p.active,p.categoryCode,p.region]
OPTIONS {indexConfig:{
  `vector.dimensions`:8,
  `vector.similarity_function`:'cosine',
  `vector.quantization.type`:'scalar',
  `vector.default_search_expansion_factor`:1.5
}};

CREATE VECTOR INDEX ch22_chunk_vector IF NOT EXISTS
FOR (c:Chunk)
ON c.embedding
WITH [c.embeddingVersion,c.seq]
OPTIONS {indexConfig:{
  `vector.dimensions`:8,
  `vector.similarity_function`:'cosine'
}};

CALL db.awaitIndexes(300);

:param qvec => [1.0,0.8,0.1,0.0,0.0,0.9,0.0,0.0];
:param k => 4;

CYPHER 25
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $qvec
    LIMIT $k
  ) SCORE AS similarityScore
RETURN p.productId AS productId,p.name AS name,similarityScore;
// SEARCH returns approximate nearest neighbors ordered by the index similarity signal.

CYPHER 25
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $qvec
    WHERE p.active = true AND p.categoryCode = 'CAMERA'
    LIMIT 4
  ) SCORE AS similarityScore
RETURN p.productId AS productId,p.name AS name,p.active,p.categoryCode,similarityScore;
// The filter is inside SEARCH because active/categoryCode were declared in WITH [...] at index creation.

CYPHER 25
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $qvec
    LIMIT 4
  ) SCORE AS similarityScore
WHERE p.active = true AND p.categoryCode = 'CAMERA'
RETURN p.productId AS productId,p.name AS name,similarityScore;
// This WHERE is a post-filter. It can return fewer than four rows because ANN chose candidates first.

CYPHER 25
MATCH (p:Product {labTag:'ch22'})
WITH p, vector.similarity.cosine(p.embedding,$qvec) AS exactScore
ORDER BY exactScore DESC, p.productId
LIMIT $k
RETURN p.productId AS productId,p.name AS name,exactScore;
// For this fixed 8-row fixture, the exact top candidates should begin with P-2202 and P-2201.
// Capture the complete runtime result; do not hard-code ANN equivalence from this tiny graph.

from neo4j import GraphDatabase
from statistics import median
from time import perf_counter

URI="bolt://localhost:7687"
AUTH=("neo4j","atlasmart-course-2026")
QVEC=[1.0,0.8,0.1,0.0,0.0,0.9,0.0,0.0]
K=4
REPEATS=30

EXACT="""
MATCH (p:Product {labTag:'ch22'})
WITH p,vector.similarity.cosine(p.embedding,$qvec) AS score
ORDER BY score DESC,p.productId LIMIT $k
RETURN p.productId AS id,score
"""
ANN="""
MATCH (p:Product)
  SEARCH p IN (VECTOR INDEX ch22_product_vector FOR $qvec LIMIT $k)
  SCORE AS score
RETURN p.productId AS id,score
"""

with GraphDatabase.driver(URI,auth=AUTH) as driver:
    exact,_,_=driver.execute_query(EXACT,qvec=QVEC,k=K,database_="neo4j")
    exact_ids=[r["id"] for r in exact]
    times=[]; ann_ids=[]
    for _ in range(REPEATS):
        t0=perf_counter()
        ann,_,_=driver.execute_query(ANN,qvec=QVEC,k=K,database_="neo4j")
        times.append((perf_counter()-t0)*1000)
        ann_ids=[r["id"] for r in ann]
    recall=len(set(exact_ids)&set(ann_ids))/K
    print({"exact":exact_ids,"ann":ann_ids,"recall_at_k":recall,
           "median_client_ms":median(times),"samples":REPEATS})

# This tiny fixture may produce recall@4 == 1.0. That proves only this fixture/run.
# Repeat on a representative corpus and record p50/p95/p99 plus server/resource evidence.

CYPHER 25
PROFILE
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $qvec
    WHERE p.active = true
    LIMIT 4
  ) SCORE AS similarityScore
RETURN p.productId,p.name,similarityScore;
// On current releases, inspect the plan for the vector-index search operator rather than assuming a label scan.

CYPHER 25
:param badVec => [1.0,0.8,0.1,0.0,0.0,0.9,0.0];
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $badVec
    LIMIT 4
  )
RETURN p.productId;
// Expected boundary: query fails because the configured vector dimension is 8 but badVec has 7 values.

CYPHER 25
MATCH (p:Product)
  SEARCH p IN (
    VECTOR INDEX ch22_product_vector
    FOR $qvec
    WHERE p.featured = true
    LIMIT 4
  )
RETURN p.productId;
// Expected boundary: featured was NOT declared as an additional filter property in ch22_product_vector.

// Compatibility history for pre-2026.01 servers / migration adapters:
CALL db.index.vector.queryNodes('ch22_product_vector',4,$qvec)
YIELD node,score
RETURN node.productId,score;
// Current 2026.07 course path uses SEARCH instead.