Field Aliases for Renaming

The Response-Key Collision

You need two users in one round trip — the entire point of GraphQL — so you write:

query Both {
  user(id: "1") { name }
  user(id: "2") { name }
}

The server answers before executing anything:

Fields "user" conflict because "id" arguments differ.
Use different aliases on fields to fetch both.

Inside one selection set every response key must be unique, and the default response key is the field's name. Two selections named user with different arguments are two different answers competing for a single slot in data, so the document fails validation rather than guessing which one wins.

An alias renames the response key without touching the schema:

query Both {
  viewer: user(id: "1") { name }
  target: user(id: "2") { name }
}

{ "data": { "viewer": { "name": "Ada" }, "target": { "name": "Grace" } } }

The schema still exposes one user field with one id argument. The caller simply asked for it twice under two names — no server change, no new field, no version bump.

Note what an alias is not: an argument. user(id: "1") and user(id: "2") still differ at the argument level; the alias only stops them from colliding in the response. When two selections use the same field and the same arguments, they merge instead, which is why duplicating an identical selection is legal (and pointless).

Aliases also decide what client code binds to. recentPosts as a response key documents intent in the JSON, where a bare posts forces every reader to inspect the arguments to learn which list they are holding. GraphQL drew this line deliberately: field names belong to the schema and must stay stable for every client, while response keys belong to the document and can vary per consumer with no negotiation, no versioning, and no server deploy.

Mapping Aliases to Response Keys

The alias becomes the key in data at every level where you use one:

query Dashboard {
  recent: posts(limit: 3, orderBy: NEWEST) { title }
  popular: posts(limit: 3, orderBy: TOP) { title }
  me {
    displayName: name
    inbox: messages(filter: UNREAD) { subject }
  }
}

Rules worth memorising:

• An alias renames the result, never the field. Resolvers still run against posts and messages; field names, types, and deprecations stay exactly as the schema declares them.
• Aliases compose with variables. recent: posts(limit: $n) is legal — the alias is fixed in the document while the value arrives separately. See query variables for how $n is delivered and validated.
• You cannot alias a fragment spread. ...Card: user is not syntax. To rename a spread selection, put the fragment on a field: viewer: user { ...UserCard } — the alias lands on user, the fragment's fields merge underneath it.
• Two aliases with identical arguments are legal but wasteful. The resolver executes twice for identical data; nothing merges them because their response keys differ.

The merge rule covers every such case: two selections of one field with different arguments conflict, no matter how small the difference — a limit, an order, an id — and aliasing is the fix each time.

Aliases nest like the fields they rename: stats: user(id: "1") { recent: posts(limit: 3) { title } } renames keys at two levels in one document, which is how a dashboard fetches several time-windowed versions of the same list without colliding at either level.

A naming convention keeps documents readable as they grow: nouns for entities (viewer, target), scope prefixes for variants (recent, popular). Response keys appear in every network trace and every cache read, so inconsistency costs readers time long after the query ships.

Aliases, Normalized Caches, and Read Paths

In a normalized client cache (Apollo Client, urql) records are stored by __typename plus id, while query results are addressed by response key:

document:  viewer: user(id:"1")   target: user(id:"2")
store:     User:1  ← read via data.viewer     User:2  ← read via data.target

Three production consequences follow:

1. The alias is a read path. Result resolvers read data.viewer, so renaming an alias breaks every cache.readQuery and test that expects the old key. Treat alias names like a public interface of the document.
2. Documents that differ only in aliases are different documents. Two dashboards fetching the same records through different alias names create two cache entries and two network requests — aliases can fragment the operation cache exactly as embedded literals do. See fragment reuse for the same concern applied to shared selection sets.
3. Aliases are the client's private namespace. Because the schema does not change, aliases need no coordination, no deprecation cycle, and no server deployment — which is why "fetch the same field twice with different arguments" should be answered with an alias rather than a near-duplicate schema field.

What aliases cannot do is conditionally rename: a response key is fixed by the document, so switching which key appears means a different document. For conditional presence of a field, see include and skip directives.

Interview angle: asked "how do you fetch two users in one query?", give the alias answer first, show the response-key mapping, then mention the alternative — a list argument like users(ids: [ID!]) when the server can batch — and note that the collision is a validation error, caught before execution.