amogh-jahagirdar commented on code in PR #17642:
URL: https://github.com/apache/iceberg/pull/17642#discussion_r4592959445


##########
open-api/rest-catalog-open-api.py:
##########
@@ -1939,11 +2006,35 @@ class ReadRestrictions(BaseModel):
 
 class LoadTableResult(BaseModel):
     """
-    Result used when a table is successfully loaded.
+    Result used when a table is successfully loaded, for tables at any format 
version.
+
+
+    The table metadata JSON is returned in the `metadata` field.
+    The location of the table metadata file is returned in the 
`metadata-location` field when the table has one, and the table's base location 
in the `table-location` field.
+
+
+    ## Metadata location
+
 
+    The `metadata-location` field is optional.
+    It is absent when the metadata is staged but not committed, as in a create 
transaction, and when the table has no client-visible metadata location, as for 
a catalog-managed table where the catalog is the source of truth for table 
state and no metadata pointer need exist.
 
-    The table metadata JSON is returned in the `metadata` field. The 
corresponding file location of table metadata should be returned in the 
`metadata-location` field, unless the metadata is not yet committed. For 
example, a create transaction may return metadata that is staged but not 
committed.
-    Clients can check whether metadata has changed by comparing metadata 
locations after the table has been created.
+
+    Clients must not require this field to be present, and must not use it to 
bypass the catalog for reads or commits.

Review Comment:
   I think we need to be a bit more careful with wording here "    Clients must 
not require this field to be present, and must not use it to bypass the catalog 
for reads or commits.". It's being made optional in this PR, which is fine but 
the whole requirement here may falsely cause folks to think their client 
implementation is incompliant with the spec when it's not. Also it's catalog 
responsibility anyways to vend scoped credentials so the whole "bypas the 
catalog for reads or commits" also feels unneccessary to say.



-- 
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]

Reply via email to