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

Propertytimeuuid (UUID v1)UUID v7
StandardRFC 4122 (legacy)RFC 9562
TimestampGregorian epoch (100ns)Unix epoch (1ms)
Node fieldMAC address (privacy risk)Random bits
Sort orderChronologicalChronological
CQL typetimeuuiduuid
Random bits1474

Further reading

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.