GraphQL explained: queries, mutations, subscriptions and introspection
GraphQL is a query language where the client describes the data it needs - the three operation types, why the request mirrors the response, and what introspection adds.
GraphQL is a query language designed to build client applications by providing an intuitive and flexible syntax and system for describing their data requirements and interactions - that is the opening definition of its specification, the October 2021 edition, which also records that it was originally created at Facebook in 2012. Instead of the server deciding the shape of every response, the client describes the data it needs, and the response mirrors that description. This guide covers the three operation types and two design principles worth knowing.
Three operation types
The specification models three types of operations. A query is a read-only fetch. A mutation is a write followed by a fetch. And a subscription is a long-lived request that fetches data in response to source events. Each operation is represented by an optional operation name and a selection set - the list of fields the client wants back.
Hierarchical by design
One of the specification's stated design principles is that GraphQL is hierarchical: because product development involves creating and manipulating view hierarchies, a GraphQL request is itself structured hierarchically - the request is shaped just like the data in its response. A client asking for a user's name and their latest posts writes the fields nested the way it will render them, which is a natural fit for components and screens.
Introspective by design
GraphQL is also introspective: a GraphQL service's type system can be queried by the GraphQL language itself. That is what lets tools and client libraries explore an API's schema - its types, fields and operations - without a separate documentation site, and it is why autocomplete and query builders work well against GraphQL services.
The calm version
GraphQL is a query language where the client spells out the data it needs - a read-only query, a mutation that writes then fetches, or a long-lived subscription - and the answer arrives in the same shape as the question. Its schema can answer questions about itself, which is what the tooling is built on.
Source: GraphQL Specification, October 2021 edition (spec.graphql.org/October2021, fetched 2026-11-20): the definition of GraphQL, its origin at Facebook in 2012, the three operation types, and the hierarchical and introspective design principles.
Frequently asked questions
What is GraphQL?
Per its specification, a query language designed to build client applications by providing a syntax and system for describing their data requirements and interactions - originally created at Facebook in 2012.
What are the three GraphQL operation types?
Query - a read-only fetch; mutation - a write followed by a fetch; and subscription - a long-lived request that fetches data in response to source events.
What does it mean that GraphQL is hierarchical?
It is a stated design principle: a GraphQL request is structured hierarchically, shaped just like the data in its response, which matches how product views and components are built.
What is GraphQL introspection?
A GraphQL service's type system can be queried using the GraphQL language itself, which powers tools and client libraries that explore the schema's types, fields and operations.