GraphQL arguments

3. GraphQL arguments

Overview

We've added track and module fields to the schema, but we still need a way to fetch one track by ID. GraphQL arguments let us pass that ID into the query.

In this lesson, we will:

Add a track entry point on the Query type
Learn how field arguments are defined in a schema
Accept a required id argument on the track field

❓ Querying for a specific track

We've updated our schema with new fields and the Module type, but we still need a way to query for a specific track by its ID. To do that, we'll need to add another entry point to our schema.

In our schema.graphql file in the server/src folder, we can see that we only have a single entry point to our API so far: the tracksForHome field that returns a list of Track objects. Let's add another one called track, which will return a single Track.

Add the following field to our schema's Query type:

track: Track

We'll be able to specify which unique track we're querying for by giving this field an argument.

🤔 How to use GraphQL arguments

An argument is a value you provide for a particular field in your query. The schema defines the arguments that each of your fields accepts.

Your resolvers can then use a field's provided arguments to help determine how to populate the data for that field. Arguments can help you retrieve specific objects, filter through a set of objects, or even transform the field's returned value. A query that performs a search usually provides the user's search term as an argument.

Doodle of resolver function retrieving a specific object from data-land using an argument

To define an argument for a field in our schema, we add parentheses after the field name. Inside, we write the name of the argument followed by a colon, then the type of that argument, like String or Int. If we have more than one argument, we can separate them with commas.

Illustration showing the syntax breakdown of using GraphQL arguments

🙌 Using arguments

In our case, we want to use the track's ID as our argument. Following the syntax rules, we'll add the parentheses, then the name id, with the type ID which is required.

Inside the Query type in schema.graphql, update the track field to:

"Fetch a specific track by ID"
track(id: ID!): Track

Code review

type Query {
  "Fetch a list of tracks for the homepage grid"
  tracksForHome: [Track!]!
  "Fetch a specific track by ID"
  track(id: ID!): Track
}
"Educational modules teaching a specific topic"
type Track {
  "The unique identifier for the track"
  id: ID!
  "The title of the track"
  title: String!
  "The track's primary author"
  author: Author!
  "The URL of the track's illustration, used in the track card and track detail page"
  thumbnail: String
  "The track's approximate length to complete, in minutes"
  length: Int
  "The number of modules contained in this track"
  modulesCount: Int
  "The track's full description, which may include Markdown"
  description: String
  "The number of times this track has been viewed"
  numberOfViews: Int
  "The ordered list of modules that make up this track"
  modules: [Module!]!
}
"A single unit of teaching. Multiple modules compose a track"
type Module {
  "The unique identifier for the module"
  id: ID!
  "The title of the module"
  title: String!
  "The module's length, in minutes"
  length: Int
}
"An author of a track or module"
type Author {
  "The unique identifier for the author"
  id: ID!
  "The author's first and last name"
  name: String!
  "The URL of the author's profile picture"
  photo: String
}

Practice

Where can we add entry points to our schema?

In any object type (Track, Module, etc.)In the Query typeIn the EntryPoint typeIn our resolvers

Which of these are reasons to use arguments in a query?

To transform a field's returned valueTo filter a set of objectsTo retrieve a specific objectTo provide a user-submitted search term

Code Challenge!

Update the schema below to add two new entry points: 1) galaxy to query for a specific galaxy, which takes an argument id of type non-nullable ID and returns a non-nullable Galaxy. 2) planets, which takes two arguments: galaxy of non-nullable type String (to specify the galaxy name the planet belongs to), and minPopulation of nullable type Int (to filter for planets with a minimum population). This field returns a nullable array of nullable Planet types.

Loading progress

Up next

That's it for the query definition. We now have our schema up-to-date for the feature we're implementing. Onwards to the resolver!

Share your questions and comments about this lesson

Your feedback helps us improve! If you're stuck or confused, let us know and we'll help you out. All comments are public and must follow the Apollo Code of Conduct. Note that comments that have been resolved or addressed may be removed.

You'll need a GitHub account to post below. Don't have one? Post in our Odyssey forum instead.