Writing Queries

Analogy categoryAnalogies

What Is a GraphQL Query?

A GraphQL query is a read operation the client sends to a single HTTP endpoint, typically /graphql, describing precisely which fields of which types it wants returned. Unlike REST, where each resource lives at its own URL and returns a fixed payload shape, a GraphQL server exposes one schema and lets every query shape its own response, so the client never receives fields it did not ask for.

🏏

Cricket analogy: It's like a batter facing Jasprit Bumrah and calling for exactly the delivery they want to practise against in the nets, rather than accepting whatever ball a fixed bowling machine spits out.

Anatomy of a Query: Operation, Selection Set, and Fields

A query is written as the keyword query (optionally omitted for anonymous shorthand queries), followed by curly braces containing a selection set — the list of fields you want. Each field must itself resolve to either a scalar (String, Int, Float, Boolean, ID) or another selection set if it returns an object type; you cannot leave an object-typed field bare without specifying which of its sub-fields to fetch.

🏏

Cricket analogy: A field like runs or wickets is a scalar leaf you can request directly, but a field like currentMatch returns an object, so you must drill into it and ask for score or overs, the same way a scorecard app can't just say 'match' without specifying which stats.

Nested Fields Traverse the Schema Graph

Because object-typed fields can themselves contain further object-typed fields, a single query can traverse several levels of the schema graph in one round trip — for example fetching a user, that user's posts, and each post's comments, all in one request. The server resolves this tree top-down, calling a resolver function for each field, so the client gets a deeply nested JSON tree back that mirrors the shape of the query exactly, with no extra round trips and no unrelated data.

🏏

Cricket analogy: A single query can pull a team, its current squad, and each player's last five scores in one shot, the way a broadcaster's graphics engine assembles a full player-form overlay from one data pull instead of querying the scorecard, then the squad list, then each player separately.

graphql

query GetUserWithPosts {
  user(id: "u_9001") {
    id
    name
    email
    posts {
      id
      title
      publishedAt
      comments {
        id
        body
        author {
          name
        }
      }
    }
  }
}

Every GraphQL query, no matter how deeply nested, is sent to the exact same URL, usually via a single HTTP POST with the query text in the request body. There is no per-resource routing — the query itself is the routing information, which is why tools like GraphiQL and Apollo Studio can introspect the entire API from one endpoint.

Naming Operations for Clarity and Tooling

Although the query keyword and an operation name are optional for a single anonymous query, naming operations — for example query GetUserWithPosts instead of a bare query { ... } — is considered best practice in any real codebase. Named operations show up in server logs, APM traces, and browser dev tools network tabs, making it far easier to correlate a slow request with the exact query that caused it, and they are required if a single document contains more than one operation.

🏏

Cricket analogy: Naming a query GetLiveScorecard is like a broadcast director labeling a camera feed 'Feed 3 – Bowler End' instead of just 'Camera' — when something breaks during a Test match broadcast, you know exactly which feed to check.

Deeply nested queries that fan out across many objects and lists can create an N+1 problem on the server: naively implemented resolvers issue one database call per parent-child edge, so a query returning 50 posts with comments could trigger hundreds of individual queries. Production GraphQL servers mitigate this with batching and caching layers such as DataLoader rather than by limiting how deeply clients can nest their selections.

A GraphQL query is a client-defined read operation sent to a single endpoint; the response shape mirrors the query shape.
Scalar fields (String, Int, Float, Boolean, ID) are leaves; object-typed fields require a nested selection set.
Queries can traverse multiple levels of the schema graph in one round trip, avoiding the multiple-request problem common with REST.
The query keyword and operation name are optional for a single anonymous operation but required once a document has multiple operations.
Naming operations (e.g. GetUserWithPosts) improves debuggability in logs, APM tools, and browser dev tools.
Deep nesting can trigger the N+1 problem on the server, typically solved with batching tools like DataLoader.