Benney Au

Querying Data with GraphQL

Benney Au

Oct 5, 2020
5 Min read
9,591 Views

Oct 5, 2020
5 Min read
9,591 Views

Data Query Languages

Data

Data Development

GraphQL

Introduction

GraphQL is a query language for accessing object graphs. It is designed to be type safe and give clients the ability to request only the data they need.

In this guide, you will learn how to construct GraphQL queries. Then we will explore some unique features of GraphQL, including fragments, sending variables and GraphQL directives. Throughout this guide, you will use the GraphQL implementation of the Star Wars API to test the querying capabilities of GraphQL.

Performing a Basic Query in GraphiQL

GraphiQL is a simple UI tool that allows you to query GraphQL endpoints with the convenience of auto-complete and syntax highlighting.

To get started writing your first GraphQL query, navigate to the Star Wars GraphiQL page. From this page, you can look at the documentation for the GraphQL endpoint, submit queries and see the output.

Submit the following query in the top left pane of GraphiQL.

1query GetAllFilms {
2  allFilms {
3    films {
4      title
5      episodeID
6      openingCrawl
7      director
8      producers
9      releaseDate
10    }
11  }
12}

graphql

This query consists of three components:

GetallFilms is the operation name that clients can set. This can be useful for debugging issues.

allFilms is field exposed endpoint on the root node. It is a complex types of Film that combines several scalar values into a single unit.

title, episodeID, director, etc. are fields. These are units of data that you are requesting to appear in the response data. allFilms is also a field that combines the fields nested inside it.

These are the fundamental building blocks of a GraphQL query. In the following sections, you will use these building blocks to perform more advanced queries.

Sending Arguments to GraphQL Fields

You have just queried all films. However, sometimes you only need a subset of this data. With the Star Wars GraphQL endpoint, you can send arguments to the allFilms field to filter the data.

There are two ways to send arguments. The first is inline:

1query GetAllFilms {
2  allFilms(first: 3) {
3    films {
4      title
5      episodeID
6      openingCrawl
7      director
8      producers
9      releaseDate
10    }
11  }
12}

graphql

You modified the allFilms field in the query to allFilms(first: 3). This approach is appropriate when you don't need to change the value of your argument(s). If your argument values change frequently, it is better to define an input variable.

To do this, update your query to the following:

1query GetAllFilms($firstFilms: Int) {
2  allFilms(first: $firstFilms) {
3    films {
4      title
5      episodeID
6      openingCrawl
7      director
8      producers
9      releaseDate
10    }
11  }
12}

graphql

You will also need to set the variables. In GraphiQL, this is configured at the bottom left of the screen. Insert the following JSON to set the variables in the query operation defined above.

1{"firstFilms": 3}

json

Using GraphQL Fragment

As you use GraphQL to query a number of resources, your query can become quite large. One way to manage this is to split your query into small, reusable pieces called fragments. Fragments are a selection set on a specific GraphQL type and can be reused in different query operations.

The snippet below demonstrates reusing a snippet fragment on the Film type within the same query operation.

1query GetAllFilms {
2  allFilms {
3    films {
4      title
5      episodeID
6      openingCrawl
7      director
8      producers
9      releaseDate
10      id
11    }
12  }
13
14  film(id:"ZmlsbXM6MQ==") {
15    ...FilmFragment
16  }
17}
18
19fragment FilmFragment on Film {
20  title
21  episodeID
22  openingCrawl
23  director
24  producers
25  releaseDate
26  id
27}

graphql

Using GraphQL Directives

A powerful feature that makes GraphQL extensible is the inclusion of directives. These are declarations that are prefixed with @, which allows extra logic to be executed on either the server or the client.

There are two directives that are built into the Star Wars Schema: @include and @skip. Usage of @include of is demonstrated in the code snippet below:

1query GetAllFilms($includeFilm: Boolean!) {
2  allFilms {
3    films {
4      title
5      episodeID
6      openingCrawl
7      director
8      producers
9      releaseDate
10      id
11    }
12  }
13
14  film(id:"ZmlsbXM6MQ==") @include(if: $includeFilm) {
15    ...FilmFragment
16  }
17}
18
19fragment FilmFragment on Film {
20  title
21  episodeID
22  openingCrawl
23  director
24  producers
25  releaseDate
26  id
27}

graphql

The film field is appended with @include(if: $includeFilm). Adding this allows clients to conditionally request the film field when the $includeFilm variable is set to true, and not return this field when it is set to false. This approach makes it possible to retrieve different resources without modifying your query.

Conclusion

GraphQL is becoming an increasingly important technology. It was developed by Facebook, and other large organizations like GitHub, Pinterest, and Coursera have adopted it. Web and integration developers will need to learn this query language to access the next generation of APIs. As a next step, you may want to explore How to Set Up GraphQL in a React App.

LEARN MORE