Skip to content
KeystoneJS LogoKeystoneJS (α)

Uuid

The Uuid field type stores Universally Unique Identifiers (UUIDs). UUIDs are 128-bit numbers but they're often represented in hexadecimal using the format 00000000-0000-0000-0000-000000000000. Here we refer to this encoding as the 8-4-4-4-12 hex format.

The encoding used for storage differs by DB adaptor, see the Storage section.

Usage

keystone.createList('Products', {
  fields: {
    name: { type: Text },
    supplierId: { type: Uuid, caseTo: 'upper' },
    // ...
  },
});

Config

OptionTypeDefaultDescription
caseToString'lower'Force the hex representation of IDs to upper or lower case when being read or written. Valid values: 'lower', 'upper' or null for no conversion. Defaults to 'lower' as per RFC 4122. See also: Casing.
isRequiredBooleanfalseDoes this field require a value?
isUniqueBooleanfalseAdds a unique index that allows only unique values to be stored

GraphQL

Uuid fields use the ID type in GraphQL.

Input Fields

Field nameTypeDescription
${path}IDUUID in the 8-4-4-4-12 hex format

Output Fields

Field nameTypeDescription
${path}IDUUID in the 8-4-4-4-12 hex format

Filters

Since Uuid fields encode IDs, "text" filters (eg. contains, starts_with, etc) have been excluded. Note also that hexadecimal encoding, as used for UUIDs, is case agnostic. As such, despite the GraphQL ID type being encoded as Strings, all Uuid filters are effectively case insensitive. See the the Casing section.

Field nameTypeDescription
${path}IDExact match to the ID provided
${path}_notIDNot an exact match to the ID provided
${path}_in[ID]In the array of IDs provided
${path}_not_in[ID]Not in the array of IDs provided

Storage

Mongoose Adaptor

When storing UUIDs, Mongo recommends BSON objects are used. The BSON spec indicates subtype 0x04 specifically. However most tools (including GraphQL) expect IDs to be encoded as strings and, for UUIDs, specifically expect the 8-4-4-4-12 hex format. Mongoose has no native support for UUIDs and storing them as BSON requires they be manually converted between these formats when being used. As such this field type does not currently follow the BSON recommendation; instead, the UUID values are stored as Strings.

This is not ideal (PRs welcome). In additional to not being inefficiently stored, working with UUIDs as Strings potentially causes problems with casing. See the Casing section.

Knex Adaptor

The Knex adaptor uses the Knex uuid type:

.. this uses the built-in uuid type in PostgreSQL, and falling back to a char(36) in other databases.

The PostgreSQL uuid type is a proper binary representation of the value. UUIDs in the text/hex format are implicitly cast to the uuid type when required so inserts, comparisons, etc. work as intended.

Other databases, such as MySQL do not have a dedicated UUID type.

Casing

Unless you're on Postgres or MS SQL Server, your DB platform probably doesn't have native support for a UUIDs type. A string type like varchar(36) or String will be used instead with values being stored is their 8-4-4-4-12 hex format. This can cause problems with casing.

Hexadecial itself is case agnostic. The hex value AF3D is identical to the hex value af3d; they both encode the same value as 44861 in decimal and 1010111100111101 in binary. However, in JavaScript, Mongo and (depending on your configuration) some other DB platforms, the String 'AF3D' does not equal the string 'af3d'.

For this field type, we mitigate this problem using the caseTo config option. This can be used to force the case of your values (to upper or lower case) whenever they're read, written or compared. This defaults to 'lower' as per the UUID spec.

Have you found a mistake, something that is missing, or could be improved on this page? Please edit the Markdown file on GitHub and submit a PR with your changes.

Edit Page