# `Ecto.UUID`
[🔗](https://github.com/elixir-ecto/ecto/blob/v3.14.0/lib/ecto/uuid.ex#L1)

An Ecto type for UUID strings.

## Autogeneration

This type can be used for any UUID field in your schemas.
It is used when autogenerating binary IDs in Ecto.Schema.
By default, autogenerated UUIDs use version 4 (random):

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

To use UUID v7 (time-ordered) instead:

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

To use UUID v7 (time-ordered) monotonic:

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

According to [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562#name-monotonicity-and-counters):
"Monotonicity (each subsequent value being greater than the last) is the
backbone of time-based sortable UUIDs."

# `option`

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

Supported options: `:version` and `:precision` (v7-only).

# `options`

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

# `raw`

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

A raw binary representation of a UUID.

# `t`

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

A hex-encoded UUID string.

# `bingenerate`

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

Generates a uuid with the given options in binary format.
See `generate/1` for details and available options.

# `cast`

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

Casts either a string in the canonical, human-readable UUID format or a
16-byte binary to a UUID in its canonical, human-readable UUID format.

If `uuid` is neither of these, `:error` will be returned.

Since both binaries and strings are represented as binaries, this means some
strings you may not expect are actually also valid UUIDs in their binary form
and so will be casted into their string form.

If you need further-restricted behavior or validation, you should define your
own custom `Ecto.Type`. There is also `Ecto.UUID.load/1` if you only want to
process `raw` UUIDs, which may be a more suitable reverse operation to
`Ecto.UUID.dump/1`.

## Examples

    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!`

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

Same as `cast/1` but raises `Ecto.CastError` on invalid arguments.

# `dump`

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

Converts a string representing a UUID into a raw binary.

# `dump!`

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

Same as `dump/1` but raises `Ecto.ArgumentError` on invalid arguments.

# `embed_as`

# `equal?`

# `generate`

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

Generates a UUID string.

## Options

 * `:version` - The UUID version to generate. Supported values are `4` (random)
   and `7` (time-ordered). Defaults to `4`.

## Options (version 7 only)

 * `:precision` - The timestamp precision for version 7 UUIDs. Supported
   values are `:millisecond` and `:monotonic`. Defaults to `:millisecond`.

> #### Monotonic precision {: .info}
>
> When using `:monotonic`, sub-millisecond precision is encoded in the
> `rand_a` field. The generated version 7 UUIDs are strictly monotonically
> increasing (per node), even when multiple UUIDs are generated within the same
> timestamp. This is useful for maintaining insertion order in databases.

## Examples

    > 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`

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

Converts a binary UUID into a string.

# `load!`

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

Same as `load/1` but raises `Ecto.ArgumentError` on invalid arguments.

---

*Consult [api-reference.md](api-reference.md) for complete listing*