Introduction to Entities

Federated schemas let multiple subgraphs collaboratively define and resolve fields for shared object types. This guide shows you how to define a shared object type called an entity.

Before you get started, you may want to check out the Introduction to Apollo Federation for a conceptual overview.

Entity overview

Entities are a fundamental aspect of federated schemas. In a supergraph, an entity is an object type that can resolve its fields across multiple subgraphs. Each subgraph can contribute different fields to the entity and is responsible for resolving only the fields that it contributes. This enables subgraphs to adhere to the separation of concerns principle.

For example, this Product entity's fields are defined and resolved across two subgraphs:

1type Product @key(fields: "upc") {
2  upc: ID!
3  name: String!
4  price: Int
5}

1type Product @key(fields: "productUpc") {
2  productUpc: ID!
3  rating: Int!
4}

This guide goes over how to define entities in your subgraph schemas and code.

Defining an entity

To define an entity within a particular subgraph, you do the following:

1. Apply the @key directive to an object type.

2. Define the object type's reference resolver.

1. Define a @key

In a subgraph schema, you can designate any object type as an entity by adding the @key directive to its definition, like so:

1type Product @key(fields: "upc") {
2  upc: ID!
3  name: String!
4  price: Int
5}

The @key directive defines an entity's unique key, which consists of one or more of the type's fields. In the previous example, the Product entity's unique key is its upc field. Every instance of an entity must be uniquely identifiable by its @key field(s). Key fields' uniqueness enable your router to associate fields 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 upc as the @key field for the Product entity, other subgraphs should likely do the same. However, this isn't strictly required.

If coming from a database context, it can be helpful to think of a @key as an entity's primary key. This term isn't completely accurate for entities since a single entity can have multiple @keys. The field(s) you select for an entity's @key must, however, uniquely identify the entity. In that way, @keys are similar to candidate keys.

1type Product @key(fields: "upc") {
2  upc: ID!
3  name: String!
4  price: Int
5}

1type Product @key(fields: "productUpc") {
2  productUpc: ID!
3  inStock: Boolean!
4}

For more information on advanced key options, like defining multiple keys or compound keys, see the guide on Defining keys.

Key field limitations

An entity's @key cannot include:

• Fields that return a union or interface

• Fields that take arguments

Though not strictly required, it's best to use non-nullable fields for keys. If you use fields that return null values, GraphOS may encounter issues resolving the entity.

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 unique key." For this to be true, the subgraph must define a reference resolver for the entity.

For the Product entity defined above, the reference resolver might look like this:

1// Products subgraph
2const resolvers = {
3  Product: {
4    __resolveReference(productRepresentation) {
5      return fetchProductByID(productRepresentation.upc);
6    }
7  },
8  // ...other resolvers...
9}

Let's break this example down:

• You declare an entity's reference resolver in your resolver map, as a member of the entity's corresponding object.

• A reference resolver's name is always __resolveReference.

• A reference resolver's first parameter is a representation of the entity being resolved.

  • An entity representation is an object that contains the entity's @key fields, plus its __typename field. These values are automatically provided to your subgraph by your router.

• A reference resolver is responsible for returning all of the entity fields that this subgraph defines.

  • In this example, the hypothetical fetchProductByID function fetches a particular Product's field data based on its upc.

Every subgraph that contributes at least one unique field to an entity must define a reference resolver for that entity.

To learn more about __resolveReference in Apollo Server, see the API docs.

Next steps

Once you add your subgraphs to your supergraph, GraphOS composes them into a supergraph schema. Clients querying your supergraph can interact with entity fields without needing to know the details of which subgraphs contribute which fields.

To learn about more advanced ways of using entities, check out these guides:

• Define Advanced Keys, including compound and nested key fields

• Contribute and Reference Entity Fields, including computed fields