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:
- Write distribution — are writes spread evenly across shards or concentrated on one (hotspot)?
- Read locality — can a query be answered by one shard, or must it fan out to all?
- Range scan efficiency — can a time-range or cursor-based query skip irrelevant shards?
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.
Related terms
- Collision — UUID uniqueness guarantees
- Monotonic Counter — within-millisecond ordering
- Time Precision — UUID v7 timestamp resolution
- Sequential ID — sequential integers vs UUID v7
- Sortable ID — time-ordered identifier category
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.