7. Arguments
4m

Overview

It's time to grow our app with a new feature: we'll introduce a page that shows a specific track's details. We've gotten some practice for a list of tracks—but how do we ask our API for one very specific track?

In this lesson, we will:

  • Learn about s
  • Write a that accepts a
  • Build a page to display data for one track object

A new feature

Our goal is to create a page that requests data for one specific track. To do this, we'll need to put together a that requests data for a single track.

Let's start with the mockup of the Track page our design team provided us with. Here we'll need to display more information about a track than what's contained in a card on the homepage.

A mockup of the Track page showing a track thumbnail, title, and data about its modules

In addition to what we had in our card, a track needs to have:

  • a description
  • the number of views
  • the list of modules included in that track

For each module, we want:

  • the title
  • the length

A new Query entrypoint

Let's return to Sandbox, and select the Schema option from the left-hand toolbar.

https://studio.apollographql.com/sandbox/schema/reference

The Schema page in Studio.

We've gotten some practice the tracksForHome , but let's take a look at the two other fields on the Query type: track and module. Each of these remaining accepts an argument.

https://studio.apollographql.com/sandbox/schema/reference

The Schema page in Studio, opened to the Query type's fields and highlighting the id argument on each.

GraphQL arguments

An is a value we provide for a particular in your . In the case of both track and module, the schema defines an id that they each accept. By specifying the id for a module or a track object, we can data for a particular object.

track(id: ID!): Track!

On the backend, the can use a 's provided (s) 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.

The track in our schema, which accepts an id , looks like just the we'll need to use to make our track page dreams come true. It takes an id, and returns data for a specific Track!

https://studio.apollographql.com/sandbox/schema/reference

The Schema page in Studio, opened to the Query type's fields and highlighting the track field.

This means that all we need to do on the frontend is pass a valid value for the id of a particular track—and the server will take care of returning the data we need!

Let's see how we can build a specific using in the Explorer.

🛠️ Building our query

Let's jump back to the Explorer and build our .

https://studio.apollographql.com/sandbox/explorer

The Explorer opened to show the Query type fields

Clicking the plus button () on the track , we start to see our come together in the Operation panel.

https://studio.apollographql.com/sandbox/explorer

The Explorer Operation panel, updated with the track field

First let's rename our to better explain what it's for, so we'll replace Track with GetTrack.

So far, the Operation panel of the Explorer should contain this:

query GetTrack($trackId: ID!) {
track(id: $trackId) {
}
}

You'll notice something new here: a dollar sign ($) followed by the name trackId.

💰 Variables

The $ symbol indicates a in . The name after the $ symbol is the name of our , which we can use throughout the . After the colon is the variable's type, which must match the type of the we'll use it for.

Illustration to explain the syntax of GraphQL variables

are great—they let us pass values dynamically from the client-side so we don't have to hardcode values into our . We'll use them every time we create a query with arguments.

In our case, we have a called trackId that the Explorer set up for us down in the Variables section. Right now, it's set to null, but let's replace it with a valid track ID: c_0.

https://studio.apollographql.com/sandbox/explorer

Screenshot identifying the Variables panel in the Explorer, with the track id of 'c_0'

Add the following to the Variables section in the Explorer:

{ "trackId": "c_0" }

Before we start adding all the we need from our initial mockup, let's start small with just returning the id and the title.

The Operation panel of the Explorer should now look like this:

query GetTrack($trackId: ID!) {
track(id: $trackId) {
id
title
}
}

When we click on the button to run the , we see the data we're expecting: the first track's title "Cat-stronomy, an introduction".

Awesome, let's add the rest of our by clicking the dropdown by the Fields subheading. When we click Select all fields recursively from the dropdown, we'll see all of our and subfields have been added to the .

https://studio.apollographql.com/sandbox/explorer

Screenshot of the Explorer with all fields added recursively to our query

The full should look like this:

query GetTrack($trackId: ID!) {
track(id: $trackId) {
id
title
author {
id
name
photo
}
thumbnail
length
modulesCount
description
numberOfViews
modules {
id
title
length
content
videoUrl
}
}
}

Let's click on the Run Query button again… it looks like we get the complete track, but it's a bit tricky to read as a JSON object. The Explorer has a nice option to format the response as a table.

https://studio.apollographql.com/sandbox/explorer

Screenshot of the Explorer highlighting how to format Response data in a table view

And now we can clearly see the track that we need, along with all the details for each module! Nice!

https://studio.apollographql.com/sandbox/explorer

Screenshot showing the Explorer with a complete query and successful response

Practice

Variables
Variables are denoted by the 
 
symbol. They are used to provide dynamic values for 
 
to avoid including 
 
 values in a query. Each one's type must match the type specified in the 
 

Drag items from this box to the blanks above

  • !

  • hardcoded

  • name

  • $

  • null

  • @

  • schema

  • graph

  • resolvers

  • arguments

Code Challenge!

Build a query called GetMission. This query uses a variable called isScheduled of type nullable Boolean. It retrieves a mission using the scheduled argument set to the isScheduled variable. It retrieves the mission's id and codename.

Loading...
Loading progress

Key takeaways

  • A is a value we provide for a particular in a .
  • On the backend, the can use to help determine how to populate data for a .
  • We use the $ symbol to denote a in .
  • With , we can pass values dynamically from the client-side.

Up next

Our 's set, but we still need our frontend pieces! Let's build the track page in the next lesson.

Previous

Share your questions and comments about this lesson

This course is currently in

beta
. 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.