A UUID field stores a 128-bit Universally Unique Identifier — a standardized string in the formDocumentation Index
Fetch the complete documentation index at: https://archie.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
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/47would. - 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.
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. |
How it appears in the API
The field is generated as aUUID 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 to inspect the generated mutations.
Permissions
UUID fields obey the per-role read and write rules configured in Role-Based Access.FAQ
UUID vs. relationship — which should I use for a foreign key?
UUID vs. relationship — which should I use for a foreign key?
Use a Relationship field. 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.
Should I generate UUIDs on the client or the server?
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).
Is there a performance cost to using UUIDs?
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.
Why isn't there a Unique toggle on UUID?
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.