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

datetime(druuid, epoch_offset \\ 0)

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 id
  • epoch_offset (optional) integer value that offsets the 1970 epoch. Defaults to 0.

Examples:

iex> offset = Druuid.epoch_offset({{2016,1,1},{0,0,0}})
iex> Druuid.datetime(107044006789234035, offset)
{{2016, 5, 27}, {16, 37, 20}}
decode(druuid_str)

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
encode(druuid)

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"
epoch_offset(offset_datetime)

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
gen(epoch_offset \\ 0)

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 to 0.
gen_from_values(epoch_offset, rand, ts)

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 to 0.
  • 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