ScyllaDB is a Cassandra-compatible database optimized for low-latency, high-throughput workloads. UUID v7 replaces Cassandra’s timeuuid (UUID v1) as the time-ordered clustering key of choice — maintaining wide-row chronological ordering with an RFC-standard format. See Sortable ID for context on time-ordered identifiers.
CQL schema with UUID v7 clustering key
CREATE TABLE events (
user_id uuid,
id uuid, -- UUID v7 clustering key — time-ordered per user
event_type text,
payload text,
PRIMARY KEY (user_id, id)
) WITH CLUSTERING ORDER BY (id ASC);
-- Table for sensor readings: sensor as partition, UUID v7 as clustering
CREATE TABLE sensor_readings (
sensor_id uuid,
id uuid, -- UUID v7 — encodes reading time
value double,
PRIMARY KEY (sensor_id, id)
) WITH CLUSTERING ORDER BY (id ASC)
AND default_time_to_live = 2592000; -- 30 days TTL
Node.js client with UUID v7
import { Client } from 'cassandra-driver';
import { v7 as uuidv7 } from 'uuid';
const client = new Client({
contactPoints: ['localhost:9042'],
localDataCenter: 'datacenter1',
keyspace: 'app',
});
await client.connect();
// Insert event — UUID v7 as clustering key
async function insertEvent(userId: string, eventType: string, payload: object) {
const id = uuidv7(); // UUID v7 — encodes event creation time
await client.execute(
'INSERT INTO events (user_id, id, event_type, payload) VALUES (?, ?, ?, ?)',
[userId, id, eventType, JSON.stringify(payload)],
{ prepare: true }
);
return id;
}
// Cursor pagination within a partition
async function getEvents(userId: string, cursor?: string, limit = 20) {
const query = cursor
? 'SELECT id, event_type, payload FROM events WHERE user_id = ? AND id > ? ORDER BY id ASC LIMIT ?'
: 'SELECT id, event_type, payload FROM events WHERE user_id = ? ORDER BY id ASC LIMIT ?';
const params = cursor ? [userId, cursor, limit] : [userId, limit];
const result = await client.execute(query, params, { prepare: true });
return {
rows: result.rows,
nextCursor: result.rows.length === limit ? result.rows.at(-1).id : null,
};
}
TTL alignment with UUID v7 timestamp
// Extract age from UUID v7 — set remaining TTL for expiring records
function getRemainingTtl(uuidV7: string, windowMs: number): number {
const hex = uuidV7.replace(/-/g, '').slice(0, 12);
const createdMs = parseInt(hex, 16);
const ageMs = Date.now() - createdMs;
const remainMs = windowMs - ageMs;
return Math.max(Math.floor(remainMs / 1000), 1); // seconds
}
// Insert with remaining TTL (e.g., 24-hour idempotency window)
async function insertWithTtl(userId: string, id: string, payload: object) {
const ttl = getRemainingTtl(id, 86_400_000); // 24 hours
await client.execute(
'INSERT INTO events (user_id, id, payload) VALUES (?, ?, ?) USING TTL ?',
[userId, id, JSON.stringify(payload), ttl],
{ prepare: true }
);
}
Go client with UUID v7
package main
import (
"github.com/gocql/gocql"
"github.com/google/uuid"
)
func insertEvent(session *gocql.Session, userID uuid.UUID, eventType, payload string) (uuid.UUID, error) {
id, err := uuid.NewV7()
if err != nil {
return uuid.Nil, err
}
return id, session.Query(
`INSERT INTO events (user_id, id, event_type, payload) VALUES (?, ?, ?, ?)`,
userID, id, eventType, payload,
).Exec()
}
UUID v7 vs timeuuid comparison
| Property | timeuuid (UUID v1) | UUID v7 |
|---|---|---|
| Standard | RFC 4122 (legacy) | RFC 9562 |
| Timestamp | Gregorian epoch (100ns) | Unix epoch (1ms) |
| Node field | MAC address (privacy risk) | Random bits |
| Sort order | Chronological | Chronological |
| CQL type | timeuuid | uuid |
| Random bits | 14 | 74 |
Further reading
- Sortable ID — Time-Ordered Identifiers
- Hot Spot — Index Contention
- UUID v7 in Kafka Event Streaming
- UUID in Databases — Storage and Indexing
- UUID v7 in Distributed Systems
External references
Frequently asked questions
Should I use UUID v7 or timeuuid in ScyllaDB?
ScyllaDB's timeuuid type is UUID v1 — it sorts by time but leaks the MAC address and uses a Gregorian epoch. UUID v7 is the RFC 9562 successor with a Unix epoch timestamp, 74 random bits (no MAC), and standard hex encoding. ScyllaDB stores UUID v7 in the native uuid column type. For new tables, UUID v7 is preferred for privacy and standard compliance. See UUID v6 for the v1 successor comparison.
How do I use UUID v7 as a ScyllaDB clustering key?
Declare the clustering column as uuid type and sort with WITH CLUSTERING ORDER BY (id ASC). ScyllaDB stores clustering keys in sorted order within each partition — UUID v7 lexicographic sort equals chronological, so SELECT * FROM events WHERE partition_id = ? AND id > ? retrieves events after a cursor in time order. See UUID v7 in Kafka Event Streaming.
How does UUID v7 help avoid hot partitions in ScyllaDB?
A hot partition occurs when too many writes target the same partition key. Using UUID v7 as the partition key distributes writes randomly across the ring because the random bits in UUID v7 vary. The timestamp prefix provides sort order within each partition when used as a clustering key. See Hot Spot — Index Contention.