(iceberg) branch main updated: OpenAPI, Core: Disambiguate the intent of REFS snapshot mode (#16252)

[kevinjqliu]

This is an automated email from the ASF dual-hosted git repository.

kevinjqliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg.git


The following commit(s) were added to refs/heads/main by this push:
     new 299f7be398 OpenAPI, Core: Disambiguate the intent of REFS snapshot 
mode (#16252)
299f7be398 is described below

commit 299f7be3987c87c8812234f85131d594b5553db6
Author: gaborkaszab <gaborkas...@gmail.com>
AuthorDate: Fri May 8 19:29:29 2026 +0200

    OpenAPI, Core: Disambiguate the intent of REFS snapshot mode (#16252)
    
    * Spec, Core: Disambiguate the intent of REFS snapshot mode
    
    Spell out that it has an effect on the 'snapshots' and not the
    'snapshot-log' part of the response. Some implementations already
    got it wrong.
    
    * Update core/src/test/java/org/apache/iceberg/rest/TestRESTCatalog.java
    
    Co-authored-by: Eduard Tudenhoefner <etudenhoef...@gmail.com>
    
    ---------
    
    Co-authored-by: Eduard Tudenhoefner <etudenhoef...@gmail.com>
---
 .../org/apache/iceberg/rest/TestRESTCatalog.java   | 25 ++++++++++++++++++++++
 open-api/rest-catalog-open-api.yaml                |  6 +++---
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/core/src/test/java/org/apache/iceberg/rest/TestRESTCatalog.java 
b/core/src/test/java/org/apache/iceberg/rest/TestRESTCatalog.java
index e4fa156059..017f400f86 100644
--- a/core/src/test/java/org/apache/iceberg/rest/TestRESTCatalog.java
+++ b/core/src/test/java/org/apache/iceberg/rest/TestRESTCatalog.java
@@ -62,6 +62,7 @@ import org.apache.iceberg.CatalogProperties;
 import org.apache.iceberg.DataFile;
 import org.apache.iceberg.DataFiles;
 import org.apache.iceberg.HasTableOperations;
+import org.apache.iceberg.HistoryEntry;
 import org.apache.iceberg.MetadataUpdate;
 import org.apache.iceberg.PartitionSpec;
 import org.apache.iceberg.Schema;
@@ -1086,6 +1087,14 @@ public class TestRESTCatalog extends 
CatalogTests<RESTCatalog> {
         .asInstanceOf(InstanceOfAssertFactories.list(Snapshot.class))
         .hasSize(1);
 
+    // snapshot log is complete regardless REFS mode
+    assertThat(((BaseTable) refsTable).operations().current())
+        .extracting("snapshotLog")
+        .asInstanceOf(InstanceOfAssertFactories.list(HistoryEntry.class))
+        .hasSize(2)
+        .containsExactlyInAnyOrderElementsOf(
+            ((BaseTable) table).operations().current().snapshotLog());
+
     assertThat(refsTable.currentSnapshot()).isEqualTo(table.currentSnapshot());
 
     // verify that the table was loaded with the refs argument
@@ -1180,6 +1189,14 @@ public class TestRESTCatalog extends 
CatalogTests<RESTCatalog> {
         .asInstanceOf(InstanceOfAssertFactories.list(Snapshot.class))
         .hasSize(2);
 
+    // snapshot log is complete regardless REFS mode
+    assertThat(((BaseTable) refsTable).operations().current())
+        .extracting("snapshotLog")
+        .asInstanceOf(InstanceOfAssertFactories.list(HistoryEntry.class))
+        .hasSize(1) // main branch has a single snapshot
+        .containsExactlyInAnyOrderElementsOf(
+            ((BaseTable) table).operations().current().snapshotLog());
+
     assertThat(refsTable.currentSnapshot()).isEqualTo(table.currentSnapshot());
 
     // verify that the table was loaded with the refs argument
@@ -1265,6 +1282,14 @@ public class TestRESTCatalog extends 
CatalogTests<RESTCatalog> {
         .asInstanceOf(InstanceOfAssertFactories.list(Snapshot.class))
         .hasSize(1);
 
+    // snapshot log is complete regardless REFS mode
+    assertThat(((BaseTable) refsTable).operations().current())
+        .extracting("snapshotLog")
+        .asInstanceOf(InstanceOfAssertFactories.list(HistoryEntry.class))
+        .hasSize(numSnapshots)
+        .containsExactlyInAnyOrderElementsOf(
+            ((BaseTable) table).operations().current().snapshotLog());
+
     assertThat(refsTable.currentSnapshot()).isEqualTo(table.currentSnapshot());
     assertThat(refsTable.snapshots()).hasSize(numSnapshots);
     assertThat(refsTable.history()).hasSize(numSnapshots);
diff --git a/open-api/rest-catalog-open-api.yaml 
b/open-api/rest-catalog-open-api.yaml
index 2435cd43f0..06d13ec133 100644
--- a/open-api/rest-catalog-open-api.yaml
+++ b/open-api/rest-catalog-open-api.yaml
@@ -983,9 +983,9 @@ paths:
         - in: query
           name: snapshots
           description:
-            The snapshots to return in the body of the metadata. Setting the 
value to `all` would
-            return the full set of snapshots currently valid for the table. 
Setting the value to
-            `refs` would load all snapshots referenced by branches or tags.
+            The snapshots to return in the body of the metadata via the 
`snapshots` field. Setting
+            the value to `all` would return the full set of snapshots 
currently valid for the table.
+            Setting the value to `refs` would load all snapshots referenced by 
branches or tags.
 
             Default if no param is provided is `all`.
           required: false