Unique constraints

This tutorial assumes that you have successfully completed the Get started with GraphQL tutorial, and that you still have the FaunaDB Console open in a browser tab/window, on the GraphQL Playground screen.

If your FaunaDB Console session has expired:

Log in again.
Select the graphql database.
Click the GRAPHQL button in the left navigation.

This tutorial explores the @unique directive, which allows you to add constraints to your GraphQL schema. When you add @unique to a field definition, FaunaDB handles the creation of an index that enforces this constraint.

Let’s define a simple user type, with a uniqueness constraint on the username, and see what happens when the constraint is triggered. The steps:

Create a new schema file
Import the new GraphQL schema into FaunaDB
Inspect the constraint
Add a user
Add a duplicate user

Create a new schema file

Create the file schema-unique.gql with the following content (or download it here):
```
type User {
  username: String! @unique
}
```
Import the new GraphQL schema into FaunaDB

Click the UPDATE SCHEMA button in the GraphQL Playground screen (in your browser), which opens your browser’s file selector. Select the schema-unique.gql file, and click the file selector’s Open button.

This new schema only updates collections (and associated indexes) with the same name. Any other collections are unaffected.

Inspect the constraint

Let’s inspect the constraint via FaunaDB Shell.

Open a terminal and run:

fauna shell graphql

After Shell starts, run the following query:

Get(Index("unique_User_username"))

You should see output similar to:

{ ref: Index("unique_User_username"),
  ts: 1559780318060000,
  active: true,
  partitions: 1,
  name: 'unique_User_username',
  source: Collection("User"),
  data: { gql: { ts: Time("2019-06-06T00:18:37.979330Z") } },
  values: [],
  terms: [ { field: [ 'data', 'username' ] } ],
  unique: true }

The unique field in the result is set to true, and the terms specify which field(s) need to be unique, i.e. data/username.

Add a user

Copy the following GraphQL query:
```
mutation CreateAUser {
   createUser(data: {
     username: "Alice"
   }) {
     username
   }
}
```
Then click the "new tab" + button on the GraphQL Playground screen in your browser (at the top left, just right of the last query tab). Paste the query into the left panel, and click the "Play" button. The query should execute and the response should appear in the right panel:
```
{
  "data": {
    "createUser": {
      "username": "Alice"
    }
  }
}
```
Add a duplicate user

Let’s see what happens when a duplicate user is added. Simply click the "Play" button a second time. The query should execute, and an error response should appear in the right panel:
```
{
  "errors": [
    {
      "message": "Document is not unique.",
      "extensions": {
        "code": "document not unique"
      }
    }
  ]
}
```

Conclusion

This tutorial has demonstrated that the @unique directive can be used to apply a uniqueness constraint to a field in your GraphQL schema.

For more information, see the @unique reference.

Next steps

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!