@loradb/lora-node 0.36.0 → 0.36.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +355 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +546 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,546 @@
1
+ ---
2
+ title: "Indexes"
3
+ description: "How to create, inspect, query, and drop LoraDB indexes for range, text, point, lookup, vector, and full-text workloads."
4
+ online: "https://loradb.com/docs/queries/indexes"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Indexes
9
+
10
+ LoraDB is still schema-free by default: labels, relationship types,
11
+ and property keys appear when you write them. Indexes are optional
12
+ catalog entries that tell the in-memory store which secondary
13
+ structures to maintain for frequently used predicates, vector search,
14
+ and full-text search.
15
+
16
+ ## Create an index
17
+
18
+ ```cypher
19
+ CREATE INDEX user_email FOR (u:User) ON (u.email);
20
+ CREATE INDEX user_age IF NOT EXISTS FOR (u:User) ON (u.age);
21
+ CREATE TEXT INDEX user_name FOR (u:User) ON (u.name);
22
+ CREATE POINT INDEX venue_location FOR (v:Venue) ON (v.location);
23
+ CREATE VECTOR INDEX doc_embedding FOR (d:Doc) ON (d.embedding)
24
+ OPTIONS {indexConfig: {\`vector.dimensions\`: 1536, \`vector.similarity_function\`: 'cosine'}};
25
+ CREATE FULLTEXT INDEX article_search FOR (a:Article) ON EACH [a.title, a.body];
26
+ ```
27
+
28
+ Relationship indexes use the relationship pattern form:
29
+
30
+ ```cypher
31
+ CREATE INDEX rel_since FOR ()-[r:FOLLOWS]-() ON (r.since);
32
+ CREATE TEXT INDEX rel_note FOR ()-[r:TAGGED]-() ON (r.note);
33
+ CREATE POINT INDEX rel_location FOR ()-[r:DELIVERED]-() ON (r.location);
34
+ CREATE VECTOR INDEX rel_embedding FOR ()-[r:CONTAINS]-() ON (r.embedding)
35
+ OPTIONS {indexConfig: {\`vector.dimensions\`: 384, \`vector.similarity_function\`: 'euclidean'}};
36
+ CREATE FULLTEXT INDEX rel_summary FOR ()-[r:WROTE]-() ON EACH [r.summary];
37
+ ```
38
+
39
+ If you omit the name, LoraDB creates a deterministic `index_...` name:
40
+
41
+ ```cypher
42
+ CREATE INDEX FOR (p:Product) ON (p.sku);
43
+ ```
44
+
45
+ Index names may also come from a string parameter:
46
+
47
+ ```cypher
48
+ CREATE INDEX $name FOR (u:User) ON (u.email);
49
+ ```
50
+
51
+ ## Index kinds
52
+
53
+ | Kind | Syntax | Useful predicates |
54
+ |---|---|---|
55
+ | RANGE | `CREATE INDEX ...` or `CREATE RANGE INDEX ...` | `=`, `<`, `<=`, `>`, `>=`, bounded ranges, `STARTS WITH` (as a prefix range) when no TEXT index covers the property, and `value IN n.list` on a list property |
56
+ | TEXT | `CREATE TEXT INDEX ...` | `STARTS WITH`, `CONTAINS`, `ENDS WITH` |
57
+ | POINT | `CREATE POINT INDEX ...` | `geo.within_bbox(...)`, `geo.distance(...) <= radius` |
58
+ | LOOKUP | `CREATE LOOKUP INDEX ...` | Catalog-visible label/type token indexes |
59
+ | VECTOR | `CREATE VECTOR INDEX ... OPTIONS {indexConfig: {...}}` | `db.index.vector.queryNodes`, `db.index.vector.queryRelationships` |
60
+ | FULLTEXT | `CREATE FULLTEXT INDEX ... ON EACH [...]` | `db.index.fulltext.queryNodes`, `db.index.fulltext.queryRelationships` |
61
+
62
+ Lookup indexes are catalog entries over labels or relationship types:
63
+
64
+ ```cypher
65
+ CREATE LOOKUP INDEX node_labels FOR (n) ON EACH node.labels(n);
66
+ CREATE LOOKUP INDEX rel_types FOR ()-[r]-() ON EACH edge.type(r);
67
+ ```
68
+
69
+ A composite RANGE index covers several properties. Each property also
70
+ gets the single-property seeks above, and the index as a whole answers
71
+ an equality on its leading properties with an ordered range on its last
72
+ one: see [Ordered seeks on a composite index](#ordered-seeks-on-a-composite-index).
73
+
74
+ ```cypher
75
+ CREATE INDEX activity_person_at FOR (a:Activity) ON (a.person, a.at);
76
+ ```
77
+
78
+ ## Vector indexes
79
+
80
+ Vector indexes are single-property node or relationship indexes. They
81
+ require an `indexConfig` map with:
82
+
83
+ - `vector.dimensions` - integer dimension in `1..=4096`;
84
+ - `vector.similarity_function` - `'cosine'`, `'euclidean'`, `'dot'`
85
+ (alias `'dot_product'`), or `'manhattan'`.
86
+
87
+ ```cypher
88
+ CREATE VECTOR INDEX movie_embedding
89
+ FOR (m:Movie)
90
+ ON (m.embedding)
91
+ OPTIONS {indexConfig: {
92
+ \`vector.dimensions\`: 3,
93
+ \`vector.similarity_function\`: 'cosine'
94
+ }};
95
+
96
+ CREATE (:Movie {title: 'A', embedding: [1.0, 0.0, 0.0]::VECTOR<FLOAT32>(3)});
97
+ CREATE (:Movie {title: 'B', embedding: [0.9, 0.1, 0.0]::VECTOR<FLOAT32>(3)});
98
+
99
+ CALL db.index.vector.queryNodes('movie_embedding', 2, [1.0, 0.0, 0.0])
100
+ YIELD node, score;
101
+ ```
102
+
103
+ The relationship procedure has the same shape but yields
104
+ `relationship`:
105
+
106
+ ```cypher
107
+ CALL db.index.vector.queryRelationships('rel_embedding', 10, $query)
108
+ YIELD relationship, score;
109
+ ```
110
+
111
+ `k` must be positive. The query argument can be a `VECTOR`, a
112
+ `[...]::VECTOR<COORD>(DIM)` cast, a numeric list, or a parameter containing a vector.
113
+ Numeric lists are coerced to `FLOAT32` vectors. The query dimension
114
+ must match the index dimension. Results are sorted by descending score,
115
+ ties broken by ascending entity id.
116
+
117
+ ### Restricting results
118
+
119
+ An optional fourth argument takes an options map with two keys, both
120
+ optional.
121
+
122
+ `restrictTo` is a list of entity ids (or node / relationship values) that
123
+ the results may come from:
124
+
125
+ ```cypher
126
+ CALL db.index.vector.queryNodes('movie_embedding', 5, $query, {restrictTo: $ids})
127
+ YIELD node, score;
128
+ ```
129
+
130
+ `where` filters by the entity's properties. Each entry is
131
+ `property: condition`, all of which must hold:
132
+
133
+ | Condition | Holds when the property |
134
+ |---|---|
135
+ | a scalar, `{eq: v}` | equals `v` |
136
+ | a list, `{in: [...]}` | equals one of the values |
137
+ | `{gt: v}`, `{gte: v}`, `{lt: v}`, `{lte: v}` | compares so with `v`; combine one lower and one upper bound for a range |
138
+ | `{withinBBox: [lowerLeft, upperRight]}` | is a point inside the box, as [`geo.within_bbox`](../functions/spatial.md#geowithin_bbox) |
139
+
140
+ ```cypher
141
+ CALL db.index.vector.queryNodes('event_taste', 20, $taste, {where: {
142
+ location: {withinBBox: [$southWest, $northEast]},
143
+ startsAt: {gte: $from, lt: $to},
144
+ status: 'confirmed'
145
+ }})
146
+ YIELD node, score
147
+ RETURN node.name AS event, score;
148
+ ```
149
+
150
+ The filter runs before the search, not after it, so the query still
151
+ returns `k` hits when `k` entities match. It reads a RANGE or POINT
152
+ index on one of the properties where one exists (the most selective
153
+ kind of condition first: a short `in` list, then a box, then a closed
154
+ range), checks every candidate against all conditions, and then scores
155
+ only the candidates. A filter on unindexed properties scans the label.
156
+ With both keys, a result must satisfy both. Comparisons follow Cypher:
157
+ a `null` property never matches, and a condition of `null` is rejected,
158
+ as are unknown operators and both `gt` and `gte` on one property.
159
+
160
+ On 300,000 events with 64-dimension vectors, the 20 nearest events in a
161
+ country-sized box and a 60-day window take about 0.4 ms this way, against
162
+ 1.6 ms for collecting the ids in a `MATCH` and passing them as
163
+ `restrictTo`, and 2 ms for sorting the matches by
164
+ `vector.similarity`.
165
+
166
+ Unknown option keys are rejected. When the `CALL` stands alone (nothing
167
+ after `YIELD`), the options must be an inline map literal — values
168
+ inside it may be parameters, as above, but `$opts` as the whole map is
169
+ rejected. A `CALL` followed by further clauses (`RETURN`, `WITH`, …)
170
+ accepts a map parameter too.
171
+
172
+ ### Providers: flat (exact) and HNSW (approximate)
173
+
174
+ Each vector index has a backend, chosen with the optional
175
+ `vector.indexProvider` key:
176
+
177
+ | Provider | Behaviour |
178
+ |---|---|
179
+ | `'flat'` (default) | Exact. Scores every entity in the index scope and returns the true top `k`. |
180
+ | `'hnsw'` | Approximate nearest-neighbour search over an HNSW graph. Much faster on large scopes; may miss some true neighbours. |
181
+
182
+ ```cypher
183
+ CREATE VECTOR INDEX doc_embedding_ann
184
+ FOR (d:Doc)
185
+ ON (d.embedding)
186
+ OPTIONS {indexConfig: {
187
+ \`vector.dimensions\`: 384,
188
+ \`vector.similarity_function\`: 'cosine',
189
+ \`vector.indexProvider\`: 'hnsw',
190
+ \`vector.hnsw.m\`: 16,
191
+ \`vector.hnsw.ef_construction\`: 200,
192
+ \`vector.hnsw.ef_search\`: 100
193
+ }};
194
+
195
+ CALL db.index.vector.queryNodes('doc_embedding_ann', 10, $query)
196
+ YIELD node, score;
197
+ ```
198
+
199
+ Queries are unchanged — the same `db.index.vector.*` procedures run
200
+ against either provider. HNSW tuning keys, all optional:
201
+
202
+ | Key | Default | Range | Effect |
203
+ |---|---|---|---|
204
+ | `vector.hnsw.m` | `16` | `4..=128` | Neighbours per node per layer. Higher improves recall and costs memory and insert time. |
205
+ | `vector.hnsw.ef_construction` | `200` | `16..=2000` | Candidate list size while building the graph. Higher gives a better graph and slower inserts. |
206
+ | `vector.hnsw.ef_search` | `100` | `16..=2000` | Candidate list size per query (never below `k`). Higher improves recall and slows queries. |
207
+ | `vector.hnsw.quantization` | `'none'` | `'none'`, `'int8'` | `'int8'` stores coordinates as 8-bit integers (about 4× less memory, slightly less precise scores). Requires `'cosine'` similarity and coordinates in `[-1, 1]` (unit-normalised embeddings); larger values are clipped. |
208
+
209
+ Out-of-range or mistyped values fail `CREATE VECTOR INDEX`, and any
210
+ provider other than `'flat'` or `'hnsw'` is rejected. The `vector.hnsw.*`
211
+ keys are validated for every vector index but only take effect with
212
+ `'hnsw'`. `SHOW INDEXES` lists them under `options`. A label or
213
+ relationship type and property can carry only one vector index, so
214
+ switching provider means `DROP INDEX` and creating it again.
215
+
216
+ With `restrictTo` or `where`, HNSW widens its search internally, but a
217
+ very selective filter can still return fewer than `k` hits; raise
218
+ `vector.hnsw.ef_search` or use a flat index for tightly filtered
219
+ queries.
220
+
221
+ Building an HNSW index over existing data (`CREATE VECTOR INDEX` on a
222
+ populated label, or the first query of a lazily populated one) uses
223
+ every core. The result does not depend on the core count: the same data
224
+ always gives the same graph. 100,000 vectors of 64 dimensions build in
225
+ about 6 seconds on a 10-core laptop. Vectors written later are added one
226
+ at a time as part of their write.
227
+
228
+ A query searches every layer of the graph with its full candidate list,
229
+ not only the bottom one, so a query that lies between clusters (a taste
230
+ profile between two genres) still reaches the true neighbours in each.
231
+ On 100,000 clustered 64-dimension vectors with such queries, the share
232
+ of the true top 20 found is about 94% at the default `ef_search` of 100
233
+ (0.4 ms), 98% at 200 (0.6 ms) and 99.5% at 400 (0.9 ms). Queries close to
234
+ one cluster find 99% at the default.
235
+
236
+ Memory: a flat index keeps each vector as 4-byte coordinates (about
237
+ 4.8 bytes per dimension, counting its bookkeeping); an HNSW index adds
238
+ its links, about 9 bytes per dimension at 64 dimensions with the default
239
+ `m`. Both are on top of the vector stored in the node itself.
240
+ `vector.hnsw.quantization: 'int8'` stores 1 byte per coordinate. Snapshots carry the HNSW graph, so a restore returns the same
241
+ results as before; after a WAL recovery the graph is rebuilt
242
+ from the stored vectors.
243
+
244
+ ### Lazy population
245
+
246
+ `vector.populate.async: true` skips the backfill at create time. The
247
+ index shows as `POPULATING` in `SHOW INDEXES` until the first query
248
+ against it builds it and flips it to `ONLINE`.
249
+
250
+ ## Full-text indexes
251
+
252
+ Full-text indexes use `ON EACH [...]` and can cover multiple properties.
253
+ Node full-text indexes may cover multiple labels; relationship
254
+ full-text indexes may cover multiple relationship types:
255
+
256
+ ```cypher
257
+ CREATE FULLTEXT INDEX article_search
258
+ FOR (a:Article|Note)
259
+ ON EACH [a.title, a.body]
260
+ OPTIONS {\`fulltext.analyzer\`: 'standard'};
261
+
262
+ CALL db.index.fulltext.queryNodes('article_search', 'graph search')
263
+ YIELD node, score;
264
+ ```
265
+
266
+ Relationship full-text search yields `relationship`:
267
+
268
+ ```cypher
269
+ CREATE FULLTEXT INDEX wrote_search
270
+ FOR ()-[r:WROTE]-()
271
+ ON EACH [r.summary];
272
+
273
+ CALL db.index.fulltext.queryRelationships('wrote_search', 'graph')
274
+ YIELD relationship, score;
275
+ ```
276
+
277
+ Procedure calls return the yielded columns directly. The current
278
+ analyzer tokenizes by lowercasing and splitting on
279
+ non-alphanumeric characters. Multiple query terms use AND semantics:
280
+ all terms must be present. Scores are based on summed term frequency
281
+ and results are sorted by descending score.
282
+
283
+ A list property is indexed element by element: each string in the list
284
+ is tokenized and indexed, whether the list was written before or after
285
+ the index was created. Non-string list elements and non-string
286
+ properties are skipped silently, without an error:
287
+
288
+ ```cypher
289
+ CREATE FULLTEXT INDEX article_tags FOR (a:Article) ON EACH [a.tags];
290
+
291
+ CREATE (:Article {title: 'Graphs', tags: ['graph databases', 'cypher', 42]});
292
+
293
+ CALL db.index.fulltext.queryNodes('article_tags', 'cypher')
294
+ YIELD node, score
295
+ RETURN node.title, score;
296
+ ```
297
+
298
+ `fulltext.analyzer` accepts `'standard'` and `'simple'`; unsupported
299
+ names are rejected. `fulltext.eventually_consistent` accepts a boolean
300
+ option, but index maintenance is currently synchronous.
301
+
302
+ A third argument, `{skip, limit}`, pages through the ranking inside the
303
+ index: only the best `skip + limit` matches are ranked and turned into
304
+ rows. A broad query (a short prefix such as `a*`) over a large index
305
+ otherwise yields a row for every match before any `LIMIT` later in the
306
+ query applies:
307
+
308
+ ```cypher
309
+ CALL db.index.fulltext.queryNodes('article_search', 'gra*', {skip: 20, limit: 10})
310
+ YIELD node, score
311
+ RETURN node.title, score;
312
+ ```
313
+
314
+ The limit applies before a `WHERE` on the yielded rows: that query
315
+ filters within the best `limit` matches. Other option keys are rejected.
316
+
317
+ ## Inspect indexes
318
+
319
+ ```cypher
320
+ SHOW INDEXES;
321
+ ```
322
+
323
+ Rows contain:
324
+
325
+ | Column | Meaning |
326
+ |---|---|
327
+ | `name` | Index name |
328
+ | `type` | `RANGE`, `TEXT`, `POINT`, or `LOOKUP` |
329
+ | `entityType` | `NODE` or `RELATIONSHIP` |
330
+ | `labelsOrTypes` | Label or relationship type scope, empty for lookup indexes |
331
+ | `properties` | Indexed property keys |
332
+ | `state` | Currently `ONLINE` for created indexes |
333
+ | `populationPercent` | `100.0` for online indexes |
334
+
335
+ `type` can be `RANGE`, `TEXT`, `POINT`, `LOOKUP`, `VECTOR`, or
336
+ `FULLTEXT`.
337
+
338
+ Use a type filter when you only want one kind:
339
+
340
+ ```cypher
341
+ SHOW RANGE INDEXES;
342
+ SHOW TEXT INDEXES;
343
+ SHOW POINT INDEXES;
344
+ SHOW LOOKUP INDEXES;
345
+ SHOW VECTOR INDEXES;
346
+ SHOW FULLTEXT INDEXES;
347
+ SHOW ALL INDEXES;
348
+ ```
349
+
350
+ The singular spelling also works:
351
+
352
+ ```cypher
353
+ SHOW RANGE INDEX;
354
+ ```
355
+
356
+ Catalog output can be shaped with a `YIELD`-anchored pipeline:
357
+
358
+ ```cypher
359
+ SHOW INDEXES
360
+ YIELD name, type, entityType
361
+ WHERE type = 'VECTOR'
362
+ RETURN name
363
+ ORDER BY name
364
+ LIMIT 10;
365
+ ```
366
+
367
+ ## Drop an index
368
+
369
+ ```cypher
370
+ DROP INDEX user_email;
371
+ DROP INDEX maybe_missing IF EXISTS;
372
+ ```
373
+
374
+ Dropping a missing index without `IF EXISTS` returns a stable
375
+ GQLSTATUS-shaped error (`42N51`). Creating an index with a duplicate
376
+ name returns `22N71`; creating an equivalent index under a different
377
+ name returns `22N70`. `IF NOT EXISTS` turns either conflict into a
378
+ no-op.
379
+
380
+ Indexes owned by constraints cannot be dropped directly. Use
381
+ [`DROP CONSTRAINT`](./constraints.md#drop-constraints) for those.
382
+
383
+ ## What the optimizer uses
384
+
385
+ Declared indexes can replace scan-and-filter plans with specialized
386
+ operators:
387
+
388
+ ```cypher
389
+ CREATE INDEX person_age FOR (p:Person) ON (p.age);
390
+ CREATE TEXT INDEX person_name FOR (p:Person) ON (p.name);
391
+ CREATE POINT INDEX place_location FOR (p:Place) ON (p.location);
392
+ ```
393
+
394
+ Inspect the plan with your binding's `explain` method or HTTP
395
+ `POST /explain`. These queries should show the specialized scan names
396
+ in the returned plan tree:
397
+
398
+ ```cypher
399
+ MATCH (p:Person) WHERE p.age >= 30 AND p.age < 50 RETURN p
400
+ ;// NodeByPropertyRangeScan
401
+
402
+ MATCH (p:Person) WHERE p.name STARTS WITH 'Al' RETURN p
403
+ ;// NodeByTextScan with a TEXT index; NodeByPropertyRangeScan with only a RANGE index
404
+
405
+ MATCH (p:Place)
406
+ WHERE geo.within_bbox(
407
+ p.location,
408
+ {x: 0, y: 0}::POINT,
409
+ {x: 100, y: 100}::POINT
410
+ )
411
+ RETURN p
412
+ // NodeByPointScan
413
+ ```
414
+
415
+ A WGS-84 bounding box whose lower-left longitude is greater than its
416
+ upper-right longitude crosses the antimeridian. The POINT index answers
417
+ it with two seeks, one for `[lowerLeft.longitude, 180]` and one for
418
+ `[-180, upperRight.longitude]`, for node and relationship indexes alike:
419
+
420
+ ```cypher
421
+ MATCH (v:Venue)
422
+ WHERE geo.within_bbox(
423
+ v.location,
424
+ {longitude: 170, latitude: -50}::POINT,
425
+ {longitude: -170, latitude: -30}::POINT
426
+ )
427
+ RETURN v
428
+ ```
429
+
430
+ See [`geo.within_bbox`](../functions/spatial.md#geowithin_bbox) for the full
431
+ semantics.
432
+
433
+ The POINT index files points in grid cells: 100 units wide for
434
+ Cartesian points and 0.25 degrees for WGS-84 points, unless the index
435
+ sets `cellSize` in its `indexConfig` (which then applies to both). A
436
+ `geo.distance(p.location, $here) <= radius` seek on WGS-84 points reads
437
+ the cells within the radius in metres, including across a pole or the
438
+ antimeridian.
439
+
440
+ ### Ordered seeks on a composite index
441
+
442
+ With a composite RANGE index on `(a, b)`, a query that fixes `a` with
443
+ `=`, bounds `b` (or tests `b IS NOT NULL`) and sorts on `b` reads its
444
+ rows from the index in order. A `LIMIT` then stops after that many
445
+ index entries, however many rows match:
446
+
447
+ ```cypher
448
+ CREATE INDEX activity_person_at FOR (a:Activity) ON (a.person, a.at);
449
+
450
+ MATCH (a:Activity)
451
+ WHERE a.person = $person AND a.at >= $since
452
+ RETURN a
453
+ ORDER BY a.at DESC
454
+ LIMIT 20
455
+ ;// NodeByPropertyRangeScan, prefix: person, order: DESC
456
+ ```
457
+
458
+ An index on three or more properties works the same way with an
459
+ equality on every property but the last. The equality values may be
460
+ parameters or literals; the predicate still runs on every row, so the
461
+ results are those of the plan without the index. On 300,000 activities
462
+ of 20 people, the query above takes 0.02 ms, against 10 ms without the
463
+ composite index. Without a bound or `IS NOT NULL` on the last property,
464
+ rows that lack it would be missing from the index, so the planner does
465
+ not use it.
466
+
467
+ ### IS NOT NULL
468
+
469
+ `n.key IS NOT NULL` seeks a RANGE index on `key`: it lists the nodes the
470
+ index holds, including values without an order (durations, points). It
471
+ pays off when few nodes of the label have the property. For 200 of
472
+ 200,000 it takes 0.04 ms instead of a 25 to 40 ms label scan; when half or more
473
+ of the label has it, the scan runs as before.
474
+
475
+ ### List properties
476
+
477
+ A RANGE index on a property that holds lists keeps each list twice: whole,
478
+ for `n.tags = ['a', 'b']` and ranges over lists, and by each distinct
479
+ element, for membership. `value IN n.tags` and
480
+ `any(x IN n.tags WHERE x = value)` then seek the nodes whose list holds the
481
+ value instead of scanning the label:
482
+
483
+ ```cypher
484
+ CREATE INDEX event_genres FOR (e:Event) ON (e.genreLineage);
485
+
486
+ MATCH (e:Event) WHERE $genre IN e.genreLineage RETURN e
487
+ ;// NodeByPropertyScan, mode: element
488
+ ```
489
+
490
+ The value may be a parameter, a literal or a value from an earlier clause.
491
+ Results are exactly those of the unindexed filter: a node whose list
492
+ holds the value twice comes back once, numbers match across integer and
493
+ float (`1` finds `1.0`), a `null` value finds nothing, and a list with a
494
+ `null` element and no match is filtered out (the test is `null`). The
495
+ plan's estimate is the average number of nodes per list element; beside
496
+ another indexed test (`e.city = $c AND $g IN e.genreLineage`) the planner
497
+ seeks whichever finds fewer rows, and a keyset page
498
+ (`... AND e.key > $after ORDER BY e.key LIMIT n`) still pages in order.
499
+ Elements without an index image (durations, points, vectors) are skipped;
500
+ seeking one scans. Relationship indexes seek list elements the same way
501
+ (`RelByListElementScan`).
502
+
503
+ The same rewrite family exists for relationship scans when the pattern
504
+ can be satisfied from the relationship index:
505
+
506
+ ```cypher
507
+ CREATE INDEX knows_since FOR ()-[r:KNOWS]-() ON (r.since);
508
+
509
+ MATCH ()-[r:KNOWS]->()
510
+ WHERE r.since > 2020
511
+ RETURN r;
512
+ ```
513
+
514
+ The original predicate still runs after the index candidate set is
515
+ produced. That keeps semantics correct for compound predicates and for
516
+ conservative TEXT/POINT candidate indexes.
517
+
518
+ ## Durability
519
+
520
+ Index catalog changes are part of the normal write path. WAL-backed
521
+ databases replay `CREATE INDEX` and `DROP INDEX` events during recovery,
522
+ and snapshots include the index catalog trailer in the current body
523
+ format. Older snapshots without a catalog still load with an empty
524
+ index list.
525
+
526
+ ## Limitations
527
+
528
+ - Vector indexes default to the exact `flat` provider; HNSW is opt-in
529
+ via `vector.indexProvider: 'hnsw'` and returns approximate results.
530
+ - Full-text query strings use term intersection and term-frequency
531
+ scoring, not a Lucene-style query language.
532
+ - A composite RANGE index is used for ordered seeks with an equality on
533
+ its leading properties; other predicates use its properties one at a
534
+ time.
535
+ - FULLTEXT indexes require `ON EACH [...]`; non-full-text indexes use
536
+ `ON (...)`.
537
+
538
+ ## See also
539
+
540
+ - [WHERE](./where.md) - predicates that can benefit from indexes.
541
+ - [Constraints](./constraints.md) - uniqueness, existence, keys, and type checks.
542
+ - [Spatial functions](../functions/spatial.md) - point predicates.
543
+ - [Vector values](../data-types/vectors.md) - storing and querying embeddings.
544
+ - [HTTP `POST /explain`](https://loradb.com/docs/api/http#post-explain) - inspect the
545
+ physical plan from HTTP, or use the equivalent binding methods.
546
+ - [Limitations](../limitations.md) - remaining schema and storage gaps.