Was this page helpful?
UUIDs¶
UUIDs are 128-bit identifiers that can be used to uniquely identify information
without requiring central coordination. These are often used in ScyllaDB/Cassandra
for primary and clustering keys. There are two types of UUIDs supported by
the driver (and ScyllaDB/Cassandra), version 1 which is time-based and version 4 which
is randomly generated. Version 1 can be used with ScyllaDB/Cassandra’s timeuuid type
and can be used as a timestamp for data. Timestamp information can be
extracted from the time part of a version 1 UUID using cass_uuid_timestamp().
Version 4 can be used with ScyllaDB/Cassandra’s uuid type for unique identification.
Generator¶
A UUID generator object is used to create new UUIDs. The CassUuidGen object
is thread-safe. It should only be created once per application and reused.
Within one wall-clock millisecond, one generator can allocate 10,000 distinct
version 1 UUID timestamps. When the generated timestamp is in the current
millisecond and this capacity is exhausted, calls to cass_uuid_gen_time()
busy-wait until the system clock advances, consuming CPU and adding latency.
If the system clock moves backward, or a thread uses a stale clock sample after another thread advances the timestamp, the generator preserves monotonicity by incrementing the last timestamp. Generated timestamps can therefore move ahead of wall time. At sustained rates above 10 million UUIDs per second, this drift can grow indefinitely. See issue #507 for possible improvements.
CassUuidGen* uuid_gen = cass_uuid_gen_new();
CassUuid uuid;
/* Generate a version 1 UUID */
cass_uuid_gen_time(uuid_gen, &uuid);
/* Generate a version 1 UUID from an existing timestamp */
cass_uuid_gen_from_time(uuid_gen, 1234, &uuid);
/* Generate a version 4 UUID */
cass_uuid_gen_random(uuid_gen, &uuid);
cass_uuid_gen_free(uuid_gen);
A CassUuidGen can also be created with user provided information for the
node part of the UUID. This only affects version 1 UUIDs.
/* Only the 48 least signficant bits of the node are considered */
cass_uint64_t node = 0x0000AAAABBBBCCCC;
CassUuidGen* uuid_gen = cass_uuid_gen_new_with_node(node);
/* Generate UUIDs */
cass_uuid_gen_free(uuid_gen);
Extracting information¶
Information such as the timestamp (for version 1 only) and the version can be extracted from UUIDs. They can also be converted to and created from the their hexadecimal string representation e.g. “550e8400-e29b-41d4-a716-446655440000”.
CassUuid uuid;
cass_uuid_from_string("550e8400-e29b-41d4-a716-446655440000", &uuid);
/* Extract timestamp and version */
cass_uint64_t timestamp = cass_uuid_timestamp(uuid);
cass_uint8_t version = cass_uuid_version(uuid);
/* Get string representation of the UUID */
char uuid_str[CASS_UUID_STRING_LENGTH];
cass_uuid_string(uuid, uuid_str);