UUID to a high/low 64-bit pair

Why getMostSignificantBits returns a negative number#

Java has no unsigned 64-bit type. UUID#getMostSignificantBits hands back the same bits as the unsigned reading above, printed as a signed long, so any identifier whose first hex digit is 8 or higher prints negative. Nothing is lost: subtract 2^64 from the unsigned value when it is 2^63 or more, and you have Java's number.

The second row is below 2^63, so both readings agree. That is the whole of the mystery.

The two readings this tool offers#

The unsigned reading takes each half big-endian, exactly as the identifier is written: the high word of f81d4fae-7dec-11d0-… is 0xf81d4fae7dec11d0. The signed reading takes each half little-endian and prints it as a signed integer. That is the shape a little-endian machine gives when it reinterprets the bytes in place, as ByteBuffer in LITTLE_ENDIAN order or BitConverter.ToInt64 do.

The same pair in each language#

UUID id = UUID.fromString("f81d4fae-7dec-11d0-a765-00a0c91e6bf6");

long msb = id.getMostSignificantBits();   // -568210367123287600
long lsb = id.getLeastSignificantBits();  // -6384696206158828554

// the unsigned reading of the same bits
String hi = Long.toUnsignedString(msb);   // 17878533706586264016

UUID back = new UUID(msb, lsb);           // f81d4fae-7dec-11d0-a765-00a0c91e6bf6

The pair as a protobuf message#

A 128-bit identifier has no home in protobuf: there is no uint128, and bytes costs a length prefix and loses fixed width. Two 64-bit fields fit exactly, which is what bavix/apis declares for the whole API surface.

syntax = "proto3";

package bavix.api.v1;

option go_package = "github.com/bavix/apis/pkg/bavix/api/v1";

// UUID is a message that represents a UUID.
//
// A UUID is composed of two 64-bit values, each representing a part of the UUID.
// The high part is stored in the high field, and the low part is stored in the
// low field.
message UUID {
    // The high part of the UUID.
    int64 high = 1;
    // The low part of the UUID.
    int64 low = 2;
}

Note the type: int64, not uint64. Protobuf has both, and the choice here follows what Go hands you, which is the reading below.

The reading that message carries#

The reference implementation reinterprets the sixteen bytes in place, eight at a time:

func UUID2DoubleInt(v uuid.UUID) (int64, int64) {
	return *(*int64)(unsafe.Pointer(&v[0])), *(*int64)(unsafe.Pointer(&v[8]))
}

func DoubleInt2UUID(highValue int64, lowValue int64) uuid.UUID {
	var uuidValue uuid.UUID

	*(*int64)(unsafe.Pointer(&uuidValue[0])) = highValue
	*(*int64)(unsafe.Pointer(&uuidValue[8])) = lowValue

	return uuidValue
}

On a little-endian machine, which is every amd64 and arm64 server, that reinterpretation reads each half **least significant byte first**. It is the signed reading in the converter, so the numbers on this page and the numbers that message carries are the same numbers.

• bavix/apis — bavix/api/v1/uuid.protoThe message above, in full
• bavix/apis — pkg/uuidconv/uuid.goUUID2DoubleInt and DoubleInt2UUID, the signed reading
• bavix/apisThe protobuf definitions these services share

Why store a UUID as two longs at all#

Two bigint columns beat a 36-character string on both storage and comparison, and a protobuf message with two fixed64 fields is 18 bytes on the wire against 36 for the text. The cost is that the identifier stops being readable, and that every service touching it has to agree on the byte order and on the sign convention. Write both down where the schema lives.

RFC 9562 § 4.1 · Variant FieldThe variant bits live in the low half, which is why the low word rarely looks random

RFC 9562 § 6.13 · DBMS and Database ConsiderationsWhat the standard says about storing UUIDs in a database