GraphQL Writing Your First Query

A GraphQL query is the instruction you send to the server that says "give me this data in this shape." Writing queries is a skill you use every day as a GraphQL developer, whether you work on the client side or the server side.

The Basic Query Structure

A query starts with an opening curly brace, lists the fields you want, and ends with a closing curly brace. The server returns a JSON object with exactly those fields.

  GraphQL Query              Server Response
  ─────────────              ───────────────
  {                          {
    hello                      "data": {
  }                              "hello": "Welcome to GraphQL!"
                               }
                             }

The Shorthand Syntax vs the Full Syntax

GraphQL allows a shorthand when you write a simple query. The shorthand omits the word query. The full syntax includes it. Both produce the same result, but the full syntax is better for production code because it supports naming and variables.

  Shorthand (quick, anonymous):
  ───────────────────────────────
  {
    user {
      name
    }
  }

  Full syntax (recommended):
  ───────────────────────────────
  query GetUser {
    user {
      name
    }
  }

Reading a Single Record

To fetch one record by ID, pass an argument to the field. Arguments go inside round brackets, just like a function call.

  Schema definition:
  ──────────────────
  type Query {
    movie(id: ID!): Movie
  }

  Client query:
  ──────────────
  query GetMovie {
    movie(id: "42") {
      title
      year
      director
    }
  }

  Response:
  ──────────
  {
    "data": {
      "movie": {
        "title": "Interstellar",
        "year": 2014,
        "director": "Christopher Nolan"
      }
    }
  }

Reading a List of Records

When a schema field returns a list, the server sends back an array of objects. You still specify which fields you want from each item.

  Schema:
  ────────
  type Query {
    movies: [Movie]
  }

  Query:
  ───────
  query AllMovies {
    movies {
      title
      year
    }
  }

  Response:
  ──────────
  {
    "data": {
      "movies": [
        { "title": "Inception",     "year": 2010 },
        { "title": "Interstellar",  "year": 2014 },
        { "title": "Tenet",         "year": 2020 }
      ]
    }
  }

Selecting Only What You Need

A Movie type in the schema might have ten fields. You request only the ones your UI needs. This is one of GraphQL's biggest advantages over REST — the response contains no extra data.

  Full Movie type in schema:     Your query requests:
  ──────────────────────────     ────────────────────
  type Movie {                   {
    id, title, year,               movies {
    director, cast,                  title
    runtime, genre,                  director
    rating, synopsis,              }
    posterUrl, trailerUrl          }
  }

  Response contains:             Does NOT contain:
  ──────────────────             ─────────────────
  title, director                id, year, cast, runtime,
                                 genre, rating, synopsis,
                                 posterUrl, trailerUrl

The Response Always Lives Inside "data"

Every successful GraphQL response wraps your data inside a "data" key. This structure is part of the GraphQL specification. If errors occur, they appear in a separate "errors" key at the same level as "data".

  Success response:           Error response:
  ─────────────────           ───────────────
  {                           {
    "data": {                   "data": null,
      "movies": [...]           "errors": [
    }                             { "message": "Not found" }
  }                             ]
                              }