Entities, Keys, and Entity Resolution

The Reference Problem

The reviews team wants product names on every review card. They do not own the product table, they cannot query the catalog database directly, and duplicating name into their service guarantees the two copies drift apart within a sprint. Federation's answer is an entity: a type that several subgraphs contribute fields to, identified by a key all of them declare.

# subgraph: catalog
type Product @key(fields: "id") {
  id: ID!
  name: String!
  priceCents: Int!
}
type Query { product(id: ID!): Product }

# subgraph: reviews
type Product @key(fields: "id") {
  id: ID!                       # the key must exist here too — it is the lookup handle
  reviews: [Review!]!
}
type Review { id: ID! rating: Int! body: String! }

Read @key(fields: "id") as a contract: identity of a Product is its id, and every subgraph that contributes fields agrees on that. The gateway uses the contract to move between subgraphs. When the plan needs reviews for a product the catalog subgraph just returned, it hands reviews an entity representation — a stripped object carrying only the type name and the key fields:

{ "__typename": "Product", "id": "p1" }

Everything else in that payload is noise the gateway already knows or will fetch later. Two rules follow. First, every subgraph contributing fields to the entity must declare the same key definition, or the gateway has no agreed identity to translate on. Second, in Federation 2 you no longer write extend type Product; a plain type Product @key(...) in each subgraph is the normal form, and key fields are implicitly shareable so you do not mark them @external.

Entity Resolvers and the _entities Round Trip

The gateway does not invent a new protocol for hops. It sends the receiving subgraph a generated operation against the spec's _entities field:

query ($representations: [_Any!]!) {
  _entities(representations: $representations) {
    ... on Product { id reviews { rating } }
  }
}

Your subgraph answers by implementing a reference resolver for each entity type — __resolveReference in Apollo Server and most federation libraries. The minimal version returns an object with just the key:

const resolvers = {
  Product: {
    __resolveReference(ref) {
      // The gateway only asked for fields this subgraph owns; the key is enough
      // to attach them, so no database read is required for pure references.
      return { id: ref.id };
    },
  },
};

When the entity needs real data, one representation means one lookup and fifty representations mean fifty lookups unless you batch them:

const productLoader = new DataLoader(async (ids) => {
  const rows = await db.product.findMany({ where: { id: { in: ids } } });
  const byId = new Map(rows.map((r) => [r.id, r]));
  // DataLoader demands one slot per requested key, in the same order.
  // Unknown ids become null, which the gateway turns into a null field.
  return ids.map((id) => byId.get(id) ?? null);
});

Product: { __resolveReference: (ref) => productLoader.load(ref.id) },

Two details decide whether this works in production. Order matters: the gateway zips representations to results positionally, so a resolver that returns a filtered list silently attaches one product's reviews to another. Batching is per round trip: the gateway coalesces every representation for the same subgraph and type into a single _entities call, and DataLoader then coalesces the individual __resolveReference calls inside that tick into one SQL IN query. A 40-item product list therefore costs one database round trip, not forty — this is the same anti-N-plus-one machinery you would build by hand, wired into the plan.

Composite Keys, Key Drift, and @requires/@provides

Not every type has a globally unique column. Multi-tenant tables key on tenant plus natural id, event stores key on stream plus offset. Federation takes a field set, so the key can be a tuple:

type Shipment @key(fields: "tenantId trackingNumber") {
  tenantId: ID!
  trackingNumber: String!
  status: String!
}

The representation becomes { "__typename": "Shipment", "tenantId": "acme", "trackingNumber": "1Z999" }, and the resolver must look up on both columns — a resolver that reads only trackingNumber will happily return another tenant's shipment. Several @key directives on one type are legal and useful during migrations: declare the old key and the new key side by side, roll the new key out to every subgraph, then remove the old one.

Key drift is the slow failure. If catalog keys Product on id and inventory keys it on sku, the gateway can translate neither direction, and the mistake usually surfaces as an unsatisfiable composition error or, worse, as a null branch at runtime. The discipline: when you add a field to an entity, every subgraph that contributes fields to that entity declares the identical key field set in the same release.

Two directives shave hops off a plan, and both are easy to misuse:

A common design smell: marking a field @external "just in case". Externals that no directive consumes are dead weight that hides true ownership. Declare the field where it is resolved, reference it through @requires or @provides only when a measured plan needs it, and let composition reject the leftovers.