> ## Documentation Index
> Fetch the complete documentation index at: https://archie.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UUID field

> UUID fields store 128-bit unique identifiers. Globally unique, hard to guess, and safe to expose in URLs.

A UUID field stores a 128-bit Universally Unique Identifier — a standardized string in the form `123e4567-e89b-12d3-a456-426614174000`. UUIDs are guaranteed to be unique across systems, databases, and servers without any central coordination, which makes them the right choice for identifiers that travel outside your database.

## When to use UUIDs

* **Public-facing identifiers in URLs** — `/orders/123e4567-...` reveals nothing about the order's age or volume the way `/orders/47` would.
* **Distributed identifiers** — IDs generated on the client or in another system that need to be unique when merged.
* **Tokens** — invite tokens, share links, password reset tokens.
* **External references** — IDs that must be unique across multiple workspaces or environments.

If you just need an integer primary key for a single table, the auto-generated `id` column is enough. Reach for UUID when the ID needs to be globally unique or hard to guess.

## Configuration options

| Option            | Description                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Name**          | The system identifier used in the GraphQL and REST APIs (for example `transaction_id`, `invite_token`).                          |
| **Description**   | An optional internal note explaining the field's purpose.                                                                        |
| **Default Value** | An optional specific UUID string. Usually left blank — UUIDs are typically generated by the application or API at creation time. |
| **Mandatory**     | If on, the record cannot be saved without a valid UUID.                                                                          |

<img src="https://mintcdn.com/archie-e998dbf6/GdaYz5W-YpQoJXsQ/features/backend/data-model/field-type-uuid.png?fit=max&auto=format&n=GdaYz5W-YpQoJXsQ&q=85&s=48520c6143b6f41b6907c09b9f39a862" alt="UUID field type configuration" width="1866" height="1022" data-path="features/backend/data-model/field-type-uuid.png" />

## How it appears in the API

The field is generated as a `UUID` scalar (or `String` in stacks that don't have a dedicated UUID scalar) in GraphQL, and as a string in JSON. Validation of the UUID format runs on insert and update. See the [GraphQL API Explorer](/features/backend/graphql-api-explorer/overview) to inspect the generated mutations.

## Permissions

UUID fields obey the per-role read and write rules configured in [Role-Based Access](/features/backend/app-services/role-based-access).

## FAQ

<AccordionGroup>
  <Accordion title="UUID vs. relationship — which should I use for a foreign key?">
    Use a [Relationship field](/features/backend/data-model/fields/relationship). It enforces referential integrity, generates the inverse query in GraphQL, and visually links the two tables. UUID is for free-form identifiers that aren't tied to a specific Archie table.
  </Accordion>

  <Accordion title="Should I generate UUIDs on the client or the server?">
    Either works. Server-side generation is the default — leave **Default Value** blank and let the API assign the UUID on insert. Client-side generation is useful when you need to know the ID before the record is saved (for offline-first apps or correlation across systems).
  </Accordion>

  <Accordion title="Is there a performance cost to using UUIDs?">
    UUIDs are 16 bytes vs. 4 bytes for a standard integer ID, so indexes are slightly larger. The trade-off is rarely meaningful at typical scales, and it's almost always worth it for IDs you expose externally.
  </Accordion>

  <Accordion title="Why isn't there a Unique toggle on UUID?">
    UUIDs are designed to be unique by construction — collisions are statistically negligible. If you need a strict database-level constraint, use the auto-generated primary key on the table or add a unique [index](/features/backend/data-model/indexes).
  </Accordion>
</AccordionGroup>