# Element indexes and staged values

[Wiki](../README.md) / [Indexes and constraints](README.md)

**On this page**

- [Element (multi-entry) indexes](#element-multi-entry-indexes)
- [Removing the index](#removing-the-index)

## Element (multi-entry) indexes

An **element index** posts each element of a **list** value separately (with
its positions), so element predicates seek instead of scan. Designed for
"dimension" arrays — e.g. a draft/review/live staged value
`stages: ['ix1', null, 'ix2']`. This is a GDB extension.

```cypher
CREATE ELEMENT INDEX FOR (c:Company) ON (c.name);   // single property only
SHOW INDEXES;                                        // type column: ELEMENT
```

The planner uses it for four predicate shapes (confirm with `EXPLAIN`):

```cypher
MATCH (c:Company) WHERE 'ACME' IN c.name RETURN c;
// Match: NodeElementIndexSeek(:Company .name)            <- membership, any slot

MATCH (c:Company) WHERE c.name[2] = 'ACME' RETURN c;
// Match: NodeElementIndexSeek(:Company .name[2])         <- slot-exact

MATCH (c:Company) WHERE any(x IN c.name WHERE x >= 'ix' AND x < 'iy') RETURN c;
// Match: NodeElementIndexSeekByRange(:Company .name)     <- per-element range

MATCH (c:Company) WHERE any(x IN c.name WHERE x STARTS WITH 'ix') RETURN c;
// Match: NodeElementIndexSeekByRange(:Company .name)     <- per-element prefix
```

Semantics: a scalar value indexes as one element at position 0; `null` and
`NaN` elements are skipped (never posted); duplicate elements record every
position; nested lists/maps are one opaque key. Like every GDB index it is
declaration-only on disk and rebuilt by backfill on replay.

**Keep an element-indexed property consistently list-typed.** The *index*
accepts a scalar, but every element predicate errors at runtime when its
re-check hits a scalar-valued node: `any()` needs a list,
`'v' IN c.name` needs a list on the right, and `c.name[0]` cannot subscript a
scalar. Store `['v']` rather than `'v'` — a one-element list preserves the required type and
every predicate shape works.

**Subscript assignment** complements the dimension model (also a GDB
extension): `SET c.name[1] = 'v'` writes one slot; an index past the end pads
with `null`s and extends (so `SET c.name[3] = v` grows a new dimension with no
migration); an absent property becomes `[null × i, v]`; a scalar target is an
error.

## Removing the index

Remove the index with `DROP ELEMENT INDEX FOR (c:Company) ON (c.name)` after
the examples, provided no element-uniqueness constraint protects it.

## Related articles

[EXPLAIN and PROFILE](../cypher/planning.md) · [Resident and hybrid storage](../operations/storage.md) · [Schema and maintenance procedures](../cypher/procedures.md)
