# Aem Oak Repository Optimization

> AEM Oak Repository Optimization

- Skill: `gabrielmoreira/aem-oak-repository-optimization` (Agent Skill)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/aem-oak-repository-optimization`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/aem-oak-repository-optimization/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/gabrielmoreira/aem-oak-repository-optimization

---

# AEM Oak Repository Optimization

## Purpose
Optimize Apache Oak/JCR repository performance including index management, compaction, storage configuration, and query-level tuning for AEM's content repository layer.

## When to Use (Triggers)
- User mentions "Oak," "repository," "index," "compaction," or "JCR performance"
- References to Lucene indexes, property indexes, or traversal queries
- Questions about repository growth, segment store, or document store
- Requests involving Oak query optimization, explain plans, or index definitions
- Discussion of async indexing, reindexing, or index corruption

## Core Capabilities
- Design and implement custom Oak Lucene and property indexes
- Configure online compaction and revision garbage collection
- Optimize content node structure for repository performance
- Diagnose and fix traversal queries using explain plans
- Manage Oak index lifecycle (creation, updates, reindexing)

## Domain Knowledge Required
### Technical Foundation
- Apache Jackrabbit Oak architecture (NodeStore, BlobStore, index subsystem)
- Lucene index internals (analyzers, field types, aggregation, suggestions)
- B-tree property indexes vs. Lucene full-text indexes
- Storage backends: TarMK (segment), DocumentMK (MongoDB), RDB

### AEM-Specific Context
- OOTB Oak indexes in AEM (`damAssetLucene`, `cqPageLucene`, `ntBaseLucene`)
- AEM index definition structure under `/oak:index/`
- Async indexing lanes (async, fulltext-async, elastic-async)
- AEM Cloud Service index management via Cloud Manager
- Oak query engine query plan selection and cost estimation

## Implementation Approach
### Step 1: Query Analysis
Identify queries needing optimization.
- Enable Oak query logging (`org.apache.jackrabbit.oak.query` at DEBUG)
- Review `error.log` for traversal warnings (queries traversing >100K nodes)
- Use Query Performance tool in AEM Operations console
- Generate explain plans for slow queries

### Step 2: Index Design
Create indexes targeting identified query patterns.
- Define property index for equality/range queries on specific properties
- Create Lucene index for full-text search or complex multi-property queries
- Configure index rules with property definitions (ordered, analyzed, nodeScopeIndex)
- Set appropriate includedPaths/excludedPaths to limit index scope

### Step 3: Index Deployment
Deploy indexes safely with minimal disruption.
- Create index definition under `/oak:index/` with `reindex=true`
- For Cloud Service: deploy via CI/CD pipeline with index migration
- Monitor async indexing progress via JMX MBeans
- Validate index is used via explain plan after deployment

### Step 4: Repository Maintenance
Configure ongoing repository health operations.
- Schedule online compaction (revision GC) during low-traffic windows
- Configure checkpoint management and cleanup
- Monitor repository size growth and blob store usage
- Implement data store garbage collection for unused binaries

### Step 5: Content Structure Optimization
Optimize node structure for repository performance.
- Flatten deep hierarchies where possible (avoid >8 levels)
- Use Oak-ordered indexes for sorted queries instead of in-memory sorting
- Implement bucket patterns for nodes with >1000 children
- Move large binary properties to separate nodes/data store

## Quality Checklist
- [ ] No traversal queries in production (all queries use indexes)
- [ ] Custom indexes have appropriate scope (not over-broad)
- [ ] Online compaction running successfully on schedule
- [ ] Repository growth rate within expected bounds
- [ ] Async indexing lag under 60 seconds during normal operation
- [ ] Index definitions version-controlled and deployable
- [ ] No duplicate or redundant indexes consuming resources
- [ ] Query explain plans documented for critical queries

## Related Skills
- aem-query-optimization (query writing best practices)
- aem-performance-tuning-profiling (overall performance)
- aem-monitoring-alerting (repository health monitoring)

## Example Use Cases
1. **DAM Search Performance:** Create custom Lucene index for asset search covering metadata fields (dc:title, dam:scene, product SKU) with analyzers for partial matching and phonetic search.
2. **Content Migration Optimization:** Pre-create indexes for content migration queries, configure bulk indexing mode, and manage post-migration reindexing with minimal impact on running system.
3. **Repository Size Management:** Implement comprehensive repository maintenance including segment compaction scheduling, data store GC for orphaned binaries, and version purge reducing repository from 500GB to 200GB.

## Notes
- Never reindex `lucene` or `damAssetLucene` on production without scheduling downtime — it can take hours
- AEM Cloud Service manages Oak indexes differently — deploy index definitions via CI/CD, not manual reindex
- Property indexes are faster for simple equality queries; Lucene indexes are needed for full-text or complex conditions
- Oak traversal limit is 100,000 nodes by default — queries exceeding this will fail in Cloud Service