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

> **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:

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

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

```xml
<allowIndexDefinitions>true</allowIndexDefinitions>
<noIntermediateSaves>true</noIntermediateSaves>
```

Top-level `pom.xml` — repository structure validation:

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

## A complete definition

```xml
<?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:

```sql
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.
