Ecto.UUID

Тип Ecto для строк UUID.

Автогенерация

Этот тип можно использовать для любого поля UUID в ваших схемах. Он используется при автоматической генерации бинарных идентификаторов в Ecto.Schema. По умолчанию автоматически сгенерированные UUID используют версию 4 (случайную):

use Ecto.Schema
@primary_key {:id, :binary_id, autogenerate: true}

Чтобы вместо этого использовать UUID версии 7 (упорядоченные по времени):

use Ecto.Schema
@primary_key {:id, Ecto.UUID, autogenerate: [version: 7]}

Чтобы использовать монотонные UUID версии 7 (упорядоченные по времени):

use Ecto.Schema
@primary_key {:id, Ecto.UUID, autogenerate: [version: 7, precision: :monotonic]}

Согласно RFC 9562: «Монотонность (каждое последующее значение больше предыдущего) — основа сортируемых UUID, основанных на времени».

Краткое описание

option(): Поддерживаемые параметры: :version и :precision (только для v7).
options()
raw(): Необработанное бинарное представление UUID.
t(): Строка UUID в шестнадцатеричном формате.

bingenerate(opts \\ []): Генерирует UUID в бинарном формате с заданными параметрами. Подробные сведения и доступные параметры см. в generate/1.
cast(uuid): Преобразует строку в каноническом, удобочитаемом формате UUID или 16-байтовое бинарное значение в UUID в каноническом, удобочитаемом формате UUID.
cast!(uuid): То же, что и cast/1, но вызывает исключение Ecto.CastError при недопустимых аргументах.
dump(uuid_string): Преобразует строку, представляющую UUID, в необработанное бинарное значение.
dump!(uuid): То же, что и dump/1, но вызывает исключение Ecto.ArgumentError при недопустимых аргументах.
embed_as(_): Реализация обратного вызова для Ecto.Type.embed_as/1.
equal?(term1, term2): Реализация обратного вызова для Ecto.Type.equal?/2.
generate(opts \\ []): Генерирует строку UUID.
load(raw_uuid): Преобразует бинарный UUID в строку.
load!(value): То же, что и load/1, но вызывает исключение Ecto.ArgumentError при недопустимых аргументах.

Типы

option()Исходный код

@type option() :: {:version, 4 | 7} | {:precision, :millisecond | :monotonic}

Поддерживаемые параметры: :version и :precision (только для v7).

options()Исходный код

@type options() :: [option()]

raw()Исходный код

@type raw() :: <<_::128>>

Необработанное бинарное представление UUID.

t()Исходный код

@type t() :: <<_::288>>

Строка UUID в шестнадцатеричном формате.

Функции

bingenerate(opts \\ [])Исходный код

@spec bingenerate(options()) :: raw()

Генерирует UUID в бинарном формате с заданными параметрами. Подробные сведения и доступные параметры см. в generate/1.

cast(uuid)Исходный код

@spec cast(t() | raw() | any()) :: {:ok, t()} | :error

Преобразует строку в каноническом, удобочитаемом формате UUID или 16-байтовое бинарное значение в UUID в каноническом, удобочитаемом формате UUID.

Если uuid не является ни тем, ни другим, будет возвращено :error.

Поскольку и бинарные значения, и строки представлены в виде бинарных значений, некоторые строки, которые вы могли бы не ожидать, на самом деле также являются допустимыми UUID в бинарном формате и потому преобразуются в строковый формат.

Если вам требуется более строгая обработка или проверка, следует определить собственный тип Ecto.Type. Кроме того, доступна функция Ecto.UUID.load/1, если нужно обрабатывать только UUID в формате raw; она может быть более подходящей обратной операцией для Ecto.UUID.dump/1.

Примеры

iex> Ecto.UUID.cast(<<0x60, 0x1D, 0x74, 0xE4, 0xA8, 0xD3, 0x4B, 0x6E,
...>                  0x83, 0x65, 0xED, 0xDB, 0x4C, 0x89, 0x33, 0x27>>)
{:ok, "601d74e4-a8d3-4b6e-8365-eddb4c893327"}

iex> Ecto.UUID.cast("601d74e4-a8d3-4b6e-8365-eddb4c893327")
{:ok, "601d74e4-a8d3-4b6e-8365-eddb4c893327"}

iex> Ecto.UUID.cast("warehouse worker")
{:ok, "77617265-686f-7573-6520-776f726b6572"}

cast!(uuid)Исходный код

@spec cast!(t() | raw() | any()) :: t()

То же, что и cast/1, но вызывает исключение Ecto.CastError при недопустимых аргументах.

dump(uuid_string)Исходный код

@spec dump(uuid_string :: t() | any()) :: {:ok, raw()} | :error

Преобразует строку, представляющую UUID, в необработанное бинарное значение.

dump!(uuid)Исходный код

@spec dump!(t() | any()) :: raw()

То же, что и dump/1, но вызывает исключение Ecto.ArgumentError при недопустимых аргументах.

embed_as(_)Исходный код

Реализация обратного вызова для Ecto.Type.embed_as/1.

equal?(term1, term2)Исходный код

Реализация обратного вызова для Ecto.Type.equal?/2.

generate(opts \\ [])Исходный код

@spec generate(options()) :: t()

Генерирует строку UUID.

Параметры

:version — версия генерируемого UUID. Поддерживаются значения 4 (случайная) и 7 (упорядоченная по времени). По умолчанию используется 4.

Параметры (только для версии 7)

:precision — точность временной метки для UUID версии 7. Поддерживаются значения :millisecond и :monotonic. По умолчанию используется :millisecond.

Монотонная точность

При использовании :monotonic точность до долей миллисекунды кодируется в поле rand_a. Сгенерированные UUID версии 7 строго монотонно возрастают (для каждого узла), даже если за одну временную метку создано несколько UUID. Это полезно для сохранения порядка вставки в базах данных.

Примеры

> Ecto.UUID.generate()
"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

> Ecto.UUID.generate(version: 7)
"018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"

> Ecto.UUID.generate(version: 7, precision: :millisecond)
"018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"

> Ecto.UUID.generate(version: 7, precision: :monotonic)
"018ec4c1-ae46-7f5a-8f5a-6f5a8f5a6f5a"

load(raw_uuid)Исходный код

@spec load(raw() | any()) :: {:ok, t()} | :error

Преобразует бинарный UUID в строку.

load!(value)Исходный код

@spec load!(raw() | any()) :: t()

То же, что и load/1, но вызывает исключение Ecto.ArgumentError при недопустимых аргументах.