Org Skills

Custom Oak indexes on AEM as a Cloud Service — naming and packaging

Supporting material for aem-backend-development. Agents load it on demand; it ships inside the skill folder.

RawSource

Verified: 2026-09 against https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/operations/indexing

This is the single source for the index rules in the AEM skills. Link here instead of restating them.

The naming rule

Kind of index Name pattern Example
Fully custom index <prefix>.<indexName>-<productVersion>-custom-<customVersion> /oak:index/acme.product-1-custom-2
Customisation of a product (out-of-the-box) index <indexName>-<productVersion>-custom-<customVersion> /oak:index/damAssetLucene-8-custom-1
  • <prefix> is 2–5 characters identifying the project, followed by a dot (acme.). It is mandatory for fully custom indexes; a name without it (acme-product-custom-1, mysite-articles-custom-1) is rejected by the pipeline.
  • <productVersion> is 1 for a fully custom index. For a customised product index it is the version of the product index you copied (damAssetLucene-8 → damAssetLucene-8-custom-1); when Adobe ships damAssetLucene-9, re-apply your change as damAssetLucene-9-custom-1.
  • <customVersion> starts at 1. A deployed definition is immutable: to change it, copy it to the next number (-custom-2 → -custom-3) and deploy both the new node and the updated filter.xml. During the rolling deployment old and new versions run side by side; the old one is removed afterwards.
  • Quick test for a name: ^([a-z0-9]{2,5}\.)?[A-Za-z0-9]+-\d+-custom-\d+$.
Wrong Why Right
mysite-articles-custom-1 No prefix. and no product version acme.articles-1-custom-1
acme.articles-custom-1 Product version missing acme.articles-1-custom-1
damAssetLucene-custom-1 Product version of the copied index missing damAssetLucene-8-custom-1
acmecorp.articles-1-custom-1 Prefix longer than 5 characters acme.articles-1-custom-1
Editing acme.articles-1-custom-1 in place Definitions are immutable once deployed Add acme.articles-1-custom-2

Lucene only

Index management on Cloud Service supports only type="lucene". A standalone type="property" index cannot be deployed; express property lookups as propertyIndex="{Boolean}true" rules inside a lucene definition. Custom analyzers are not supported — only the analyzers shipped with the product. When customising a product index keep its tika node.

On AEM 6.5 naming is free and property indexes are allowed, but adopting the Cloud naming now makes a later migration (Index Converter) trivial.

Where it lives in the project

ui.apps/src/main/content/jcr_root/_oak_index/acme.article-1-custom-1/.content.xml

ui.apps/src/main/content/META-INF/vault/filter.xml — one entry per index version:

<filter root="/oak:index/acme.article-1-custom-1"/>

ui.apps/pom.xml — filevault-package-maven-plugin (1.3.2 or later) configuration:

<allowIndexDefinitions>true</allowIndexDefinitions>
<noIntermediateSaves>true</noIntermediateSaves>

Top-level pom.xml — repository structure validation:

<immutableRootNodeNames>apps,libs,oak:index</immutableRootNodeNames>

A complete definition

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    xmlns:oak="http://jackrabbit.apache.org/oak/ns/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0"
    jcr:primaryType="oak:QueryIndexDefinition"
    type="lucene"
    async="[async,nrt]"
    compatVersion="{Long}2"
    evaluatePathRestrictions="{Boolean}true"
    includedPaths="[/content/acme]"
    queryPaths="[/content/acme]"
    tags="[acmeArticle]">
    <indexRules jcr:primaryType="nt:unstructured">
        <cq:Page jcr:primaryType="nt:unstructured">
            <properties jcr:primaryType="nt:unstructured">
                <template jcr:primaryType="nt:unstructured"
                    name="jcr:content/cq:template" propertyIndex="{Boolean}true"/>
                <publishDate jcr:primaryType="nt:unstructured"
                    name="jcr:content/publishDate" propertyIndex="{Boolean}true" ordered="{Boolean}true"/>
            </properties>
        </cq:Page>
    </indexRules>
</jcr:root>
  • Required: jcr:primaryType="oak:QueryIndexDefinition", type="lucene", compatVersion="{Long}2", async ([async], [async,nrt] or [fulltext-async]), includedPaths, queryPaths, indexRules.
  • tags plus option(index tag acmeArticle) in the query stops unrelated queries from selecting this index.
  • Index only the properties you filter or sort on; ordered="{Boolean}true" for ORDER BY properties.

Matching query:

SELECT * FROM [cq:Page] AS p
WHERE ISDESCENDANTNODE(p, '/content/acme')
  AND p.[jcr:content/cq:template] = '/conf/acme/settings/wcm/templates/article'
ORDER BY p.[jcr:content/publishDate] DESC
OPTION (INDEX TAG acmeArticle)

Deployment behaviour

  • Indexes deploy with the full-stack pipeline. The new version is built before traffic switches (blue-green), so large repositories lengthen the deployment: ship index changes ahead of the code that needs them.
  • Removing a customised product index: deploy a new version equal to the product baseline. Removing a fully custom index: deploy a new version whose includedPaths/queryPaths point at a path that never matches (Adobe's docs use /dummy), then drop it in a later release.
  • RDE and the local SDK do not have the production Tika configuration; verify full-text behaviour on dev/stage.
  • Adobe also documents a "simplified index management" JSON diff format for customising product indexes; it is unavailable for indexes that include /apps or /libs. Use the explicit versioned form above unless the project already adopted the diff format.