uros-b commented on code in PR #17827:
URL: https://github.com/apache/iceberg/pull/17827#discussion_r3880315329
##########
docs/docs/spark-writes.md:
##########
@@ -218,8 +218,11 @@ For more complex row-level updates based on incoming data,
see the section on `M
## Writing to Branches
-The branch must exist before performing write. Operations do **not** create
the branch if it does not exist.
-A branch can be created using [Spark
DDL](spark-ddl.md#branching-and-tagging-ddl).
+A branch can be created during a write if it does not already exist.
+
+A branch can also be created using [Spark
DDL](spark-ddl.md#branching-and-tagging-ddl).
+
+When writing to a branch, the branch specified in the table identifier and the
`branch` write option must match if both are specified. An explicit branch
takes precedence over the session WAP branch configured with
`spark.wap.branch`. If no explicit branch is specified and WAP is enabled, the
session WAP branch is used.
Review Comment:
The new text states "An explicit branch takes precedence over the session
WAP branch configured with spark.wap.branch." This accurately reflects the v4.1
SparkTableUtil.determineWriteBranch() logic (the option/identifier branch is
returned first, WAP branch is only checked when branch == null). However, in
v3.5 and v4.0 the same scenario goes through SparkWriteConf.branch(), which
throws a ValidationException("Cannot write to both branch and WAP branch, ...")
rather than silently preferring the explicit branch. The docs page covers all
Spark versions without a version qualifier, so stating "takes precedence" is
misleading to 3.5/4.0 users. The fix is to scope the sentence to "Since Spark
4.1" or to split the section with version-specific behavior boxes.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
