diff --git a/docs/source/entities-advanced.mdx b/docs/source/entities-advanced.mdx index 2dbf14cfe..7debc595e 100644 --- a/docs/source/entities-advanced.mdx +++ b/docs/source/entities-advanced.mdx @@ -21,7 +21,7 @@ type User @key(fields: "username domain") { #### Nested fields in compound `@key`s -Compound keys can also include _nested_ fields. In the following example, the `User` entity's primary key consists of both a user's `id` _and_ the `id` of that user's associated `Organization`: +Compound keys can also include _nested_ fields. In the following example, the `User` entity's `@key` consists of both a user's `id` _and_ the `id` of that user's associated `Organization`: ```graphql {1} title="Users subgraph" type User @key(fields: "id organization { id }") { diff --git a/docs/source/entities.mdx b/docs/source/entities.mdx index 1e70d07ed..700ab5fc2 100644 --- a/docs/source/entities.mdx +++ b/docs/source/entities.mdx @@ -53,10 +53,12 @@ type Product @key(fields: "id") { } ``` -The `@key` directive defines the entity's **primary key**, which consists of one or more of the type's `fields`. In the example above, the `Product` entity's primary key is its `id` field. **Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your router to associate field data from _different_ subgraphs with the _same_ entity instance. +The `@key` directive defines an entity's **unique key**, which consists of one or more of the type's `fields`. In the example above, the `Product` entity's unique key is its `id` field. **Every instance of an entity must be uniquely identifiable by its `@key` fields.** This is what enables your router to associate field data from _different_ subgraphs with the _same_ entity instance. In most cases, the `@key` field(s) for the same entity will be the same across subgraphs. For example, if one subgraph uses `id` as the `@key` field for the `Product` entity, other subgraphs should do the same. However, this [isn't strictly required](./entities-advanced#differing-keys-across-subgraphs). +> If coming from a database context, it can be helpful to think of a `@key` as an entity's [primary key](https://en.wikipedia.org/wiki/Primary_key). This term isn't completely accurate for entities since a single entity can have [multiple `@key`s](./entities-advanced#multiple-keys). The field(s) you select for an entity's `@key` must, however, uniquely identify the entity. In that way, `@key`s are similar to [candidate keys](https://en.wikipedia.org/wiki/Candidate_key). + ```graphql title="Products subgraph" @@ -87,7 +89,7 @@ For more information on advanced key options, like how to define [multiple keys] ### 2. Define a reference resolver -The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its primary key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity. +The `@key` directive effectively tells the router, "This subgraph can resolve an instance of this entity if you provide its unique key." In order for this to be true, the subgraph needs to define a **reference resolver** for the entity. > ⚠️ **This section describes how to create reference resolvers in Apollo Server.** If you're using another [subgraph-compatible library](./building-supergraphs/supported-subgraphs/), see its documentation for creating reference resolvers (or the equivalent functionality). diff --git a/docs/source/federated-types/federated-directives.mdx b/docs/source/federated-types/federated-directives.mdx index 0ac36afe9..6b6d6378a 100644 --- a/docs/source/federated-types/federated-directives.mdx +++ b/docs/source/federated-types/federated-directives.mdx @@ -27,10 +27,10 @@ If an imported directive's default name matches one of your own custom directive ```graphql extend schema @link(url: "https://specs.apollo.dev/federation/v2.3", - import: [{ name: "@key", as: "@primaryKey"}, "@shareable"]) + import: [{ name: "@key", as: "@uniqueKey"}, "@shareable"]) ``` -This example subgraph schema uses `@primaryKey` for the federated directive usually named [`@key`](#key). +This example subgraph schema uses `@uniqueKey` for the federated directive usually named [`@key`](#key). ### Namespaced directives @@ -134,7 +134,7 @@ To check whether your subgraph library supports repeatable directives, see the ` -**Required.** A GraphQL selection set (provided as a string) of fields and subfields that contribute to the entity's primary key. +**Required.** A GraphQL selection set (provided as a string) of fields and subfields that contribute to the entity's unique key. Examples: diff --git a/docs/source/migrating-from-stitching.md b/docs/source/migrating-from-stitching.md index ac289b7b4..4f392dfa5 100644 --- a/docs/source/migrating-from-stitching.md +++ b/docs/source/migrating-from-stitching.md @@ -122,7 +122,7 @@ resolvers: { This resolver calls `Query.user` on the `userSchema` to look up a `User`. It adds that user to the `Reservation.user` field that was previously defined at the gateway. This code can all remain. You don't need to remove it from the stitched gateway. In fact, if you did that, the stitched gateway would break. -On the other hand, a _federated_ architecture defines its resolvers at the subgraph level. These resolvers rely on **entities**, which are identified by a primary key. For example, the Reservation subgraph must define the `Reservation` type as an entity to allow other subgraphs to extend it. These other subgraphs use the `Reservation`'s `@key` fields to uniquely identify a given instance: +On the other hand, a _federated_ architecture defines its resolvers at the subgraph level. These resolvers rely on **entities**, which are identified by a unique key. For example, the Reservation subgraph must define the `Reservation` type as an entity to allow other subgraphs to extend it. These other subgraphs use the `Reservation`'s `@key` fields to uniquely identify a given instance: ```graphql type Reservation @key(fields: "id") {