Snowflake ID

The 64-bit layout

A snowflake ID is a single 64-bit integer divided into four fields. Read left-to-right (most significant bit first):

| 1 bit | 41 bits          | 10 bits     | 12 bits         |
| sign  | timestamp (ms)   | machine ID  | sequence per ms |
|   0   | since epoch      | 0–1023      | 0–4095          |

The sign bit is always zero — keeping the ID positive lets it slot into a Java long or a Postgres bigint without sign-extension surprises. The timestamp field counts milliseconds since a custom epoch (Twitter chose 2010-11-04T01:42:54.657Z — the moment the format went live). The machine ID is the generator's identity, baked into config at deploy time. The sequence is a per-millisecond counter that resets to zero each time the timestamp advances.

Why those exact widths? 41 bits buys 69.7 years from the epoch — long enough that no one has to migrate format mid-decade. 10 bits = 1024 generators, comfortable for a fleet of dozens or low hundreds with room to grow. 12 bits = 4096 IDs per millisecond, which works out to 4 million per second per machine — well past any real per-node throughput. Adjust the widths and you get the variants Discord, Instagram, and Sony use.

Why not just use UUIDv4?

UUIDv4 is 128 bits of random entropy. Two huge wins: trivially decentralized (any process can mint one) and effectively collision-free (the birthday bound at 2^61 IDs is comfortable). The catch is database indexes.

A B-tree index over UUIDv4 sees insertions land at random positions. Every insert dirties a different page; the index's working set grows to the entire index. Postgres benchmarks routinely show UUIDv4 insertions running 2–5× slower than monotonically-increasing IDs once the index exceeds RAM. Snowflake IDs solve this: because the timestamp occupies the high bits, new IDs always insert to the right side of the index — append-only, cache-hot, page-split-free.

The downside is coordination. Each generator needs a unique machine ID and a roughly-synchronized clock. UUIDv4 needs neither.

Snowflake variants in the wild

• Twitter (original). 41/10/12. Custom epoch 2010-11-04. Open-sourced in Scala, retired in 2019 when Twitter moved to a different scheme.
• Discord. 41/10/12 with epoch 2015-01-01. The IDs in every Discord URL — /channels/<guild>/<channel> — are snowflakes.
• Instagram. 41/13/10 — 13-bit shard ID (8192 shards), 10-bit sequence (1024/ms). Designed to encode their MySQL shard topology directly into the ID.
• Sonyflake. 39/8/16 — 39 bits of 10ms-precision timestamp (174 years), 8-bit machine ID (256 hosts), 16-bit sequence. Trades resolution for lifespan and burst capacity.
• Snowflake-style ULID. 128 bits — 48 bits ms timestamp, 80 bits random. Same time-sortability, no machine-ID coordination, twice the storage.
• UUIDv7 (RFC 9562, 2024). 128 bits — 48 bits Unix ms, 12 bits sub-millisecond entropy, 62 bits random. The IETF-standard answer to "I want snowflake but in UUID format."

When snowflake is the right choice

• You need IDs faster than a central database can mint them. A MySQL auto-increment column is one row-lock per insert; snowflake is local arithmetic at four million per second per node.
• Your IDs land in a clustered B-tree index. Time-sortable IDs keep insert latency flat as the index grows; random IDs degrade as RAM pressure rises.
• You want time-encoded debugging. Decoding a snowflake gives you the creation timestamp for free — no separate created_at column needed for ordering.
• You can pre-allocate machine IDs. Hard-coding a generator ID per host (or per Kubernetes pod via downward-API) is straightforward; ZooKeeper-based dynamic assignment is the alternative for elastic clusters.

Snowflake is the wrong choice when you need IDs that don't leak creation time (replace with UUIDv4 or unguessable random), when your fleet has more than ~1024 generators without ID-space partitioning, or when generators come and go fast enough that machine-ID assignment becomes a problem.

Snowflake vs UUID variants

	Snowflake	UUIDv4	UUIDv7	ULID	KSUID	Auto-increment
Size	64 bits	128 bits	128 bits	128 bits	160 bits	32–64 bits
Time-sortable	Yes (ms)	No	Yes (ms)	Yes (ms)	Yes (s)	Yes
Decentralized	Yes (with machine ID)	Yes	Yes	Yes	Yes	No (single counter)
Embeds machine ID	Yes (10 bits)	No	No	No	No	No
Encodes creation time	Yes (ms)	No	Yes (ms)	Yes (ms)	Yes (s)	No
Coordination needed	Machine ID assignment	None	None	None	None	Central source
Per-generator throughput	4M/sec	Unlimited	Unlimited (sub-ms ctr)	Unlimited	Unlimited	Central limit

The right pick depends on what tradeoff you can afford. Snowflake's small footprint and embedded machine ID make it ideal for high-volume, well-controlled fleets. UUIDv7 is the modern default for general-purpose decentralized IDs because the size penalty (8 extra bytes) is rarely the bottleneck and the standards body has blessed it.

Pseudo-code

// Constants
EPOCH        = 1288834974657   // 2010-11-04T01:42:54.657Z in Unix ms
MACHINE_BITS = 10              // 1024 machines
SEQ_BITS     = 12              // 4096 IDs per ms per machine

MAX_MACHINE = (1 << MACHINE_BITS) - 1   // 1023
MAX_SEQ     = (1 << SEQ_BITS) - 1       // 4095

TIMESTAMP_SHIFT = MACHINE_BITS + SEQ_BITS  // 22
MACHINE_SHIFT   = SEQ_BITS                 // 12

// Generator state
machineId  = (assigned at boot, 0–1023)
lastMs     = 0
sequence   = 0

generate():
    now = current_unix_ms()
    if now < lastMs:
        panic("clock moved backward")
    if now == lastMs:
        sequence = (sequence + 1) & MAX_SEQ
        if sequence == 0:
            // exhausted this ms — spin until the next ms
            while now <= lastMs:
                now = current_unix_ms()
    else:
        sequence = 0
    lastMs = now

    id = ((now - EPOCH) << TIMESTAMP_SHIFT)
       | (machineId << MACHINE_SHIFT)
       | sequence
    return id

JavaScript implementation

// Uses BigInt because JS Number can't precisely represent 64-bit values.

class SnowflakeGenerator {
  constructor(machineId, epochMs = 1288834974657n) {
    if (machineId < 0 || machineId > 1023) throw new Error('machineId 0-1023');
    this.machineId = BigInt(machineId);
    this.epoch = epochMs;
    this.lastMs = 0n;
    this.seq = 0n;
  }

  nextId() {
    let now = BigInt(Date.now());
    if (now < this.lastMs) {
      throw new Error('clock moved backward: refusing to mint');
    }
    if (now === this.lastMs) {
      this.seq = (this.seq + 1n) & 0xfffn;
      if (this.seq === 0n) {
        // sequence exhausted — spin to next ms
        while (BigInt(Date.now()) <= this.lastMs) {}
        now = BigInt(Date.now());
      }
    } else {
      this.seq = 0n;
    }
    this.lastMs = now;

    return ((now - this.epoch) << 22n)
         | (this.machineId << 12n)
         | this.seq;
  }

  static decode(id, epochMs = 1288834974657n) {
    const bi = BigInt(id);
    return {
      timestamp: Number((bi >> 22n) + epochMs),
      machineId: Number((bi >> 12n) & 0x3ffn),
      sequence:  Number(bi & 0xfffn),
    };
  }
}

// Usage
const gen = new SnowflakeGenerator(42);
const id = gen.nextId();             // e.g. 1729012345678901234n
SnowflakeGenerator.decode(id);
// → { timestamp: 1734567890123, machineId: 42, sequence: 0 }

Common pitfalls

• Returning the ID as a JSON number. JavaScript's Number is IEEE 754 double — only 53 bits of integer precision. A 64-bit snowflake silently rounds when parsed by JSON.parse. Always serialize snowflakes as strings ("1729012345678901234") on the wire.
• Reusing machine IDs. Two generators with the same machine ID can collide in the same millisecond. Pin the machine ID via deployment config (Kubernetes downward API for pod-ordinal), ZooKeeper ephemeral nodes, or environment variable injected by your scheduler.
• Ignoring clock skew. NTP can step the clock forward (no big deal — sequence resets) or backward (catastrophic — duplicate IDs possible). Always check now >= lastMs and refuse to mint until the wall clock catches up.
• Leap seconds. Pre-2017, some kernels could repeat a second during a leap. Use a leap-smearing NTP source (Google Public NTP, AWS Time Sync) to avoid the issue entirely.
• Confusing snowflake bit ordering across language implementations. Some libraries put sequence in the high bits (anti-pattern — breaks sortability). Always verify the layout by decoding a known timestamp.

Performance characteristics

• ~50 ns per ID on modern x86. The hot path is one atomic read of monotonic time, one masking-and-shifting expression, and a 64-bit store. Zero allocations, zero network round-trips.
• 4096 IDs per ms hard cap per generator. Twelve bits of sequence space. Exceeded? Spin until the next ms, or widen the sequence field at the cost of timestamp resolution.
• 69.7 years from epoch. Twitter's snowflakes run out around 2080-09-07. Discord's around 2084. Plan a format migration before you hit the wall.
• ~50 bytes per ID at rest in JSON. Compared to UUID's ~36-char hex string, snowflake saves bandwidth and storage at scale — Twitter shaved petabytes off their tweet-ID column.
• O(1) decoding. Splitting a snowflake into (timestamp, machine, sequence) is three masking operations — no parsing, no allocation, sub-nanosecond on modern CPUs.