Index management
Purpose: Operate Oak indexes: deployment, reindexing, monitoring lag and keeping definitions healthy as content grows.
Who this page is for
| Audience | Why it matters to you |
|---|---|
| Platform engineers | Operators |
| Backend engineers | Index definition owners |
Index types you operate
| Type | Backs | Operational trait |
|---|---|---|
| Lucene (async) | Full-text + most property queries | Indexed asynchronously — lag exists by design |
| Property (synchronous) | Unique/critical lookups | Immediate but write-cost on every commit |
| Counter/nodetype internals | System | Leave alone |
Async lag consequence: content saved a moment ago may not be query-visible for seconds. Code that writes-then-queries must not assume immediacy (queries).
Deploying index changes
- Definitions are code (/oak:index via package), reviewed like schema migrations — because they are.
- New/changed Lucene index ⇒ (re)index cost proportional to content volume. On big repos, plan it: off-peak, monitored, using oak-run for heavy rebuilds where appropriate.
- Never reindex as a superstition ("try reindexing" is the AEM "have you tried turning it off"). Reindex when: definition changed, corruption diagnosed, or upgrade notes say so. Blind reindexing of large indexes costs hours and masks the real cause.
Monitoring
| Signal | Meaning |
|---|---|
| Async indexing lag (JMX IndexStats: lastIndexedTime drift) | Indexing falling behind writes — investigate before queries "lose" content |
| Traversal warnings in error.log | A query lost its index — new code or definition regression (slow queries) |
| Index disk growth | Definitions indexing too much (includedPaths/properties too broad) |
| Reindex jobs running unexpectedly | Someone set reindex=true in prod — find out who and why |
Definition hygiene
Scope tightly: includedPaths to your content roots, only queried properties, analyzed only where full-text is real. Every custom index has an owner comment (which feature/query needs it) — orphan indexes accumulate write cost forever and nobody dares delete undocumented ones.