Apache Flink processes unbounded streams of events where every event needs a unique, ordered identifier. UUID v7 is particularly well-suited to Flink pipelines — the embedded millisecond timestamp eliminates the need for a separate event time field, lexicographic ordering maps directly to Flink’s event time semantics, and global uniqueness enables exactly-once deduplication. This page covers UUID v7 event IDs in Flink DataStream API jobs using the uuid-creator Java library on Maven Central, integrated with Kafka sources and JDBC sinks.
Extracting event time from UUID v7
import com.github.f4b6a3.uuid.UuidCreator;
import org.apache.flink.api.common.eventtime.*;
public class UuidV7WatermarkStrategy implements WatermarkStrategy<OrderEvent> {
@Override
public TimestampAssigner<OrderEvent> createTimestampAssigner(
TimestampAssignerSupplier.Context context) {
return (event, recordTimestamp) -> {
// Extract 48-bit ms timestamp from UUID v7 string
String hex = event.getEventId().replace("-", "").substring(0, 12);
return Long.parseUnsignedLong(hex, 16);
};
}
@Override
public WatermarkGenerator<OrderEvent> createWatermarkGenerator(
WatermarkGeneratorSupplier.Context context) {
return WatermarkStrategies.forBoundedOutOfOrderness(Duration.ofSeconds(5))
.createWatermarkGenerator(context);
}
}
This eliminates the created_at timestamp field — the UUID v7 ID is the single source of truth for event time. The Flink watermark documentation covers the WatermarkStrategy interface.
Kafka source with UUID v7 event IDs
import org.apache.flink.connector.kafka.source.KafkaSource;
import com.github.f4b6a3.uuid.UuidCreator;
KafkaSource<OrderEvent> source = KafkaSource.<OrderEvent>builder()
.setBootstrapServers("localhost:9092")
.setTopics("orders")
.setGroupId("flink-order-processor")
.setDeserializer(new OrderEventDeserializer())
.build();
DataStream<OrderEvent> events = env
.fromSource(source, new UuidV7WatermarkStrategy(), "Order Events Source");
Events arriving from Kafka carry UUID v7 IDs generated by the producer. The Flink job uses the UUID v7 timestamp as event time — even if Kafka delivers events slightly out of order, the bounded-out-of-orderness watermark strategy handles late arrivals within the configured window.
Keyed stream partitioning
// Key by tenant ID (UUID v4) — partition by tenant
// Order within partition by UUID v7 event ID (time-ordered)
DataStream<OrderEvent> keyedStream = events
.keyBy(event -> event.getTenantId()) // UUID v4 — even partition distribution
.process(new OrderStateMachineFunction());
Using UUID v4 as the partition key distributes load evenly across Flink task slots. UUID v7 event IDs within each partition sort chronologically, enabling correct state machine transitions (CREATED → SHIPPED → DELIVERED) without additional sorting.
Deduplication with ValueState
public class DeduplicateFunction extends KeyedProcessFunction<String, OrderEvent, OrderEvent> {
private ValueState<Boolean> seenState;
@Override
public void open(Configuration config) {
ValueStateDescriptor<Boolean> descriptor =
new ValueStateDescriptor<>("seen", Boolean.class);
// TTL: discard dedup state after 24 hours
descriptor.enableTimeToLive(
StateTtlConfig.newBuilder(Time.hours(24)).build()
);
seenState = getRuntimeContext().getState(descriptor);
}
@Override
public void processElement(OrderEvent event,
KeyedProcessFunction<String, OrderEvent, OrderEvent>.Context ctx,
Collector<OrderEvent> out) throws Exception {
if (seenState.value() == null) {
seenState.update(true);
out.collect(event);
}
// Duplicate — drop silently
}
}
// Key by UUID v7 event ID for deduplication
DataStream<OrderEvent> deduped = events
.keyBy(OrderEvent::getEventId)
.process(new DeduplicateFunction());
The TTL is set proportionally — UUID v7 event IDs older than 24 hours can be safely evicted because Flink’s Kafka consumer will not replay events older than the retention window. The Flink state TTL documentation covers cleanup strategies.
JDBC sink with UUID v7 primary keys
import org.apache.flink.connector.jdbc.JdbcSink;
DataStream<OrderAggregate> aggregates = /* windowed aggregation */;
aggregates.addSink(JdbcSink.sink(
"INSERT INTO order_aggregates (id, tenant_id, window_start, total) " +
"VALUES (?, ?, ?, ?) ON CONFLICT (id) DO UPDATE SET total = EXCLUDED.total",
(ps, agg) -> {
ps.setString(1, UuidCreator.getTimeOrderedEpoch().toString()); // UUID v7 PK
ps.setString(2, agg.getTenantId());
ps.setLong(3, agg.getWindowStart());
ps.setDouble(4, agg.getTotal());
},
JdbcExecutionOptions.builder().withBatchSize(1000).build(),
new JdbcConnectionOptions.JdbcConnectionOptionsBuilder()
.withUrl("jdbc:postgresql://localhost:5432/analytics")
.build()
));
The Flink JDBC connector documentation covers batch size, retry policies, and exactly-once sink configuration. The ON CONFLICT clause handles Flink checkpoint replay without duplicate rows.
Further reading
- UUID v7 in Kafka Event Streaming — Kafka producer patterns
- UUID v7 in Distributed Systems — ordering across services
- UUID in Databases — PostgreSQL JDBC sink storage
External references
- Apache Flink documentation
- uuid-creator on GitHub
- uuid-creator on Maven Central
- RFC 9562 — UUID standard
- PostgreSQL 18 UUID functions
Frequently asked questions
How does UUID v7 relate to Flink watermarks?
Flink watermarks track event time progress for windowed operations. If events carry UUID v7 IDs, you can extract the embedded 48-bit millisecond timestamp directly from the ID to assign event time — no separate timestamp field needed. Implement a custom WatermarkStrategy that parses the UUID v7 prefix: long ts = Long.parseUnsignedLong(uuidStr.replace("-","").substring(0,12), 16). The Flink watermark documentation covers bounded-out-of-orderness and custom watermark strategies.
Can UUID v7 replace Flink's internal event time assignments?
UUID v7 provides millisecond-precision event time embedded in the ID. For most Flink windowing operations this is sufficient — tumbling windows, sliding windows, and session windows all work at millisecond precision. UUID v7 does not replace Flink's checkpoint mechanism or state backends, which use internal sequence numbers. UUID v7 is appropriate as the event identifier and event time source, not as a substitute for Flink's internal coordination. The RFC 9562 standard defines the 48-bit timestamp layout.
How do I use UUID v7 for exactly-once deduplication in Flink?
In exactly-once pipelines, Flink may replay events on recovery. Deduplicate by storing processed UUID v7 event IDs in a Flink ValueState keyed by event ID: check if the ID is present before processing, then add it. UUID v7's global uniqueness per RFC 9562 ensures no two legitimate events share an ID. The Flink state documentation covers ValueState, TTL configuration, and state backend choices.