Definition

A shard key (also called a partition key) is the column or value used to determine which database node, shard, or partition stores a given row. The choice of shard key directly affects:

UUID v4 vs UUID v7 as a shard key

UUID v4:  550e8400-e29b-41d4-a716-446655440000
          ↑ all 122 bits random — perfectly uniform distribution, no range structure

UUID v7:  018fbe3a-4c5d-7b12-8abc-0123456789ab
          ↑↑↑↑↑↑↑↑↑↑↑↑ 48-bit timestamp — enables range pruning
                        ↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑ 74-bit random suffix — even distribution

UUID v7 combines the write distribution of UUID v4 (random suffix) with the range-scan capability of a sequential integer (timestamp prefix). See Time Precision for the 48-bit millisecond timestamp detail.

MongoDB — UUID v7 shard key

// MongoDB — shard a collection on UUID v7 _id
db.adminCommand({
  shardCollection: 'mydb.orders',
  key: { _id: 'hashed' },  // hashed sharding — even distribution regardless of UUID version
});

// Or range sharding — works best with UUID v7 (time-ordered chunks)
db.adminCommand({
  shardCollection: 'mydb.orders',
  key: { _id: 1 },  // range sharding — UUID v7 chunks align with time windows
});

With range sharding, MongoDB chunk boundaries naturally correspond to time windows when the shard key is UUID v7 — a chunk migration moves a cohesive time range rather than a random scatter of records. See UUID in MongoDB.

PostgreSQL — partition by UUID v7 range

-- Partition by UUID v7 time range (equivalent to monthly partitions)
CREATE TABLE events (
  id         uuid NOT NULL,
  payload    jsonb,
  created_at timestamptz NOT NULL DEFAULT now()
) PARTITION BY RANGE (id);

-- Partition for Q4 2025 — UUID v7 bounds derived from timestamps
CREATE TABLE events_2025_q4 PARTITION OF events
  FOR VALUES FROM ('018fcc00-0000-7000-8000-000000000000')
             TO   ('018fd600-0000-7000-8000-000000000000');

UUID v7 partition bounds can be derived from timestamps — no separate date column is needed to define time-range partitions. See UUID in Databases for the B-tree fragmentation analysis.

Cassandra — UUID v7 partition key

-- Cassandra CQL — UUID v7 as partition key with time-bucketing
CREATE TABLE orders (
  bucket     text,     -- e.g., '2025-10' — coarse time bucket to limit partition size
  id         uuid,     -- UUID v7 — fine-grained ordering within bucket
  status     text,
  PRIMARY KEY (bucket, id)
) WITH CLUSTERING ORDER BY (id ASC);

-- Insert
INSERT INTO orders (bucket, id, status)
VALUES ('2025-10', uuid_v7_value, 'pending');

-- Time-range query within a bucket — efficient single-partition scan
SELECT * FROM orders
WHERE bucket = '2025-10'
  AND id >= lower_bound_uuid7
  AND id < upper_bound_uuid7;

In Cassandra, the partition key must be narrow enough that each partition fits in memory. UUID v7 alone would create one partition per row — coarse time-bucketing (bucket = '2025-10') controls partition size while UUID v7 provides ordering within the partition.

External references

Frequently asked questions

Why is UUID v4 a bad shard key but UUID v7 is acceptable?

UUID v4 is purely random — writes distribute uniformly across shards, which is actually good for write throughput. The problem is read performance: range queries on UUID v4 must scan every shard because the key has no order. UUID v7's timestamp prefix gives range queries a pruning opportunity — a query for records created in the last hour can skip shards whose ID ranges fall outside the corresponding UUID v7 bounds. UUID v7 distributes writes nearly as evenly as v4 (the random 74-bit suffix prevents hot shards) while enabling bounded range scans. See UUID v4 vs v7.

Does CockroachDB work well with UUID v7 shard keys?

Yes. CockroachDB distributes ranges by key — UUID v7's random suffix prevents hotspot ranges while the timestamp prefix enables efficient time-range queries. CockroachDB recommends UUID v4 or v7 over sequential integers precisely because sequential keys cause all new writes to land on a single range until it splits. UUID v7 is slightly better than v4 for range-based pagination. See UUID v7 in Distributed Systems.