Implementation:Langchain ai Langgraph UUID6

Knowledge Sources	Langchain_ai_Langgraph
Domains	Checkpointing, ID_Generation
Last Updated	2026-02-11 16:00 GMT

Overview

Provides a custom `UUID` class and `uuid6()` factory function for generating UUID version 6 identifiers optimized for time-ordered database locality in LangGraph checkpoints.

Description

The UUID6 module is adapted from the `uuid6-python` package and bundled directly into LangGraph to avoid external dependency installation issues. It extends Python's standard `uuid.UUID` class to support UUID draft versions 6, 7, and 8, with the primary focus on UUID version 6 generation through the `uuid6()` function.

UUID version 6 is a field-compatible variant of UUID v1 that reorders the time fields for improved database locality. Where UUID v1 scatters the timestamp bits across non-contiguous fields (causing poor B-tree index performance), UUID v6 places the most significant time bits first, ensuring that temporally adjacent UUIDs sort adjacently. This makes UUID v6 ideal for checkpoint identifiers that must be lexicographically sortable by creation time.

The `uuid6()` function maintains a module-level `_last_v6_timestamp` variable to guarantee strict monotonicity: if the system clock returns the same or an earlier timestamp as the previous call, the function increments the timestamp by one 100-nanosecond interval. This prevents duplicate IDs even under rapid successive calls. The function accepts optional `node` and `clock_seq` parameters; when omitted, it generates random 48-bit and 14-bit values respectively using Python's `random` module.

Usage

Use `uuid6()` whenever you need to generate checkpoint IDs in LangGraph. The time-ordered nature of UUID v6 ensures that checkpoints can be efficiently queried and sorted by creation time without requiring a separate timestamp column or index. This is the default ID generation strategy for LangGraph checkpoint savers.

Code Reference

Source Location

• Repository: Langchain_ai_Langgraph
• File: libs/checkpoint/langgraph/checkpoint/base/id.py

Signature

class UUID(uuid.UUID):
    def __init__(
        self,
        hex: str | None = None,
        bytes: bytes | None = None,
        bytes_le: bytes | None = None,
        fields: tuple[int, int, int, int, int, int] | None = None,
        int: int | None = None,
        version: int | None = None,
        *,
        is_safe: uuid.SafeUUID = uuid.SafeUUID.unknown,
    ) -> None: ...

    @property
    def subsec(self) -> int: ...

    @property
    def time(self) -> int: ...

def uuid6(node: int | None = None, clock_seq: int | None = None) -> UUID: ...

Import

from langgraph.checkpoint.base.id import UUID, uuid6

I/O Contract

uuid6 Function

Parameter	Type	Required	Description
node	None`	No	48-bit node identifier; random if omitted
clock_seq	None`	No	14-bit clock sequence; random if omitted

Return Type	Description
`UUID`	A UUID version 6 instance with time-ordered fields

UUID Class Properties

Property	Type	Description
`time`	`int`	Timestamp extracted from the UUID fields (version-aware for v6, v7, v8)
`subsec`	`int`	Sub-second precision component (for v7/v8)
`version`	`int`	UUID version number (6, 7, or 8)

Monotonicity Guarantee

Behavior	Description
Timestamp collision	If current time <= last generated time, timestamp is incremented by 1 (100ns interval)
Global state	Module-level `_last_v6_timestamp` tracks the last used timestamp

Usage Examples

from langgraph.checkpoint.base.id import uuid6, UUID

# Generate a new UUID v6
checkpoint_id = uuid6()
print(str(checkpoint_id))  # e.g., "1ef1a2b3-c4d5-6e7f-8a9b-0c1d2e3f4a5b"
print(checkpoint_id.version)  # 6

# Generate multiple IDs - guaranteed monotonically increasing
ids = [uuid6() for _ in range(5)]
assert all(str(ids[i]) < str(ids[i + 1]) for i in range(len(ids) - 1))

# Parse an existing UUID v6 string
parsed = UUID("1ef1a2b3-c4d5-6e7f-8a9b-0c1d2e3f4a5b")
print(parsed.time)  # Timestamp in 100-nanosecond intervals since UUID epoch

# Use with custom node and clock sequence
custom_id = uuid6(node=0x123456789ABC, clock_seq=42)

Related Pages

• Principle:Langchain_ai_Langgraph_Checkpoint_ID_Generation