Core: Add UUIDv7 generator #14700

huaxingao · 2025-11-27T03:11:16Z

This is the 2nd PR for Idempotency Key. This PR adds a UUIDv7 generator to REST Util.

First PR: Add idempotency-key-lifetime to ConfigResponse

Follow-ups (separate PRs)

Client opt-in wiring in RESTSessionCatalog and mutation calls.
E2E tests with test server idempotency layer.

nastra · 2025-11-27T07:01:23Z

core/src/test/java/org/apache/iceberg/rest/TestRESTUtil.java

  }
+
+  @Test
+  public void generateUuidV7_hasVersionAndVariant() {


nit: we don't use _ for method names

core/src/test/java/org/apache/iceberg/rest/TestRESTUtil.java

nastra · 2025-11-27T07:32:14Z

core/src/main/java/org/apache/iceberg/rest/RESTUtil.java

+   * 2-bit variant (RFC 4122, 0b10) - 62-bit random (rand_b)
+   */
+  public static String generateUuidV7() {
+    long epochMs = System.currentTimeMillis() & 0xFFFFFFFFFFFFL; // 48 bits


I haven't reviewed this yet but just wanted to link how the JDK generates a UUIDv7 in JDK26: openjdk/jdk@642ba4c

Thanks for the pointer! I didn’t realize JDK 26 includes UUIDv7. I’ll compare my implementation with UUID.ofEpochMillis, and align as needed.

I compared with JDK 26’s UUID.ofEpochMillis and our layout matches (48‑bit timestamp, version 7 nibble, RFC 4122 variant, 12+62 random bits). I’d like to keep a no‑arg generateUuidV7() to mirror UUID.randomUUID() and avoid exposing timestamps; since callers need a header value, it returns String. I’ll align by using SecureRandom and adding a 48‑bit range check. I won’t copy JDK code (licensing), but the behavior is equivalent. The test is also the same: verify version() == 7 and variant()==2.

huaxingao · 2025-11-28T20:03:13Z

core/src/main/java/org/apache/iceberg/rest/RESTUtil.java

  private static final Joiner NAMESPACE_ESCAPED_JOINER = Joiner.on(NAMESPACE_ESCAPED_SEPARATOR);
  private static final Splitter NAMESPACE_ESCAPED_SPLITTER =
      Splitter.on(NAMESPACE_ESCAPED_SEPARATOR);
+  private static final SecureRandom SECURE_RANDOM = new SecureRandom();


new SecureRandom() is relatively expensive; one shared instance is thread‑safe and sufficient.

pan3793 · 2025-12-01T09:24:11Z

I wonder if this can go to a more common package (maybe a dedicated UuidUtil under org.apache.iceberg.util), as UUIDv7 may also benefit other places that use UUID, for example, View's uuid, Field's id, then we can infer when it was generated from the uuid prefix

api/src/test/java/org/apache/iceberg/util/TestUUIDUtilV7.java

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java

singhpk234

LGTM, thanks @huaxingao !

ebyhr · 2025-12-02T01:01:14Z

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java

+    if ((epochMs >>> 48) != 0) {
+      throw new IllegalArgumentException("timestamp does not fit within 48 bits: " + epochMs);
+    }


nit: We could use checkArgument method instead:

Preconditions.checkArgument( (epochMs >>> 48) == 0, "timestamp does not fit within 48 bits: %s", epochMs);

nastra · 2025-12-02T06:16:58Z

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java

+  public static String generateUuidV7() {
+    long epochMs = System.currentTimeMillis();
+    Preconditions.checkArgument(
+        (epochMs >>> 48) == 0, "timestamp does not fit within 48 bits: %s", epochMs);


maybe this should be an IllegalStateException, since the user can't really provide an argument here and we're throwing a IAE? Also I would probably update the error msg to align with the rest of the codebase to something like Invalid timestamp: does not fit within 48 bits: ...

Fixed. Thanks

nastra

LGTM with one comment

pan3793 · 2025-12-02T06:28:29Z

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java

+   * <p>Layout: - 48-bit Unix epoch milliseconds - 4-bit version (0b0111) - 12-bit random (rand_a) -
+   * 2-bit variant (RFC 4122, 0b10) - 62-bit random (rand_b)
+   */
+  public static String generateUuidV7() {


How about returning UUID instead of String? then the caller can call toString if necessary.

Changed the return type to UUID.

ebyhr · 2025-12-02T06:34:59Z

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java

  }
+
+  /**
+   * Generate a RFC 9562 UUIDv7 string.


The returned type isn't string anymore.

Suggested change

* Generate a RFC 9562 UUIDv7 string.

* Generate a RFC 9562 UUIDv7.

### Why are the changes needed? https://datatracker.ietf.org/doc/html/rfc9562#name-uuid-version-7 https://uuidv7.org/ > The Key Benefits of UUIDv7 UUIDv7 is rapidly gaining traction for various use cases across many industries. Here are some of the primary benefits: > > 1. Time-Ordered and Sortable: UUIDv7 encodes the time of creation as part of the identifier, making it naturally sortable. This is especially valuable for systems where data needs to be ordered by time without needing an additional timestamp field. > ... I think it's very useful - e.g., use UUIDv7 as session ID, then we can infer the session creation time from the UUID itself, or use UUIDv7 as a staging dir name, then we can easily clean dangling staging folders (for example, created 3 months ago) with a prefix. Implementation is inspired by apache/iceberg#14700 ### How was this patch tested? New UTs are added. ### Was this patch authored or co-authored using generative AI tooling? No. Closes #7277 from pan3793/uuidv7. Closes #7277 1dc1801 [Cheng Pan] style 3c7d3c5 [Cheng Pan] Add UUID v7 generator Authored-by: Cheng Pan <chengpan@apache.org> Signed-off-by: Cheng Pan <chengpan@apache.org>

Add UUIDv7 generator to REST Util

b38dcb8

github-actions bot added the core label Nov 27, 2025

huaxingao requested a review from nastra November 27, 2025 04:20

nastra reviewed Nov 27, 2025

View reviewed changes

core/src/test/java/org/apache/iceberg/rest/TestRESTUtil.java Outdated Show resolved Hide resolved

address comments

68e0987

nastra reviewed Nov 27, 2025

View reviewed changes

switch to SecureRandom and adding a 48‑bit range check for ts

5329ef0

huaxingao commented Nov 28, 2025

View reviewed changes

move UUIDv7 to UUIDUtil

9bfba53

github-actions bot added the API label Dec 1, 2025

singhpk234 reviewed Dec 1, 2025

View reviewed changes

api/src/test/java/org/apache/iceberg/util/TestUUIDUtilV7.java Outdated Show resolved Hide resolved

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java Outdated Show resolved Hide resolved

api/src/main/java/org/apache/iceberg/util/UUIDUtil.java Outdated Show resolved Hide resolved

address comments

a3a8dde

singhpk234 approved these changes Dec 2, 2025

View reviewed changes

fix test name

4ebace1

ebyhr reviewed Dec 2, 2025

View reviewed changes

use Preconditions.checkArgument

704b9f9

nastra reviewed Dec 2, 2025

View reviewed changes

nastra approved these changes Dec 2, 2025

View reviewed changes

pan3793 reviewed Dec 2, 2025

View reviewed changes

address comments

9dc596e

ebyhr approved these changes Dec 2, 2025

View reviewed changes

pan3793 approved these changes Dec 2, 2025

View reviewed changes

fix java doc

7fc2ed8

nastra changed the title ~~Core: Add UUIDv7 generator to REST Util~~ Core: Add UUIDv7 generator Dec 2, 2025

nastra merged commit 16e8435 into apache:main Dec 2, 2025
45 checks passed

huaxingao deleted the idempotency_2 branch December 2, 2025 17:55

This was referenced Dec 3, 2025

Core: Send Idempotency-Key on mutation requests when advertised #14740

Merged

Add idempotency adapter and E2E coverage #14773

Open

pan3793 mentioned this pull request Dec 17, 2025

Add UUID v7 generator apache/kyuubi#7277

Closed

	* Generate a RFC 9562 UUIDv7 string.
	* Generate a RFC 9562 UUIDv7.

Core: Add UUIDv7 generator #14700

Core: Add UUIDv7 generator #14700

Uh oh!

Conversation

huaxingao commented Nov 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan3793 commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

singhpk234 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nastra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pan3793 commented Dec 1, 2025 •

edited

Loading