Unique constraints definition

Unique constraints are defined on the Collection document definition in the constraints field. This field takes an array of unique constraints and has the following form:

constraints: [
  {
    unique: [
      "<fieldName>", ...
    ],
    status: "<status>",
  },
  ...
]

When one or more fields are part of a unique constraint, multiple documents cannot have the same combination of values for the constrained fields.

Constraints aren’t applied retroactively to existing documents but are applied only when a new document is created or an existing document is updated.

You can declare any number of constraints that define which Document field values must be unique in a Collection. A unique constraint can define one or more fields that must be unique in combination. For example, if firstName and lastName fields are included in a unique definition, the first and last name combination must be unique in the collection.

If you create a unique constraint over more than one field, the absence of one or more fields with the presence of other fields in the unique constraint is a combination that the constraint is enforced over. In the firstName / lastName example, if you create a user with only a lastName, you can’t create another user with only that lastName, but you could if you add a firstName.

Constraints definition fields

Property Type Description

unique

Array

Array of document field names that are constrained to unique values. All defined fields are considered when validating create and update requests against constrained fields.

status

String

(read-only) Constraint status:
active = Constraint is active, and a document can’t be added that conflicts with another document in the collection.
pending = Constraint isn’t yet active. If a constraint is added to a large collection, it takes time to account for existing documents, after which status transitions to active.

Examples

Basic unique constraints example

  1. Given a collection definition:

    Hello.definition
    {
  name: "Hello",
  coll: Collection,
  ts: Time("2023-03-28T20:28:05.490Z"),
  indexes: {},
  constraints: [],
}

  2. Create a unique constraint:+

    Hello.definition.update({
  constraints: [
    { unique: [ "what" ] }
  ]
})
    {
  name: "Hello",
  coll: Collection,
  ts: Time("2023-03-28T20:28:05.490Z"),
  indexes: {},
  constraints: [
    {
      unique: [
        "what",
      ],
      status: "active",
    },
  ],
}

  3. Create a document and populate it with the constrained field. The document is created successfully:

    Hello.create({ what: "greeting" })
    {
  id: "360475803255832609",
  coll: Hello,
  ts: Time("2023-03-28T20:29:25.260Z"),
  what: "greeting",
}

  4. Create another document and try to populate it with the same value for the constrained field. The create fails because the constrained field already has the same value:

    Hello.create({ what: "greeting" })
    Error: constraint_failure

Failed unique constraint.

error: Failed unique constraint.
constraint failures:
  what: Failed unique constraint
at *query*:1:13
  |
1 | Hello.create({ what: "greeting" })
  |             ^^^^^^^^^^^^^^^^^^^^^^
  |

 

Compound and multiple unique constraints example

This example shows how to declare multiple unique constraints and constraints on a combination of values.

  1. Given documents that have the shape of the following example:

    {
  id: "372518393394233409",
  coll: Customer,
  ts: Time("2023-08-08T18:41:14.200Z"),
  name: {
    first: "Kilgore",
    last: "Trout"
  },
  username: "ktrout"
}

  2. Define two unique constraints, with one of the constraints requiring that the first and last names in combination are unique:

    Customer.definition.update( { constraints: [ { unique: [ "name.first", "name.last" ] }, { unique: "username" } ] })
    {
  name: "Customer",
  coll: Collection,
  ts: Time("2023-08-08T20:08:36.240Z"),
  constraints: [
    {
      unique: [
        "username"
      ],
      status: "active"
    },
    {
      unique: [
        "name.first",
        "name.last"
      ],
      status: "active"
    }
  ],
  history_days: 0,
  indexes: {}
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!