⚠️ Breaking changes: Compound hints precedence and replacement behavior#

PR: #3431

Starting with v1.21.2, compound hints (primary_key, merge_key, cluster, partition) now follow explicit precedence and replacement rules. This affects how hints are resolved.

What changed:

1. Direct merge_key and primary_key hints now take precedence over column-level hints

   • When you specify primary_key="col_1" at the resource level and columns={"col_2": {"primary_key": True}}, only col_1 will be treated as the primary key
   • This also applies when using apply_hints

2. Redefining compound hints replaces previous configuration

   • If you redefine compound hints on a resource that was already extracted, the new properties completely replace the previous configuration
   • Example: If you first set partition on col_1, then redefine the resource with partition on col_2, only col_2 will remain partitioned

3. Direct merge_key and primary_key hints via apply_hints are authoritative

   • When calling apply_hints with direct key hints (primary_key="col_1"), they replace the existing key configuration instead of merging

Notes

• Previously, all compound hints were merged additively

More details → Compound Hints