Better documentation; one more test

scottsand-db · Jan 31, 2025 · aac4caf · aac4caf
1 parent ac11bbf
commit aac4caf
Show file tree

Hide file tree

Showing 2 changed files with 27 additions and 1 deletion.
diff --git a/kernel/kernel-api/src/main/java/io/delta/kernel/internal/snapshot/LogSegment.java b/kernel/kernel-api/src/main/java/io/delta/kernel/internal/snapshot/LogSegment.java
@@ -58,6 +58,19 @@ public static LogSegment empty(Path logPath) {
    * Provides information around which files in the transaction log need to be read to create the
    * given version of the log.
    *
+   * <p>This constructor validates and guarantees that:
+   *
+   * <ul>
+   *   <li>All deltas are valid deltas files
+   *   <li>All checkpoints are valid checkpoint files
+   *   <li>All checkpoint files have the same version
+   *   <li>All deltas are contiguous and range from {@link #checkpointVersionOpt} to version
+   *   <li>If no deltas are present then {@link #checkpointVersionOpt} is equal to version
+   * </ul>
+   *
+   * <p>Notably, this constructor does not guarantee that this LogSegment is complete and fully
+   * describes a Snapshot version. You may use the {@link #isComplete()} method to check this.
+   *
    * @param logPath The path to the _delta_log directory
    * @param version The Snapshot version to generate
    * @param deltas The delta commit files (.json) to read
@@ -136,6 +149,8 @@ public LogSegment(
                       + "of this LogSegment");
             });
       }
+    } else {
+      checkArgument(deltas.isEmpty() && checkpoints.isEmpty(), "Version -1 should have no files");
     }
 
     ////////////////////////////////

diff --git a/kernel/kernel-api/src/test/scala/io/delta/kernel/internal/snapshot/LogSegmentSuite.scala b/kernel/kernel-api/src/test/scala/io/delta/kernel/internal/snapshot/LogSegmentSuite.scala
@@ -20,7 +20,6 @@ import java.util.Collections
 
 import scala.collection.JavaConverters._
 
-import io.delta.kernel.exceptions.InvalidTableException
 import io.delta.kernel.test.MockFileSystemClientUtils
 import io.delta.kernel.utils.FileStatus
 import org.scalatest.funsuite.AnyFunSuite
@@ -58,6 +57,18 @@ class LogSegmentSuite extends AnyFunSuite with MockFileSystemClientUtils {
     }
   }
 
+  test("constructor -- non-empty deltas or checkpoints with version -1 => throw") {
+    val exMsg1 = intercept[IllegalArgumentException] {
+      new LogSegment(logPath, -1, deltasFs11To12List, Collections.emptyList(), 1)
+    }.getMessage
+    assert(exMsg1 === "Version -1 should have no files")
+
+    val exMsg2 = intercept[IllegalArgumentException] {
+      new LogSegment(logPath, -1, Collections.emptyList(), checkpointFs10List, 1)
+    }.getMessage
+    assert(exMsg2 === "Version -1 should have no files")
+  }
+
   test("constructor -- all deltas must be actual delta files") {
     val exMsg = intercept[IllegalArgumentException] {
       new LogSegment(logPath, 12, badJsonsList, checkpointFs10List, 1)