Skip to content

UUID version 7, which are time-sortable (following the Peabody RFC4122 draft)

License

Notifications You must be signed in to change notification settings

stevesimmons/uuid7

Repository files navigation

uuid7 - time-sortable UUIDs

This module implements the version 7 UUIDs, proposed by Peabody and Davis in https://www.ietf.org/id/draft-peabody-dispatch-new-uuid-format-02.html as an extension to RFC4122.

Version 7 has the nice characteristic that the start of a UUID encodes the time with a chronological sort order and potentially ~50ns time resolution, while the end of the UUID includes sufficient random bits to ensure consecutive UUIDs will remain unique.

Implementation notes

The 128 bits in the UUID are allocated as follows:

  • 36 bits of whole seconds
  • 24 bits of fractional seconds, giving approx 50ns resolution
  • 14 bits of sequential counter, if called repeatedly in same time tick
  • 48 bits of randomness

plus, at locations defined by RFC4122, 4 bits for the uuid version (0b111) and 2 bits for the uuid variant (0b10).

         0                   1                   2                   3
         0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
t1      |                 unixts (secs since epoch)                     |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
t2/t3   |unixts |  frac secs (12 bits)  |  ver  |  frac secs (12 bits)  |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
t4/rand |var|       seq (14 bits)       |          rand (16 bits)       |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
rand    |                          rand (32 bits)                       |
        +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Indicative timings:

  • uuid.uuid4() - 2.4us
  • uuid7() - 3.7us
  • uuid7(as_type='int') - 1.6us
  • uuid7(as_type='str') - 2.5us

Installation

> pip install uuid7

Usage

>>> from uuid_extensions import uuid7, uuid7str
>>> uuid7()
UUID('061cb26a-54b8-7a52-8000-2124e7041024')

>>> uuid7(0)
UUID('00000000-0000-0000-0000-00000000000')

>>> for fmt in ('bytes', 'hex', 'int', 'str', 'uuid', None):
...     print(fmt, repr(uuid7(as_type=fmt)))
bytes b'\x06\x1c\xb8\xfe\x0f\x0b|9\x80\x00\tjt\x85\xb3\xbb'
hex '061cb8fe0f0b7c3980011863b956b758'
int 8124504378724980906989670469352026642
str '061cb8fe-0f0b-7c39-8003-d44a7ee0bdf6'
uuid UUID('061cb8fe-0f0b-7c39-8004-0489578299f6')
None UUID('061cb8fe-0f0f-7df2-8000-afd57c2bf446')

>>> uuid7str() # Shorthand for uuid7(as_type='str')
'061cb26a-54b8-7a52-8000-2124e7041024'

Licence

  • Free software: MIT license

About

UUID version 7, which are time-sortable (following the Peabody RFC4122 draft)

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published