Collection-valued fields
Schema fields that return multiple objects, such as users, products, or posts.
GraphQL · Class
GraphQLList
GraphQLList represents a GraphQL list type whose items share a declared item type. Lists preserve order and can be combined with non-null wrappers or nested lists.
How it works
GraphQLList is the GraphQL.js wrapper used to represent a list type. It takes an item type, and that item type may itself be another wrapper, allowing combinations such as lists of non-null values or nested lists.
Syntax
new GraphQLList(ofType)Parameters
| Name | Type | Description |
|---|---|---|
ofType | GraphQLType | The GraphQL item type wrapped by the list; it may be a named type or another type modifier. |
Returns
A GraphQL list type whose items are serialized according to the wrapped item type.
Key points
- GraphQL list notation uses square brackets and represents an ordered sequence.
- Every list declares the GraphQL type used to serialize each item.
- A schema field such as
pets: [Pet]returns a list ofPetvalues. - Lists can be nested when each item is itself another list type.
- The wrapped type can be another list or a non-null wrapper, enabling combinations such as nested and non-null lists.
Example: Declaring a list type
const users = new GraphQLList(UserType);Wrap a GraphQL object type to declare a field that returns an ordered list of users.
When to use it
Nested lists
Fields requiring nested collection structures, such as a matrix or grouped records.
Non-null list items
Fields where each returned item must satisfy a non-null constraint.
Interview questions
QWhat does GraphQLList represent, and how is it declared?
GraphQLList represents a list whose items have a specified GraphQL type. In a GraphQL.js schema field, it is commonly constructed as new GraphQLList(ItemType), which corresponds to [ItemType] in GraphQL schema notation.
Follow-up: How do you require every list item to be non-null? Use new GraphQLList(new GraphQLNonNull(ItemType)), corresponding to [ItemType!].
QCan GraphQLList wrap another wrapper or list?
A list type preserves item order and serializes each item according to the wrapped item type. The item type can itself be a modified type, so nested lists and lists of non-null types are supported.
Follow-up: What does [ [Int] ] express? It is a list whose items are themselves lists of integers; inner lists may contain null values unless further constrained.
QWhat operational concern applies to large GraphQLList fields?
A list field can produce many values, so an unconstrained list may create excessive response sizes. For potentially large list results, design the field with pagination rather than returning every item at once.
Follow-up: What other demand-control measures complement pagination? Depth, breadth or batch limits, and rate limiting can constrain costly operations.
Related
GraphQLNonNullGraphQLObjectTypeListNon-NullofType