feat(transaction): support transform-based sort orders

[viirya]

What changes are included in this PR?

ReplaceSortOrderAction only supported sorting by a column's raw value (an implicit identity transform) — asc/desc hardcoded Transform::Identity and only accepted a column name. There was no way to declare a sort order using a transform (bucket[N], year, truncate[W], etc.), which Java's SortOrderBuilder.asc/desc(Term, NullOrder) supports.

Adds asc_with_transform / desc_with_transform:

tx.replace_sort_order()
    .asc_with_transform("event_time", Transform::Year, NullOrder::First)
    .desc_with_transform("id", Transform::Bucket(16), NullOrder::Last);

asc/desc are unchanged (same signature, same behavior) — they now delegate to the new methods with Transform::Identity, so no existing caller is affected.

Whether a transform is valid for the source column's type is checked at commit time (via the existing SortOrder::builder().build(schema) → check_compatibility), matching the timing of Java's SortOrder.Builder.build() — an incompatible transform is only rejected once the table schema is available, not at the asc_with_transform call site.

Scope

This only extends the metadata-declaration API — which sort order (including which transform) can be recorded on a table. Whether the write path actually sorts a RecordBatch to match a table's declared sort order is a separate, pre-existing gap: no writer in crates/iceberg/src/writer/ reads SortOrder or sorts data today, for any sort order, including the pre-existing identity case. This PR does not touch that; it only makes a wider set of sort orders declarable.

Are these changes tested?

• test_replace_sort_order_with_transform — the builder records the requested transform per field.
• test_replace_sort_order_with_transform_commits — end-to-end commit; the resulting TableUpdate::AddSortOrder's SortField carries the requested transform.
• test_replace_sort_order_rejects_incompatible_transform — Transform::Year on a long column is rejected at commit time with ErrorKind::Unexpected, exercising the existing check_compatibility path.
• Existing test_replace_sort_order (plain asc/desc) passes unchanged.

Full iceberg lib suite passes; clippy and rustfmt clean.

[NikitaMatskevich]

Can we also add an integration test that would write a metadata.json with updated sort order, and then another operation would read this json and correctly parse the transform?

[viirya]

Good idea — added in eee40b8: test_sort_order_transform_survives_metadata_json_round_trip.

It commits a transform-based sort order (bucket[16] asc + truncate[4] desc) through the in-crate memory catalog, which serializes the updated table metadata to an actual metadata.json file (TableMetadata::write_to on FileIO), then reloads the table via catalog.load_table — which reads and parses that file back (TableMetadata::read_from) — and asserts both transforms and directions survive. So the transform string ("bucket[16]" etc.) is exercised through the real serialize-file-parse path, not just the in-memory TableUpdate.

[huan233usc]

LGTM

[viirya]

@CTTY Could you take a look at this? Thanks!

[mbutrovich]

Thanks @viirya! One design question: should sort-order declaration converge on Term rather than growing _with_transform variants

Adding asc_with_transform/desc_with_transform alongside asc/desc doubles the builder surface, and it mirrors Java's overload (asc(Term, NullOrder)) rather than Java's type (Term). We already have Term in crates/iceberg/src/expr/term.rs, but it's currently pub type Term = Reference (a bare column ref, no transform). #2665 is expanding Term into a transform-carrying enum. Once that lands, asc(term, null_order) could subsume both the identity and transform cases with a single method, which is both closer to Java's API and more idiomatic than a parallel method pair.

I don't think this should block the PR: building on a Term enum that doesn't exist yet would be premature, and _with_transform is the minimal non-breaking step today. Mainly flagging it so we agree on direction and don't ship an API we'll want to deprecate right after #2665 merges. Could you add a short comment noting the intended convergence, or say if you see it differently?

Two minor nits:

1. The new tests scatter use statements inside each test fn (use std::sync::Arc;, use crate::TableUpdate;, etc.), whereas the rest of the file imports at the mod tests top. Worth hoisting for consistency.
2. test_replace_sort_order_with_transform_commits is largely subsumed by test_sort_order_transform_survives_metadata_json_round_trip (the round-trip also asserts the committed transform). Not worth removing, just noting the overlap.

[viirya]

Agreed on the direction, @mbutrovich — converging on a transform-carrying Term is the better end state. I checked #2665 and it is indeed turning Term (today just pub type Term = Reference) into an enum, so once that lands, a single asc(term, null_order) mirrors Java's actual type rather than its overload, and the _with_transform pair becomes redundant.

Done in afe2c27:

• Added the convergence note to both asc_with_transform/desc_with_transform doc comments — they're documented as the minimal non-breaking step today, expected to be deprecated in favor of Term-based asc/desc after feat: expand Term to enum and add basic support for transform term predicate #2665.
• Hoisted the scattered in-test use statements to the mod tests top (nit 1).

On nit 2 — agreed there's overlap; keeping both since the unit test pinpoints the ActionCommit output in isolation while the round-trip covers the serde path, and the unit test is where a failure would localize faster. Cheap to keep.