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>is1for 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 shipsdamAssetLucene-9, re-apply your change asdamAssetLucene-9-custom-1.<customVersion>starts at1. 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 updatedfilter.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. tagsplusoption(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"forORDER BYproperties.
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/queryPathspoint 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
/appsor/libs. Use the explicit versioned form above unless the project already adopted the diff format.