Docs
Launch GraphOS Studio
You're viewing documentation for a previous version of this software. Switch to the latest stable version.

Entities in Apollo Federation

Reference and extend types across subgraphs


In Apollo Federation, an entity is an that you define canonically in one and can then reference and extend in other s.

Entities are the core building block of a federated graph.

Defining entities

In a GraphQL , you can designate any as an entity by adding a @key to its definition, like so:

products
type Product @key(fields: "upc") {
upc: String!
name: String!
price: Int
}

Types besides s (such as unions and interfaces) cannot be entities.

The @key defines the entity's primary key, which consists of one or more of the type's fields. Like primary keys in other systems, an entity's primary key must uniquely identify a particular instance of that entity.

In the example above, the Product entity's primary key is its upc . The gateway uses an entity's primary key to match data from different s to the same object instance.

An entity's @key cannot include s that return a union or interface.

Multiple primary keys

You can define more than one primary key for an entity, when applicable.

In the following example, a Product entity can be uniquely identified by either its upc or its sku:

products
type Product @key(fields: "upc") @key(fields: "sku") {
upc: String!
sku: String!
price: String
}

This pattern is helpful when different s interact with different s of an entity. For example, a reviews might refer to products by their UPC, whereas an inventory might use SKUs.

Compound primary keys

A single primary key can consist of multiple s, and even nested fields.

The following example shows a primary key that consists of both a user's id and the id of that user's associated organization:

directory
type User @key(fields: "id organization { id }") {
id: ID!
organization: Organization!
}
type Organization {
id: ID!
}

Referencing entities

After you define an entity in one , other s can then reference that entity in their .

For example, let's say we have a products that defines the following Product entity:

products
type Product @key(fields: "upc") {
upc: String!
name: String!
price: Int
}

A reviews can then add a of type Product to its Review type, like so:

reviews
type Review {
score: Int!
product: Product!
}
# This is a required "stub" of the Product entity (see below)
extend type Product @key(fields: "upc") {
upc: String! @external
}

To reference an entity that originates in another , the reviews needs to define a stub of that entity to make its own valid. The stub includes just enough information for the to know how to uniquely identify a particular Product:

  • The extend keyword indicates that Product is an entity that's defined in another .
  • The @key indicates that Product uses the upc as its primary key. This value must match the value of exactly one @key defined in the entity's originating (even if the entity defines multiple primary keys).
  • The upc must be present because it's part of the specified @key. It also requires the @external to indicate that it originates in another .

This explicit syntax has several benefits:

  • It's standard GraphQL grammar.
  • It enables you to run the reviews standalone with a valid , including a Product type with a single upc .
  • It provides strong typing information that lets you catch mistakes at composition time.

Resolving entities

Let's say our reviews from Referencing entities defines the following Query type:

reviews
type Query {
latestReviews: [Review!]
}

That means the following query is valid against our federated graph:

query GetReviewsAndProducts {
latestReviews {
score
product {
upc
price # Not defined in reviews!
}
}
}

Now we have a problem: this query starts its execution in the reviews (where latestReviews is defined), but that doesn't know that Product entities have a price ! Remember, the reviews only knows about its stub s of Product.

Because of this, the gateway needs to fetch price from the products instead. But how does the gateway know which products it needs to fetch the prices for?

To solve this, we add a to each :

Entity representations

In our example, the reviews needs to define a for its stub version of the Product entity. The reviews doesn't know much about Products, but fortunately, it doesn't need to. All it needs to do is return data for the s it does know about, like so:

resolvers.js
// Reviews subgraph
const resolvers = {
Review: {
product(review) {
return {
__typename: "Product",
upc: review.upc
};
}
},
// ...
}

This 's return value is a representation of a Product entity (because it represents an entity from another ). A representation always consists of:

  • A __typename
  • Values for the entity's primary key s (upc in this example)

Because an entity can be uniquely identified by its primary key s, this is all the information the gateway needs to fetch additional fields for a Product object.

Reference resolvers

As a reminder, here's the example query we're executing across our s:

query GetReviewsAndProducts {
latestReviews {
score
product {
upc
price # Not defined in reviews!
}
}
}

The gateway knows it can't fetch Product.price from the reviews , so first it executes the following query on reviews:

query {
latestReviews {
score
product { # List of Product representations
__typename
upc
}
}
}

Notice that this query omits price but adds __typename, even though it wasn't in the original query string! This is because the gateway knows it needs all of the s in each Product's representation, including __typename.

With these representations available, the gateway can now execute a second query on the products to fetch each product's price. To support this special query, the products needs to define a reference resolver for the Product entity:

resolvers.js
// Products subgraph
const resolvers = {
Product: {
__resolveReference(reference) {
return fetchProductByUPC(reference.upc);
}
},
// ...
}

In the example above, fetchProductByUPC is a hypothetical function that fetches a Product's full details from a data store based on its upc.

A reference (always called __resolveReference) provides the gateway direct access to a particular entity's s, without needing to use a custom query to reach that entity. To use a reference , the gateway must provide a valid entity representation, which is why we created the in the reviews first!

To learn more about __resolveReference, see the API docs.

After fetching the price from products via a reference , the gateway can intelligently merge the data it obtained from its two queries into a single result and return that result to the querying client.

Extending entities

A can add s to an entity that's defined in another subgraph. This is called extending the entity.

When a extends an entity, the entity's originating is not aware of the added s. Only the extending (along with the gateway) knows about these s.

Each of an entity should be defined in exactly one . Otherwise, a composition error will occur.

Example #1

Let's say we want to add a reviews to the Product entity. This will return a list of reviews for the product. The Product entity originates in the products , but it makes more sense for the reviews to resolve this particular .

To handle this case, we can extend the Product entity in the reviews , like so:

reviews
extend type Product @key(fields: "upc") {
upc: String! @external
reviews: [Review]
}

This definition is nearly identical to the stub we defined for the Product type in Referencing entities. All we've added is the reviews . We don't include an @external , because this does originate in the reviews .

Whenever a extends an entity with a new , it's also responsible for resolving that . The gateway is automatically aware of this responsibility. In our example:

  1. The gateway first fetches the upc for each Product from the products .
  2. The gateway then passes those upc values to the reviews , where you can access them on the object passed to your Product.reviews :
{
Product: {
reviews(product) {
return fetchReviewsForProduct(product.upc);
}
}
}

Example #2

Let's say we want to be able to query for the inStock status of a product. That information lives in an inventory , so we'll add the type extension there:

inventory
extend type Product @key(fields: "upc") {
upc: ID! @external
inStock: Boolean
}
{
Product: {
inStock(product): {
return fetchInStockStatusForProduct(product.upc);
}
}
}

Similar to the previous example, the gateway fetches the required upc from the products and passes it to the inventory , even if the query didn't ask for the upc:

# This query fetches upc from the products subgraph even though
# it isn't a requested field. Otherwise, the inventory subgraph
# can't know which products to return the inStock status for.
query GetTopProductAvailability {
topProducts {
name
inStock
}
}

The Query and Mutation types

In Apollo Federation, the Query and Mutation base types originate in the graph composition itself and all of your s are automatically treated as extending these types to add the s they support without explicitly adding the extends keyword.

For example, the products might extend the root Query type to add a topProducts query, like so:

products
type Query {
topProducts(first: Int = 5): [Product]
}

Migrating entities and fields (advanced)

As your federated graph grows, you might decide that you want an entity (or a particular of an entity) to originate in a different . This section describes how to perform these migrations.

Entity migration

Let's say our Payments defines a Bill entity:

# Payments subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
}
type Payment {
# ...
}

Then, we add a dedicated Billing to our federated graph. It now makes sense for the Bill entity to originate in the Billing instead. When we're done migrating, we want our deployed subgraph s to look like this:

# Payments subgraph
type Payment {
# ...
}
# Billing subgraph
type Bill @key(fields: "id") {
id: ID!
amount: Int!
}

The exact steps depend on how you perform composition:

Field migration

The steps for migrating an individual are nearly identical in form to the steps for migrating an entire entity.

Let's say our Products defines a Product entity, which includes the boolean inStock:

# Products subgraph
type Product @key(fields: "id") {
id: ID!
inStock: Boolean!
}

Then, we add an Inventory to our federated graph. It now makes sense for the inStock to originate in the Inventory instead, like this:

# Products subgraph
type Product @key(fields: "id") {
id: ID!
}
# Inventory subgraph
extend type Product @key(fields: "id") {
id: ID! @external
inStock: Boolean!
}

We can perform this migration with the following steps (additional commentary on each step is provided in Entity migration):

  1. In the Inventory 's , extend the Product entity to add the inStock :

    # Products subgraph
    type Product @key(fields: "id") {
    id: ID!
    inStock: Boolean!
    }
    # Inventory subgraph
    extend type Product @key(fields: "id") {
    id: ID! @external
    inStock: Boolean!
    }
    • If you're using managed federation, register this change with Apollo.
  2. In the Inventory , add a for the inStock . This should resolve the field with the exact same logic as the in the Products subgraph.

  3. Deploy the updated Inventory to your environment.

  4. In the Products 's , remove the inStock and its associated :

    # Products subgraph
    type Product @key(fields: "id") {
    id: ID!
    }
    # Inventory subgraph
    extend type Product @key(fields: "id") {
    id: ID! @external
    inStock: Boolean!
    }
    • If you're using managed federation, register this change with Studio.
  5. If you're using Rover composition, compose a new . Deploy a new version of your gateway that uses the updated schema.

    • Skip this step if you're using managed federation.
  6. Deploy the updated Products to your environment.

Extending an entity with computed fields (advanced)

When you extend an entity, you can define s that depend on fields in the entity's originating . For example, a shipping might extend the Product entity with a shippingEstimate , which is calculated based on the product's size and weight:

shipping
extend type Product @key(fields: "sku") {
sku: ID! @external
size: Int @external
weight: Int @external
shippingEstimate: String @requires(fields: "size weight")
}

As shown, you use the @requires to indicate which s (and subfields) from the entity's originating are required.

You cannot require s that are defined in a besides the entity's originating subgraph.

In the above example, if a client requests a product's shippingEstimate, the gateway will first obtain the product's size and weight from the products , then pass those values to the shipping . This enables you to access those values directly from your :

{
Product: {
shippingEstimate(product) {
return computeShippingEstimate(product.sku, product.size, product.weight);
}
}
}

Using @requires with object subfields

If a computed @requires a that returns an , you also specify which subfields of that object are required. You list those subs with the following syntax:

shipping
extend type Product @key(fields: "sku") {
sku: ID! @external
dimensions: ProductDimensions @external
shippingEstimate: String @requires(fields: "dimensions { size weight }")
}

In this modification of the previous example, size and weight are now subs of a ProductDimensions object. Note that the ProductDimensions object must be defined in both the entity's extending and its originating , either as an entity or as a value type.

Resolving another subgraph's field (advanced)

Sometimes, multiple s are capable of resolving a particular for an entity, because all of those subgraphs have access to a particular data store. For example, an inventory and a products might both have access to the database that stores all product-related data.

When you extend an entity in this case, you can specify that the extending @provides the , like so:

inventory
type InStockCount {
product: Product! @provides(fields: "name price")
quantity: Int!
}
extend type Product @key(fields: "sku") {
sku: String! @external
name: String @external
price: Int @external
}

This is a completely optional optimization. When the gateway plans a query's execution, it looks at which s are available from each . It can then attempt to optimize performance by executing the query across the fewest subgraphs needed to access all required fields.

Keep the following in mind when using the @provides :

  • Each that @provides a must also define a for that field. That resolver's behavior must match the behavior of the resolver in the field's originating subgraph.
  • When an entity's can be fetched from multiple s, there is no guarantee as to which will resolve that for a particular query.
  • If a @provides a , it must still list that field as @external, because the originates in another .
Previous
The gateway
Next
Reusing types (value types)
Edit on GitHubEditForumsDiscord