docs(upsert): add rationale for duplicate check ordering

Abanoub Doss · Abanoub Doss · commit 336dcf8c4689 · 2026-05-19T15:00:09.000-05:00
diff --git a/pyiceberg/table/__init__.py b/pyiceberg/table/__init__.py
@@ -823,6 +823,7 @@ def upsert(
                     f"Extension type '{arr.type}' for column '{col}' is not currently supported as a join key in upsert."
                 )
 
+        # Validate uniqueness after type checks to avoid comparing/hashing unsupported types.
         if upsert_util.has_duplicate_rows(df, join_cols):
             raise ValueError("Duplicate rows found in source dataset based on the key columns. No upsert executed")
 

Original file line number	Diff line number	Diff line change
`@@ -823,6 +823,7 @@ def upsert(`
`823`	`823`	`f"Extension type '{arr.type}' for column '{col}' is not currently supported as a join key in upsert."`
`824`	`824`	`)`
`825`	`825`
	`826`	`+ # Validate uniqueness after type checks to avoid comparing/hashing unsupported types.`
`826`	`827`	`if upsert_util.has_duplicate_rows(df, join_cols):`
`827`	`828`	`raise ValueError("Duplicate rows found in source dataset based on the key columns. No upsert executed")`
`828`	`829`