On this page, you'll learn all you need to know about the GraphQL type system and GraphQL Schema to define the data. Since GraphQL can be used with any backend framework or programming language, we'll stay away from implementation-specific details and talk only about the concepts.
If you've seen a GraphQL query before, you know that the GraphQL query language is basically about selecting fields on objects. So, for example, in the following query:
- GraphQL Query
- Input Data
- We start with a special
queryfor request and
- We select the
todosfield on that
- For the object returned by todos, we select the
Because the shape of a GraphQL query closely matches the result, you can predict what the query will return without knowing that much about the server. But it's useful to have an exact description of the data we can ask for - what fields can we select? What kinds of objects might they return? What fields are available on those sub-objects? That's where the schema comes in.
Every GraphQL service defines a set of types that completely describe the set of possible data you can query on that service. Then, when queries come in, they are validated and executed against that schema.
The most basic components of a GraphQL schema are object types, which just represent a kind of object you can fetch from your service. The object has fields of various types. In the GraphQL schema language, we might represent it like this:
The language is pretty readable, but let's go over it so that we can have a shared vocabulary:
Characteris a GraphQL Object Type, meaning it's a type with some fields. Most of the types in your schema will be object types. On the Hypi platform, you may build the Schema by adding this object type in the form of a table using Visual builder. (See Create Table) . Consider
Characteras a table and its fields as columns.
appearsInare fields on the
Charactertype. That means that
appearsInare the only fields that can appear in any part of a GraphQL query that operates on the
Stringis one of the built-in scalar types - these are types that resolve to a single scalar object, and can't have sub-selections in the query. We'll go over scalar types more later.
String!indicates that the field is non-nullable, meaning that the GraphQL service promises to always give you a value when you query this field. The field will never be empty. In the type language, we'll represent such fields with an exclamation mark.
[Episode!]!represents an array of Episode objects. Since it is also non-nullable, you can always expect an array (with zero or more items) when you query the appearsIn field. And since Episode! is also non-nullable, you can always expect every item of the array to be an Episode object.
Now you know what a GraphQL object type looks like, and how to read the basics of the GraphQL type language.
Every field on a GraphQL object type can have zero or more arguments. Look at the
length field below:
Arguments can be either required or optional. When an argument is optional, we can define a default value - if the unit argument is not passed, it will be set to METER by default.
Most types in your schema will just be normal object types, but there are two special types within a schema:
Every GraphQL service has a query type and may or may not have a mutation type. These types are the same as a regular object type, but they are special because they define the entry point of every GraphQL query. So if you see a query that looks like:
- GraphQL Query
It means that the GraphQL service needs to have a Query type with hero and droid fields
Mutations work similarly - you define fields on the Mutation type, and those are available as the root mutation fields you can call in your query.
It's important to remember that other than the special status of being the "entry point" into the schema, the
Mutationtypes are the same as any other GraphQL object type, and their fields work exactly the same way.
Check about GraphQL scalar types here.
Also called Enums, enumeration types are a special kind of scalar that is restricted to a particular set of allowed values. This allows you to:
- Validate that any arguments of this type are one of the allowed values.
- Communicate through the type system that a field will always be one of a finite set of values.
Here's what an enum definition might look like in the GraphQL schema language:
This means that wherever we use the type
Episode in our schema, we expect it to be exactly one of
Object types, scalars, and enums are the only kinds of types you can define in GraphQL. But when you use the types in other parts of the schema, or your query variable declarations, you can apply additional type modifiers that affect the validation of those values. Let's look at an example:
Here, we're using a String type and marking it as Non-Null by adding an exclamation mark, ! after the type name. This means that our server always expects to return a non-null value for this field, and if it ends up getting a null value that will actually trigger a GraphQL execution error, letting the client know that something has gone wrong.
The Non-Null type modifier can also be used when defining arguments for a field, which will cause the GraphQL server to return a validation error if a null value is passed as that argument, whether in the GraphQL string or the variables.
The type name within square brackets indicates that the field is a list. Hence
appearIn is a list of objects of type Episode. Each list item will contain the fields of object