Queries: Asking for Exactly What You Need

Queries are the heart of GraphQL: declarative descriptions of the data your UI needs, sent to a single endpoint and answered with JSON of exactly the same shape. In this lesson we will write real queries, nest them, alias duplicate fields, and learn how GraphQL responses behave when things go wrong.

Anatomy of a Query

A query is a selection of fields starting from the Query root type. Given the blog schema from the previous lesson:

graphql

query GetUsers {
  users {
    id
    name
  }
}

A few things to note:

query is the operation type; GetUsers is an optional but recommended operation name that shows up in logs and dev tools.
The braces contain a selection set. Every field you want must be listed explicitly; there is no SELECT * in GraphQL, and that is a feature.
The response arrives under a top-level data key mirroring your selection.

json

{ "data": { "users": [{ "id": "1", "name": "Ada" }] } }

Nesting: Traversing the Graph

Because fields can return object types, selections nest arbitrarily deep. This is how one request replaces several REST round trips:

graphql

query PostWithAuthor {
  post(id: "7") {
    title
    author {
      name
      posts {
        title
        published
      }
    }
  }
}

The server walks the graph for you: post 7, its author, and the other posts by that same author, all in one round trip. Be aware that depth has a cost; production servers usually enforce a maximum query depth to stop abusive requests.

Aliases: Same Field, Different Arguments

JSON keys must be unique, so you cannot ask for post(id: "7") and post(id: "9") side by side without renaming one. Aliases solve this:

graphql

query TwoPosts {
  first: post(id: "7") { title }
  second: post(id: "9") { title }
}

The response now uses your names: { "data": { "first": {...}, "second": {...} } }. Aliases are also handy for renaming server fields to what your UI component expects.

Comments and Formatting

Lines starting with # are comments. Whitespace and commas are insignificant, so format for readability; most teams run Prettier on .graphql files.

Errors and Partial Data

A GraphQL response can contain both data and errors. If resolving one nullable field fails, the server nulls that field, appends an entry to the errors array with a path, and still returns everything else:

json

{
  "data": { "post": { "title": "On Engines", "viewCount": null } },
  "errors": [{ "message": "stats service timeout", "path": ["post", "viewCount"] }]
}

Partial success is a deliberate design choice: one flaky microservice should not blank out the whole screen. We will go much deeper on errors in lesson 11.

Exploring with GraphiQL

Most GraphQL servers ship an in-browser IDE, GraphiQL or Apollo Sandbox, at their endpoint. Thanks to schema introspection you get autocomplete (Ctrl+Space), inline docs, and instant execution. Make it a habit: explore any new GraphQL API through its playground before writing application code.

Key Takeaways

A query is a named selection set starting at the Query root; the response mirrors its shape under data.
Nesting selections traverses relationships in a single round trip.
Aliases let you request the same field multiple times with different arguments.
Responses support partial success: data and errors can coexist.
Use GraphiQL and introspection-powered autocomplete to explore any schema.

Next lesson: Arguments and Variables, where queries become dynamic and reusable.