Begin a query at Query
Reading API data
GraphQL · Const
root value
A GraphQL operation starts at a root operation type. For queries, that root is the Query object, which provides the first fields the client can select.
How it works
A GraphQL operation begins with a root operation type. For a read operation, that is the schema's Query object; the client selects fields from it and continues through nested selections until reaching scalar or enum leaf values.
Syntax
query { field }Returns
The selected fields and their leaf values from the operation's root.
Key points
- For a read operation, the root operation type is the Query object.
- The root operation type acts as the API's starting point for selecting data.
- Clients declare the fields they want in a selection set immediately after the root.
- Nested selections let a query describe the shape of the requested result.
- A valid traversal ends at scalar or enum leaf fields.
Common mistakes
- A query must begin from a root operation type rather than directly selecting a nested object or scalar.
- Selections must continue to scalar or enum leaves; stopping at an object field is incomplete.
Example: Start at the query root
const query = `query { hero { name } }`;
fetch('/graphql', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ query })
});This query begins at the schema's root Query object and selects a field before reaching the returned leaf value.
When to use it
Traverse selected fields
Requesting nested data
Shape the response explicitly
Designing client operations
Interview questions
QWhat is the role of the root operation type in a GraphQL query?
A root value is the entry point represented by the root operation type. For a read operation, the Query object is the root, and the operation selects fields from it before traversing nested fields to scalar or enum leaves.
Follow-up: How does a client know which root fields are valid? It uses the schema, whose root operation type defines the fields available at the operation's top level.
QWhat does a GraphQL document start with?
The root operation type is the first object selected by an operation. A query starts at Query, while mutation and subscription operations use their corresponding operation roots when supported.
Follow-up: Why is the root not usually a scalar? Because GraphQL selections describe a hierarchy, and the root object provides the initial set of named fields.
QHow does a query proceed after reaching the root?
After entering through the root, a client specifies a selection set and follows fields through nested objects. The traversal ends at scalar or enum values, which provide the data values in the response.
Follow-up: What happens if an object field has no nested selection? The document is invalid because an object selection must specify which fields to request.
Related
QueryMutationSubscriptionselection setScalarEnum