Stop Messing with Index Definitions: Index Optimizer and Simplified Index Management in AEM
Customizing indexes in AEM as a Cloud Service has traditionally been complicated and error-prone: copying entire OOTB index definitions, manually bumping version numbers, keeping copies in sync with every product upgrade, and hoping nothing breaks during reindex. This session introduces two innovations that eliminate most of that toil.
Simplified Index Management lets you express your customizations and fully custom indexes in a single “diff.json” file containing only the delta. At deploy time, the platform merges your diff with the latest OOTB index definition and creates a correctly versioned index when needed. This works with both Cloud Manager pipelines and RDE/local quickstart, and is backward-compatible for incremental adoption.
The Index Optimizer closes the loop by analyzing the queries running in your environment and enhancing index definitions. Together, the two features let developers focus on what data needs indexing, not the mechanics of defining, versioning, and deploying indexes. The session includes a live demo using the open-source Oak Indexing Tools, covering migration, the merge algorithm, limitations, and the roadmap ahead.
wolf
Will the functionality make its way to AMS? Dealing with Index definitions handling is the primary obstacle when it comes to addressing BPA issues for any AMS->AEMaaCS migration, as „AEMaaCS style” is outright not usable on AMS for any instance of non-trivial size.
wolf
It also requires Cloud Manager updates, not just Oak ones
Konrad Windszus
Do you plan to still deprecate classic index definitions soon given the limitations of diff indices: 1. No multitenancy support (https://github.com/oak-indexing/oakTools/issues/7) 2. No support for indexing apps/libs
Paul Chibulcuteanu
We will continue to support existing index definitions that were created using the legacy approach. We are addressing the limitations of simplified index management as follows: We will support modularized index definitions (https://github.com/oak-indexing/oakTools/issues/7) Indexes on apps and libs: this will take more time, but we will eventually also support those
angela
How are you going to enforce the deprecation that customers will benefit from the new way? Eventually t her should be no old customisations left, no?
Paul Chibulcuteanu
We will continue to support existing index definitions that were created using the legacy approach. However, we will notify customers to migrate, and help them migrate to simplified index management over time, such that they are not stuck once they need to change their customizations and custom indexes. We know this will take time.
TamalB
what about dummy index to get rid of any exisiting index which we do not want anymore. The diff will support that change?
Robert
We read that the new way of definition should be used for fully custom indexes as well. But what is the diff to a non existing index. Again the whole definition? And how about later lifecycle, do we maintain only diffs to the previous version later or always the full version?
Edgar
How is it managed the remove of custom indexes? With previous implementation, actually it was necessary to create a new custom index where it is indicated it is removed to be ignored by AEM.
Paul Chibulcuteanu
If an index is removed from the diff.json, then a new "dummy" index is created (one that doesn't index anything and is not used for queries). After some time, this dummy index is purged. The purging mechanism will also be changed soon to remove, after some time, these dummy indexes, as well as old disabled index definitions. This is work in progress.
Badr
What about using Index Tag Option in the query? How is it defined in the diff json? If yes, does it affect the original index?
Paul Chibulcuteanu
Yes, you can extend the existing indexes by adding tags. Adding is allowed, modifying/deleting is not.
Simon
Will there be some verification built into the Maven build process (aem analyzer plugin)?
Paul Chibulcuteanu
Yes, this is something that we plan to have in the future to help with the validation. For now you can use the available online tools to validate
RolandGruber
Why are there different jcr:primaryTypes for local vs. cloud for the diff.index node?
Konrad Windszus
This prevents reusing the same package for both targets!
Masoud Rozati
Will diffIndexAnalyzer and -Verifier be integrated into AEM Analyzer?
Himani chauhan
How can this be part of the migration from 6.x -> AEMaaCS? Can this be part of the existing skills set?
Paul Chibulcuteanu
This is only available for AEMaaCS now (only released Summer 2026) but this is something that we will strongly consider.
wolf
How does the optimiser avoid the problem of „more specific index that is more specialised makes OTHER queries slower” when it looks at specific slow queries only?
Paul Chibulcuteanu
What we have seen so far, mostly, is missing properties in the index definitions, and queries that either read too much, or are otherwise not optimal. Adding the missing properties to the index definitions won't make other queries slower, and changing the query will not affect other queries. But I'm not quite sure if I understand the questions, could you give an example?
Yegor Kozlov
Can I control the auto-improve behavior, e.g. throw exception vs appending option(limit 1000) ?
Paul Chibulcuteanu
The index optimizer and query optimizer are not used a lot currently. So far, each case is a little bit different, and we don't currently see clear patterns that would allow us to define a clear set of rules or customizations.
Michael
Does the new JSON syntax work for new indexes as well? Or does it only apply when extending?
Paul Chibulcuteanu
Yes, you can add new indexes - in the new JSON format.