Guide · updated
Custom Oak indexes on AEM as a Cloud Service: naming, deployment and testing
Indexes are one of the quieter migration risks. An AEM 6.5 instance often carries indexes created by hand in CRXDE years ago. On AEM as a Cloud Service, indexes are code: versioned, deployed through Cloud Manager and built before traffic switches to a new release.
Naming
| Kind | Convention | Example |
|---|---|---|
| Fully custom index | <prefix>.<indexName>-<productVersion>-custom-<customVersion> | /oak:index/acme.product-1-custom-2 |
| Customised out-of-the-box index | the product index name followed by -custom- and a number | damAssetLucene-8-custom-1 |
Bump the custom version for every change. Adobe asks you to treat deployed index definitions as immutable; to remove an index, deploy a new version that replaces it, such as a dummy index.
Deployment
- Definitions live in the ui.apps package under _oak_index and are deployed by Cloud Manager.
- Adobe recommends filevault-package-maven-plugin 1.3.2 or later with immutableRootNodeNames set to apps,libs,oak:index, allowIndexDefinitions enabled for custom index definitions, and noIntermediateSaves so configurations are added atomically.
- For most indexes Adobe recommends Simplified Index Management with a single diff.index/diff.json file. Indexes that cover /apps or /libs, or have no includedPaths, still use the legacy format.
How changes roll out
Cloud Service uses rolling deployments: the old and new application versions run against the same repository for a while, so each version gets its own index set. Before the switch, the repository is reindexed with the new definitions. Large indexes therefore make deployments slower; plan index changes, do not slip them in with a hotfix.
What is not supported
- Index customisations must be type lucene, with async set to [async], [async,nrt] or [fulltext-async], and compatVersion 2 for index management.
- Custom analyzers are not supported; only standard analyzers are.
- Similarity search by feature vectors (useInSimilarity = true) is not supported.
- Indexing the contents of /oak:index is not supported.
A migration checklist for indexes
- Export every index definition from the 6.5 repository and compare it with the product's out-of-the-box version.
- Drop indexes nothing queries; keep a list of the queries each remaining index serves.
- Convert the rest to the naming convention and lucene type, using Adobe's Oak indexing tools where they help.
- Test the queries on a Rapid Development Environment or dev environment with production-like content volume, and watch for traversal warnings in the logs.
- Deploy index changes on their own and time the reindex before a production release depends on it.