docs: doc the requirement for ParquetHandler to do type widening - #3313
docs: doc the requirement for ParquetHandler to do type widening#3313dengsh12 wants to merge 2 commits into
AI review completed
Draft - human review required.
No blocking issues. This is a docs-only change to the ParquetHandler coercion contract. The protocol reviewer verified the type-widening examples (INTEGER -> LONG, FLOAT -> DOUBLE, DATE -> TIMESTAMP_NTZ) against PROTOCOL.md, and the docs reviewer confirmed each example and the INT32 -> DATE / INT64 -> TIMESTAMP/TIMESTAMP_NTZ checkpoint conversions map to real branches in check_cast_compat in kernel/src/engine/ensure_data_types.rs. The DATE -> TIMESTAMP_NTZ example correctly excludes the timezone-bearing TIMESTAMP variant, and the microsecond normalization text matches the protocol.
Non-blocking notes
Nit1
kernel/src/lib.rs:797 The examples INTEGER -> LONG, FLOAT -> DOUBLE, and DATE -> TIMESTAMP_NTZ sit directly under the "[Delta protocol type widening rules]" link, while the next paragraph lists INT32 -> DATE and INT64 -> TIMESTAMP/TIMESTAMP_NTZ as extra Kernel requirements. A reader could infer the coercions are gated on the type-widening table feature rather than being reader-side coercions needed to materialize the requested physical_schema. Raised by: maintainer-codex-reviewer. Suggested fix: add a short clause noting these coercions are required whenever physical_schema asks for a compatible type and are not conditional on the table having the type-widening feature enabled.
Summary
The documentation accurately reflects both the Delta protocol and the default engine's coercion behavior, and the change is safe to merge. Coverage note: the maintainer-codex, delta-protocol, and docs reviewers completed and reached quorum; the maintainer-claude reviewer did not return within the review window, so its pass is not reflected here.