GraphQL Aliases and Multiple Queries

Aliases let you rename fields in the response. Multiple queries let you fetch different pieces of data in one single request. Together, these features save round trips and keep your data organized.

The Problem Aliases Solve

Suppose a product comparison page needs two different products from the same product field. If you call product twice with different IDs, GraphQL does not know which response belongs to which call. The second call would overwrite the first in the response.

  ✗ Problem — same field name used twice:
  ─────────────────────────────────────────
  {
    product(id: "1") { name }
    product(id: "2") { name }   ← Conflict!
  }
  Error: Fields "product" conflict because they have
         different arguments.

Aliases Rename Fields in the Response

An alias goes before the field name with a colon separator. The response uses the alias as the key instead of the original field name.

  Query with aliases:
  ────────────────────
  {
    firstProduct:  product(id: "1") {
      name
      price
    }
    secondProduct: product(id: "2") {
      name
      price
    }
  }

  Response:
  ──────────
  {
    "data": {
      "firstProduct":  { "name": "Keyboard", "price": 49.00 },
      "secondProduct": { "name": "Monitor",  "price": 199.00 }
    }
  }

Aliases on Any Field

Aliases work on any field in the query, not just the top level. Use them whenever you want the response key to differ from the schema field name.

  Schema field   →  Alias used   →  Response key
  ────────────────────────────────────────────────
  firstName          givenName       "givenName"
  lastName           surname         "surname"
  emailAddress       email           "email"

  Query:
  ───────
  {
    user(id: "3") {
      givenName:  firstName
      surname:    lastName
      email:      emailAddress
    }
  }

Multiple Top-Level Queries in One Request

GraphQL executes all top-level fields in a query in parallel. You can ask for completely unrelated data from different parts of your schema in one single HTTP request. This eliminates the need for multiple REST calls that your app would otherwise make in parallel anyway.

  Query — dashboard page needs 3 types of data:
  ───────────────────────────────────────────────
  {
    currentUser {
      name
      avatarUrl
    }
    notifications {
      message
      isRead
    }
    featuredProducts {
      name
      price
    }
  }

  Response — all three in one JSON:
  ───────────────────────────────────
  {
    "data": {
      "currentUser":       { "name": "Arjun", "avatarUrl": "..." },
      "notifications":     [ { "message": "...", "isRead": false } ],
      "featuredProducts":  [ { "name": "Laptop", "price": 899 } ]
    }
  }

Using Aliases to Shape Response for UI Components

A dashboard UI component might need data in a specific shape that matches its props. Aliases let you rename fields on the server's response to match your frontend code without writing any transformation logic.

  UI component expects:         Query uses aliases:
  ─────────────────────         ───────────────────
  { userName, userEmail }       {
                                  user(id: "1") {
                                    userName:  name
                                    userEmail: email
                                  }
                                }

Key Points

• Aliases rename fields in the response and resolve conflicts when the same field is queried twice with different arguments.
• Aliases use the format aliasName: fieldName.
• Multiple top-level fields in one query run in parallel and return together in a single HTTP response.
• Combining multiple queries into one request reduces round trips compared to making several REST calls.