From 68314372c684ad1462812e3d51c086f3e0a61730 Mon Sep 17 00:00:00 2001 From: Michel Diz Date: Fri, 26 Jul 2024 07:33:00 -0300 Subject: [PATCH] docs(graphql): Update id directive for interfaces (#209) (#382) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes DOC-275 Co-authored-by: Damián Parrino Co-authored-by: Abhimanyu Singh Gaur <12651351+abhimanyusinghgaur@users.noreply.github.com> Co-authored-by: rderbier --- content/graphql/schema/directives/ids.md | 31 +++++++++++++++++++++--- 1 file changed, 28 insertions(+), 3 deletions(-) diff --git a/content/graphql/schema/directives/ids.md b/content/graphql/schema/directives/ids.md index 22129e83..aeeeb13d 100644 --- a/content/graphql/schema/directives/ids.md +++ b/content/graphql/schema/directives/ids.md @@ -13,7 +13,7 @@ Dgraph provides two types of built-in identifiers: the `ID` scalar type and the * The `@id` directive is used for external identifiers, such as email addresses. -### The `@id` directive +## The `@id` directive For some types, you'll need a unique identifier set from outside Dgraph. A common example is a username. @@ -63,8 +63,33 @@ query { This will yield a positive response if both the `name` **and** `isbn` match any data in the database. +### `@id` and interfaces -### Combining `ID` and `@id` +By default, if used in an interface, the `@id` directive will ensure field uniqueness for each implementing type separately. +In this case, the `@id` field in the interface won't be unique for the interface but for each of its implementing types. +This allows two different types implementing the same interface to have the same value for the inherited `@id` field. + +There are scenarios where this behavior might not be desired, and you may want to constrain the `@id` field to be unique across all the implementing types. In that case, you can set the `interface` argument of the `@id` directive to `true`, and Dgraph will ensure that the field has unique values across all the implementing types of an interface. + +For example: + +```graphql +interface Item { + refID: Int! @id(interface: true) # if there is a Book with refID = 1, then there can't be a chair with that refID. + itemID: Int! @id # If there is a Book with itemID = 1, there can still be a Chair with the same itemID. +} + +type Book implements Item { ... } +type Chair implements Item { ... } +``` + +In the above example, `itemID` won't be present as an argument to the `getItem` query as it might return more than one `Item`. + +{{% notice "note" %}} +`get` queries generated for an interface will have only the `@id(interface: true)` fields as arguments. +{{% /notice %}} + +## Combining `ID` and `@id` You can use both the `ID` type and the `@id` directive on another field definition to have both a unique identifier and a generated identifier. @@ -84,7 +109,7 @@ With this schema, Dgraph requires a unique `username` when creating a new user. If in a type there are multiple `@id` fields, then in a `get` query these arguments will be optional. If in a type there's only one field defined with either `@id` or `ID`, then that will be a required field in the `get` query's arguments. {{% /notice %}} -