In this section we will learn everything that is needed to build an expressive GraphQL schema.
Operations
First we will look at the three root types, often called Operations, that represent entry points to our schema:
Queries allow us to query our graph and retrieve data in a readonly manner.
Learn more about queriesMutations allow us to mutate our graph entities in the form of adding, removing or updating entities.
Learn more about mutationsSubscriptions allow us to subscribe to events in our system and be notified in real-time of their occurrence.
Learn more about subscriptions
Types
Each GraphQL schema is made up of two basic building blocks:
Object types contain fields and describe our entities.
Learn more about object typesScalars are the primitives of our GraphQL schema:
String,Int, etc.
We can also define custom scalars to more precisely describe our business domain.
Learn more about scalars
There are also more advanced types:
- Enums are a special kind of scalar, restricted to a particular set of allowed values.
Learn more about enums - Interfaces represent a shared contract that other types can implement.
Learn more about interfaces - Unions represent a set of object types, without the need for a shared contract.
Learn more about unions.
Type Modifiers
Besides regular types, like scalars and object types, there are also type modifiers.
A non-null field for example indicates that a client can always expect a non-null value to be returned from the field.
List fields indicate to a client that the field will return a list in the specified shape.
Arguments
We can pass arguments to individual fields on an object type and access their values inside the field's resolver.
Nested object types can also be used as arguments by declaring so called input object types. These are most commonly used when passing a payload to a mutation.
Learn more about input object types
Extending Types
Hot Chocolate allows us to extend existing types, helping us keep our code organized.
Rather than adding more and more fields to the Query type in the same class for instance, we can extend the Query type with a new field from another location in our codebase where that field logically should live.
Learn more about extending types
Directives
Directives allow us to decorate parts of our GraphQL schema with additional configuration.
This configuration can be used as metadata for client tools or alternate our GraphQL server's runtime execution and type validation behavior.
Schema evolution
As our data graph and number of developers/clients grows, we need to ensure that the graph is understood by everyone. Therefore, our schema should expose as much information to consumers of our API as possible.
Learn more about schema documentation
Relay
Relay proposes some schema design principles for GraphQL servers in order to more efficiently fetch, refetch and cache entities on the client. Since these principles make for a better schema, we encourage all users, not only those of Relay, to consider these principles.