Ensure Oak Index
Available since version 2.1.0
The Oak repository used by AEM 6, allows from fine tuning of search performance via the definition of Oak Index definitions. The index definition nodes, usually stored under
/oak:index, define the index and also store the index data (in a node structure invisible to the AEM tooling).
Ideally the Oak Index definitions used by an application could be stored with in the application’s content package, however, it is possible (and even likely) that upon deployment the content packages index definition may wipe out the actual index data (again, invisible via AEM tooling) when updating the node, necessitating a reindex, which depending on the repository size and index configuration can be costly (and generally unnecessary).
Ensure Oak Index is tooling that allows Oak Index Definitions (referred to in this document as Ensure Definitions) to be defined in a content package, and then safely translated to real Oak Indexes.
How to Use
As of v2.2.0, the management of Oak Indexes has been moved to an async Sling Job to ensure the work does not block bundle activation.
Define the Ensure Definitions
In your AEM Content project, create a
sling:Folder under your application’s
Under this folder, create Ensure Definitions for each Oak Index you want to ensure is created/updated. Ensure Definitions are identical to
oak:QueryIndexDefinition nodes, except they MUST be of type
See details on defining Ensure Definitions below.
Create the Ensure Oak Index OSGi Configuration
Once all the Ensure Definitions are defined, create a
sling:OsgiConfig factory config instructing EnsureOakIndex where to find the Ensure Definitions and then where to ensure they are created/updated/deleted.
Provide Additional Ignore Properties (Since v2.6.4/3.2.4)
If additional properties on the root ensure definition/oak index node need to be ignored, you can specify them via OSGi configuration. These additional properties will be joined w the mandatory ignore properties list and will NOT be considered when 1) evaluating if there is a change between the ensure definition and oak index 2) when removing properties from the oak index during and update operation.
Now, deploy the package containing the Ensure Definitions and the OSGi Configuration. Set logging to INFO on
com.adobe.acs.commons.oak.impl to see what Oak Indexes are managed.
- Place Ensure Definitions in a
sling:Foldercan be named anything but convention named it
- Ensure Definition nodes must be
- Ensure Definition nodes can be multi-levels deep, supporting Lucene Property Index definitions.
- Define the Ensure Definition exactly as you would the Oak Index you wish to create/update (with the exception of the
jcr:primaryTypeas noted above)
Ensure Oak Index supports special properties on the Ensure Definition nodes.
An Ensure Definition can be ignored completely by setting
Disabled (as of v.2.2.0)
An Ensure Definition can mark an Oak Index as disabled (but NOT deleted) by setting
To delete an existing Oak Index, create an Ensure Definition with the same node name as the Oak Index to delete, and add the property
@delete=true. If no index can be found to delete, this will note it in the log and continue.
On create or update, the Oak Index can be marked to be immediately re-indexed by setting @forceReindex=true`.
Recreate on Update
Property Name: @recreateOnUpdate`
The default behavior for updating Oak Index properties is to perform an in place update to avoid deleting the actual indexed data (invisible to AEM). To force the Oak Index to be be fully deleted and then recreated on an update, set
Note this should be used sparingly. It is almost always better to use the forceReindex option
Example Ensure Definition
On AEM 6.2 or above, this service uses a Service User for repository access. This user is configured with the expected permissions required, but additional permissions may be required if your repository design deviates from the expected structure.