druuid v0.3.0 Druuid
Druuid is used to generate datetime relative uuids that fit into a postgres bigint. It does this by reserving the higher order bits for the datetime and the lower order bits for some entropy.
Getting Started
The primary function is Druuid.gen/1
. This will return a new uuid
based on the 1970 UNIX epoch:
Druuid.gen()
#=> 12283551831556210035
You may wish to choose an epoch offset to make this number smaller if
you don’t need to worry about dates before a certain point. Druuid.epoch_offset/1
allows you to pass in an erlang datetime tuple as the offset point and Druuid.gen/1
can take this as an optional argument. For example, consider using Jan 1st, 2016 at midnight
as an anchor point:
{{2016,1,1},{0,0,0}}
|> Druid.epoch_offset
|> Druuid.gen
#=> 106596357117955988
If you wish to pass this along to other systems (such as using as an id in a RESTful url),
you might want to consider using the Druuid.encode/1
and the Druuid.decode/1
functions.
Druuid.encode/1
converts to a base 36 string and Druuid.decode/1
converts back to an integer.
Druuid.gen()
|> Druuid.encode
#=> "2lbpkins91z90"
Druuid also allows you to extract the datetime back out of the id with the Druuid.datetime/2
function.
If the id was generated using an offset, you’ll need to provide the offset used as the second argument.
The result is an erlang datetime tuple.
offset = Druuid.epoch_offset({{2016,1,1},{0,0,0}})
"taqi2f417zk"
|> Druuid.decode
|> Druuid.datetime(offset)
# => {{2016, 5, 27}, {19, 6, 15}}
Summary
Functions
Extracts the datetime from the druuid id given an epoch_offset (optional). If you used an offset to generate the druuid, you must provide the same offset to get the datetime back out
Decodes a base 36 string to a druuid integer
Encodes a druuid id as a base 36 string
Calculates an epoch offset from the given datetime
Generates a druuid id given an epoch_offset (optional)
Determinstically generates the druuid id from the variables given.
Unless you have a specific reason to override one of these, you probably want to use
the Druuid.gen/1
function
Functions
Specs
datetime(integer, integer) :: Tuple
Extracts the datetime from the druuid id given an epoch_offset (optional). If you used an offset to generate the druuid, you must provide the same offset to get the datetime back out.
Parameters
druuid
integer druuid idepoch_offset
(optional) integer value that offsets the 1970 epoch. Defaults to0
.
Examples:
iex> offset = Druuid.epoch_offset({{2016,1,1},{0,0,0}})
iex> Druuid.datetime(107044006789234035, offset)
{{2016, 5, 27}, {16, 37, 20}}
Specs
decode(String.t) :: integer
Decodes a base 36 string to a druuid integer.
Parameters
druuid_str
String base 36 representation of the druuid
Examples
iex> Druuid.decode("2lborpt3qr983")
12283551831556210035
Specs
encode(integer) :: String.t
Encodes a druuid id as a base 36 string.
Parameters
druuid
integer druuid id
Examples
iex> Druuid.encode(12283551831556210035)
"2lborpt3qr983"
Specs
epoch_offset(Tuple) :: integer
Calculates an epoch offset from the given datetime.
Parameters
offset_datetime
erlang datetime tuple from which to calculate the offset
Examples
iex> Druuid.epoch_offset({{2016, 1, 1}, {0, 0, 0}})
1451606400
Specs
gen(integer) :: integer
Generates a druuid id given an epoch_offset (optional).
Parameters
epoch_offset
(optional) integer value that offsets the 1970 epoch. Defaults to0
.
Specs
gen_from_values(integer, float, integer) :: integer
Determinstically generates the druuid id from the variables given.
Unless you have a specific reason to override one of these, you probably want to use
the Druuid.gen/1
function.
Parameters
epoch_offset
integer value that offsets the 1970 UNIX epoch. Defaults to0
.rand
float value representing a random sample b/w 0 and 1 from a uniform distribution.ts
integer timestamp representing the current time in seconds from the epoch.
Examples
iex> Druuid.gen_from_values(0, 0.0, 1)
8388608000