Evolve meaning as carefully as bytes

Parquet separates a compact set of physical types from logical annotations that specify interpretation. An INT64 carrier alone does not tell an application whether a number is an epoch count in microseconds or a scaled decimal. Decimal precision and scale, timestamp units and instant/local semantics, signedness, and string ordering all matter. Changing only a label can silently change query values or pruning order without changing any payload bits. A migration should explicitly transform values where needed and test boundaries, rather than treating metadata edits as a generally safe conversion.

Nested schema changes add further questions about presence and identity. Adding an optional field can permit old records to be represented with missing values under an engine's reconciliation policy, but the file format alone does not assign every application's default or guarantee every reader combines mixed schemas automatically. Renames need a table or engine's field-identity rules; matching names by guesswork can conflate unrelated columns. Validate null versus absent/default semantics and preserve list structure. Physical type widening must also respect range, precision, and supported conversion behavior in each consumer.

List the physical and logical types, encodings, codecs, data-page variants, statistics semantics, and optional indexes the writer can emit. Then test each actual consumer version against that set. A reader may support a codec but not a new logical type, or correctly read values while ignoring an optional pruning index. Ignoring an optional performance feature can be safe; inventing the meaning of an unsupported required feature is not. Parquet's documented fallback for an unrecognized annotation does not guarantee an application that needs its semantics can safely accept raw physical values.

File-format version, library release, table metadata version, and Arrow in-memory or IPC feature support are different layers. Do not infer that upgrading one enables all others, or that an engine advertising Parquet support implements every optional feature. Consult current implementation documentation and retain representative compatibility fixtures. Include mixed dictionary/plain pages, null-heavy nested records, maximum integer values, decimal scales, timestamp units, and missing statistics. Check decoded values and query answers rather than only whether an open call succeeds; incorrect statistics interpretation can corrupt results by pruning valid data.

Introduce compatible readers before enabling writer features that older required consumers cannot handle. Write a small canary generation, validate it with the full reader matrix, compare query answers with established data, and publish through the table's checked commit protocol. Keep a rollback strategy that accounts for newly created files: reverting a writer binary does not rewrite files it already emitted. Long-lived snapshots and backups can retain old schemas and codecs for years, so the supported read history and restoration process deserve explicit fixtures and ownership.

Use the cache instrument only to illustrate a bounded working-set effect during compatibility scans. Reset, set both C=8 and s=2, predict eight hits among the first sixteen requests, then Play or Step. Reset and re-enter both C=4 and s=2 for a separate run with no hits. This deterministic stream caps at 4,096 requests and has no files or type system; a hit is not evidence that a reader understands a logical type. Its limited lesson is to keep cache-warm timing separate from semantic pass/fail evidence when rerunning a compatibility fixture suite.