apache-hudi-lakehouse

name: apache-hudi-lakehouse description: Guides agents through Apache Hudi lakehouse design. Use when managing incremental upserts, record-level mutations, timeline behavior, compaction, and Hudi-based lakehouse tables.

Apache Hudi Lakehouse

Overview

Use this skill when Apache Hudi is the primary table layer for incremental lakehouse workloads. It helps agents reason about mutation-heavy patterns, table type selection, compaction behavior, timeline safety, and consumer expectations across read-optimized and real-time query paths.

When to Use

• choosing or operating Apache Hudi for lakehouse tables
• building record-level upsert or delete pipelines
• managing compaction, clustering, and incremental consumption
• supporting lakehouse tables with heavy mutations (CDC sinks, slowly changing dimensions)
• planning multi-engine access (Spark, Presto, Trino, Athena, Hive)

Do not use this when the workload is append-only with no mutation requirements and simpler formats like Parquet or Iceberg would suffice.

Workflow

1. Define mutation patterns and read access expectations. Include:

   • primary record key and partition path
   • expected operations: inserts, upserts, deletes, or bulk replaces
   • read latency expectations: are readers okay with merge-on-read or do they need read-optimized snapshots?
   • query engines that must access the table
   • expected write throughput and record mutation rate

2. Choose the right table type and indexing strategy.

   • Copy-on-Write (COW): best for read-heavy workloads, produces columnar snapshots on write
   • Merge-on-Read (MOR): best for write-heavy workloads, defers merge to read time or compaction
   • choose record index type: BLOOM, GLOBAL_BLOOM, SIMPLE, BUCKET, or RECORD_INDEX
   • index choice affects upsert performance and scaling behavior
   • document why the table type was chosen — revisiting later is expensive

3. Plan compaction and clustering explicitly.

   • for MOR tables: compaction converts log files to columnar — it is not optional
   • define compaction strategy: synchronous (inline) or asynchronous (scheduled)
   • set compaction triggers: by number of commits, time, or log file size
   • clustering reorganizes data layout for query performance — plan separately from compaction
   • budget compute for compaction and clustering in cost planning

4. Design incremental consumption and downstream contracts.

   • Hudi supports incremental queries by commit timeline
   • define the consumer contract: which commit instant do consumers start from?
   • plan for consumer resets and bootstrap reads
   • document how schema changes affect incremental consumers
   • test that consumers handle compaction and rollback instants correctly

5. Handle schema evolution and timeline safety.

   • Hudi supports schema evolution but not all changes are safe across readers
   • column adds are generally safe; renames and type changes require care
   • define compatibility expectations per reader engine
   • rollback instants can confuse consumers — document rollback behavior
   • archive policy affects timeline visibility for late consumers

6. Plan operations, monitoring, and recovery.

   • monitor timeline growth, pending compactions, and inflight commits
   • alert on compaction backlog and write failures
   • plan for rollback: Hudi supports instant-level rollback, but consumers must handle gaps
   • define retention and archival for the Hudi timeline
   • document backup and restore procedures for critical tables

Common Rationalizations

Red Flags

• record key chosen without understanding uniqueness guarantees
• MOR table with no compaction schedule or monitoring
• incremental consumers have no documented starting instant or reset procedure
• schema changes deployed without testing across all reader engines
• no monitoring of timeline growth, pending compactions, or inflight commits
• clustering is never run despite increasing query scan ranges
• rollback behavior is undocumented and consumers assume a linear timeline
• index type is default without analysis of key cardinality and write patterns

Verification

• Record key, partition path, and mutation semantics are explicitly documented
• Table type choice (COW vs MOR) is justified with read/write trade-off analysis
• Compaction is scheduled, monitored, and budgeted for compute cost
• Incremental consumer contracts define starting instants and reset behavior
• Schema evolution paths are tested across all target query engines
• Timeline monitoring covers pending compactions, inflight commits, and archival
• Rollback behavior is documented and consumers handle timeline gaps safely