Entity overview

InApollo Federation, federated data objects are represented asentities. Entities are objects that can be fetched with one or more unique key fields. Like a row in a database table, anentity contains fields of various types, and it can be uniquely identified by a key field or set of fields.

Entities are defined insubgraph schemas. Eachsubgraph can contribute different fields to an entity it defines and is responsible forresolving it—returning only the fields that it contributes. This enables subgraphs to adhere to the separation of concerns principle.

Anentity type is anobject type that has beendefined as an entity. Because an entity is keyed, an entity type's definition must have a@keydirective. For example, thisProduct entity's fields are defined and resolved across two subgraphs:

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

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

The rest of 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'sreference 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:Int5}

The@key directive defines an entity'sunique key, which consists of one or more of the type'sfields.In the previous example, theProduct entity's unique key is itsupc field.Every instance of an entity must be uniquely identifiable by its@key field(s).Key fields' uniqueness enable yourrouter 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 usesupc as the@key field for theProduct entity, other subgraphs should likely do the same.However, thisisn't strictly required.

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

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

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

For more information on advanced key options, like definingmultiple keys orcompound keys, see the guide onDefining 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 returnnull 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 have areference resolver for the entity.

For theProduct entity definedabove, the reference resolver might look like this:

1// Products subgraph2const 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 yourresolver 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 hypotheticalfetchProductByID function fetches a particularProduct's field data based on itsupc.

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 theAPI docs.

Next steps

Once youadd your subgraphs to yoursupergraph, GraphOS composes them into asupergraph 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