Apollo Federation @key directive: missing key selection priority constraint

Question

Entity key resolution ambiguityApollo Federation allows entities to define multiple @key directives, each declaring a different set of fields that can uniquely identify an entity across subgraphs. The gateway's query planner chooses which key to use based on the fields requested in the incoming operation, but the selection algorithm lacks a documented priority order or configurable constraint.Operational impactWithout a guaranteed selection order, the same query can produce different query plans across gateway versions or even between planning cycles. This non-determinism complicates performance tuning, as subgraph authors cannot enforce the use of a more efficient key—such as one backed by a database index—over a less optimal alternative. Workarounds like restricting entities to a single key or adding @provides/@requires directives increase schema complexity without addressing the root constraint gap.Can the Federation specification define a deterministic key selection priority? Is there a mechanism for subgraph authors to declare a preferred key for a given query pattern? Will future gateway releases expose a configuration option to control this behavior?

Tasadduq Burney · Answer

Answer to the Core Question
No. The Federation 2 specification does not define a deterministic priority order among multiple @key directives on one entity. The Apollo Router planner picks a key based on the fields requested in the operation and which subgraphs can resolve the entity, but that choice is an internal implementation detail, not a published contract. Subgraph authors cannot declare a preferred key for a query pattern, and no documented router configuration forces a specific key.
Confirmed Facts and Likely Explanation
Confirmed: Federation permits multiple @key directives per entity. The planner may choose any key that satisfies the requested fields, and behavior can shift between router releases even with an unchanged schema.
Likely explanation: The planner targets plan validity and field coverage, not index-backed lookup speed. Because the algorithm is internal, it is not guaranteed to prefer a database-indexed key over a less efficient alternative.
Steps for This Case

Confirm you run Apollo Router with Federation 2, not legacy Apollo Gateway. Check apollo router --version and the composed schema's federation target.
Enable router query-planning trace for a representative operation and inspect the _entities representation to see which key fields go to which subgraph.
If one index-backed key must win, remove the other @key directives from the entity, redeploy, and compare the plan and latency.
If multiple keys must stay, use @requires and @provides to shape resolution, or move the indexed lookup into the entity resolver so the planner does not control the lookup path.

Future Releases
Apollo has not announced a public key-priority configuration toggle. Future router releases may add planning knobs, but none are documented in current stable releases. Review router release notes before upgrading.
Missing Diagnostic Detail
Whether you use Apollo Router or legacy Apollo Gateway changes the applicable behavior. Confirm your gateway implementation and Federation version before applying these steps.

Apollo Federation @key directive: missing key selection priority constraint

Entity key resolution ambiguity

Operational impact

1 answer

Answer to the Core Question

Confirmed Facts and Likely Explanation

Steps for This Case

Future Releases

Missing Diagnostic Detail

Your perspective belongs here.

0 question comments