ksuid generator

KSUID, which stands for K-Sortable Unique Identifier, is a unique ID format created by the engineering team at Segment (now part of Twilio) to address a specific challenge in their data infrastructure: they needed identifiers that were globally unique, like UUIDs, but that also sorted naturally by creation time without requiring a separate timestamp column. Introduced around 2017, KSUID was born from the practical demands of processing billions of events across a distributed analytics pipeline where chronological ordering of records was essential for debugging, auditing, and efficient database operations.

The core insight behind KSUID is that embedding a timestamp in the most significant bits of an identifier causes lexicographic sorting to align with chronological sorting. This means that standard string comparison operations, database index scans, and alphabetical ordering all produce results in creation-time order without any special logic. This property, sometimes called "natural sortability," makes KSUIDs particularly valuable in systems where data is append-heavy and queries frequently involve time-range filters. Unlike randomly generated identifiers that scatter across index space, KSUIDs cluster temporally, which can improve database write performance and query efficiency in B-tree-based storage engines.

KSUID has been adopted well beyond Segment's internal infrastructure. It is available as a library in Go, Python, Ruby, Java, Rust, and numerous other languages, and it has become a popular choice for developers who need a straightforward, time-sortable identifier without the complexity of more elaborate schemes.

How KSUID Works

A KSUID is a 160-bit (20-byte) value composed of two distinct segments: a 32-bit timestamp and a 128-bit random payload.

The timestamp occupies the first 4 bytes and represents the number of seconds elapsed since a custom epoch of May 13, 2014 (Unix timestamp 1400000000). This custom epoch was chosen deliberately to maximize the useful lifespan of the 32-bit timestamp field. By starting the clock roughly 44 years after the Unix epoch of January 1, 1970, KSUIDs gain decades of additional range before the timestamp overflows. A 32-bit unsigned integer can represent approximately 136 years of seconds, and since the KSUID epoch begins in 2014, the format will not exhaust its timestamp space until well into the 22nd century. The second-level precision of the timestamp means that KSUIDs created within the same second share the same timestamp prefix, with their relative ordering within that second determined by the random payload.

The payload occupies the remaining 16 bytes (128 bits) and consists of cryptographically secure random data. This payload serves two purposes: it guarantees uniqueness among KSUIDs generated within the same second, and it makes the identifiers unpredictable. With 128 bits of randomness, the probability of two KSUIDs colliding within a single second is approximately 1 in 3.4 x 10^38, which is effectively zero for any practical workload.

The raw 20-byte binary value is then encoded using base62 (the characters 0-9, A-Z, and a-z), producing a fixed-length string of exactly 27 characters. Base62 encoding was chosen over base64 because it avoids the special characters (+, /, =) that make base64 strings problematic in URLs, filenames, and other contexts. The resulting string is naturally case-sensitive and sorts lexicographically in the same order as the underlying binary value, preserving the time-ordering property.

A typical KSUID looks like 2MJg6MBRiLBbSALnHxA2ixC24sB. The first few characters correspond to the timestamp, and the remainder represents the random payload, though the base62 encoding makes the boundary between the two components non-obvious in the string representation. Developers can extract the embedded timestamp programmatically using any KSUID library, which provides the creation time with second-level precision.

Because the timestamp occupies the most significant bytes, KSUIDs generated at different times will always sort chronologically. Within the same second, KSUIDs sort in an order determined by their random payloads, which is effectively arbitrary. This means KSUID provides second-resolution temporal ordering, which is sufficient for the vast majority of applications but less precise than formats like ULID that encode millisecond timestamps.

Use Cases

Event sourcing and audit logs. Systems that record every state change as an immutable event benefit enormously from KSUIDs. Each event receives a naturally time-ordered identifier, enabling efficient range queries over event streams without maintaining a separate index on a timestamp column. Replaying events in order, debugging sequences of operations, and building materialized views all become simpler when the primary key itself encodes creation time.

Distributed database primary keys. In distributed databases that use B-tree or LSM-tree storage engines, randomly generated identifiers like UUID v4 cause write amplification because new records are inserted at scattered positions across the index. KSUIDs, by contrast, cluster new writes near the end of the index space (since they share a recent timestamp prefix), resulting in more sequential write patterns and better cache utilization. This property makes KSUIDs a practical performance optimization for high-throughput, write-heavy workloads.

API resource identifiers. KSUIDs make excellent identifiers for API resources because they are URL-safe, reasonably compact at 27 characters, and carry embedded creation-time information. API consumers can sort resources chronologically by their identifiers alone, and backend developers can extract approximate creation timestamps without additional database lookups. The base62 encoding ensures that KSUIDs work in URLs, HTTP headers, and JSON payloads without escaping.

Message queuing and stream processing. In message brokers and stream processing systems, KSUIDs provide natural ordering guarantees that simplify consumer logic. Messages can be deduplicated, ordered, and partitioned using their KSUID alone, reducing the need for composite keys or additional metadata fields. The second-level timestamp precision is typically more than sufficient for message ordering in most real-world throughput scenarios.

Comparison with Alternatives

Compared to ULID, KSUID offers a larger total size (160 bits versus 128 bits) and uses a different encoding scheme (base62 versus Crockford's base32). ULID encodes a millisecond-precision timestamp in its first 48 bits, providing finer temporal resolution than KSUID's second-precision 32-bit timestamp. However, KSUID compensates with a larger random payload (128 bits versus ULID's 80 bits), which provides significantly stronger collision resistance within any given time window. ULID's 26-character Crockford base32 output is case-insensitive and one character shorter than KSUID's 27-character base62 output. The choice between them often comes down to whether millisecond ordering or a larger entropy pool matters more for the application.

Compared to UUID v7, KSUID predates the UUID v7 specification and solves a similar problem: combining time-based sorting with random uniqueness. UUID v7 fits into the standard 128-bit, 36-character UUID format with hyphens, making it a drop-in replacement for existing UUID v4 columns in databases that enforce UUID formatting. KSUID's 160-bit structure provides more total entropy and its base62 encoding produces a more compact string, but it lacks the universal tooling and standardized format that UUID v7 inherits from the UUID specification. For greenfield projects, UUID v7 offers better ecosystem compatibility, while KSUID offers a more compact representation with stronger collision guarantees.

Compared to UUID v4, KSUID's primary advantage is time-sortability. UUID v4 identifiers are purely random and scatter uniformly across the key space, providing no temporal ordering and causing well-documented index fragmentation in B-tree databases. KSUID solves this problem by design. However, UUID v4 remains the most widely recognized and supported identifier format in software, with native support in virtually every database, ORM, and programming language. Applications that do not benefit from time-ordering may find UUID v4's universal compatibility more important than KSUID's sorting properties.