Core: Fix metrics mode lookup for escaped column names

[wombatu-kun]

Problem

Closes #11950

MetricsConfig keys per-column metrics modes by the original Iceberg column name, while MetricsUtil.metricsMode(schema, config, fieldId) resolves the field id to a name using whatever schema it is handed. When metrics are computed from a Parquet footer — the add_files / migrate / snapshot path via ParquetUtil.fileMetrics (TableMigrationUtil, the Delta→Iceberg snapshot action) — the schema is reconstructed from the file and carries sanitized names (AvroSchemaUtil.makeCompatibleName, e.g. $event_time → _x24event_time). The name lookup then misses and silently falls back to the default mode, which is none once a table exceeds write.metadata.metrics.max-inferred-column-defaults (default 100). Column bounds and value counts are silently dropped for escaped columns, degrading scan pruning. Explicit write.metadata.metrics.column.<escaped-name> overrides are ignored on the same path.

The write path was already correct because ParquetWriter.metrics() passes the writer's original Iceberg schema; only the footer-reconstructed path was affected.

Fix

Alongside the original-name column modes, MetricsConfig now derives a separate alias map keyed by the sanitized form of each column name (sanitizing each dotted path component). columnMode falls back to this alias map, so a mode resolves whether the caller passes the original name (write path) or the sanitized name (footer path). The alias map is intentionally kept separate from columnModes so validateReferencedColumns keeps validating only user-supplied original names against the table schema. The change is confined to the private constructor, so every factory path benefits and there is no public API change (revapi clean).

Relationship to #17022 (MetricsConfig id tracking)

main now includes #17022 ("Core: Add id tracking to MetricsConfig"), which added an id-based resolver columnMode(int id). It overlaps in intent but does not replace this fix:

• Core: Add id tracking to MetricsConfig #17022 did not convert the footer path: MetricsUtil.metricsMode still resolves the field id to a name and calls columnMode(String), so Column statistics are not collected when the column name is escaped #11950 is still reproducible on main.
• The sanitized-name fallback is kept rather than routing callers through columnMode(int id), which throws when idToName is null (configs built without a schema, e.g. fromProperties and forPositionDelete) and would require refactoring name-based callers such as SparkScanBuilder.

Tests

• TestMetricsModes: inferred-default and explicit-override cases for an escaped column, asserting columnMode resolves by both the original and the sanitized name.
• TestParquet: end-to-end regression that writes a Parquet file with an escaped column and verifies ParquetUtil.fileMetrics collects value counts and bounds for it.

---

AI Disclosure

• Model: Claude Opus 4.7
• Platform/Tool: Claude Code
• Human Oversight: fully reviewed
• Prompt Summary: Fix the per-column metrics mode lookup for escaped column names.

[github-actions]

This pull request has been marked as stale due to 30 days of inactivity. It will be closed in 1 week if no further activity occurs. If you think that’s incorrect or this pull request requires a review, please simply write any comment. If closed, you can revive the PR at any time and @mention a reviewer or discuss it on the dev@iceberg.apache.org list. Thank you for your contributions.

[wombatu-kun]

Not stale

[wombatu-kun]

@nastra you merged #16722 for me earlier - would you mind taking a look at this one? Small Core fix, closes #11950, CI is green. Thanks!