Odyssey

Lift-off III: Arguments

Feature OverviewUpdating our schemaGraphQL argumentsResolver args parameterResolver chainsQuery building in Apollo SandboxBuilding the track pageThe useQuery hook - with variablesNavigating to the track page
6. Query building in Apollo Sandbox
3m

🚀 Exploring the Apollo Sandbox

So far, we've been using the Explorer page of Apollo Sandbox to build and test GraphQL queries. But Sandbox can do even more! Let's take a quick detour to explore some of the other tools in Sandbox.

First, we need to start our server. Open a terminal window, navigate to the server folder with cd server, then run npm start.

With the server running, we can go to the Sandbox in the browser by going to http://localhost:4000.

The Schema page

Let's check out the schema page (the first tab on the left sidebar).

http://localhost:4000
Screenshot of GraphOS Studio, opened to the Schema page

This page gives us useful information about the current status of our schema. Because we're using Sandbox, GraphOS Studio automatically polls our locally running server for schema changes.

The Schema page has two main tabs: Reference and SDL.

The SDL tab shows you your schema represented in schema definition language. It should look familiar from your own schema.jsfile!

The Reference tab shows you a high-level overview of your schema, including its defined types and fields. Notice the Play button to the right of the field? Click it and see what happens. It sends us directly to the Explorer, with the Documentation sidebar conveniently opened to the corresponding field!

🛠️ Building our query

Now that we're back in the Explorer page, let's get back to building our query. Clicking the plus button (⊕) on the track field, we start to see our query come together in the Operation panel.

http://localhost:4000
Screenshot of GraphOS Studio Explorer with the Operation panel pre-filled with the `track` field

First let's rename our query to better explain what it's for, so we'll replace Query 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 variable in GraphQL. The name after the $ symbol is the name of our variable, which we can use throughout the query. After the colon is the variable's type, which must match the type of the argument we'll use it for.

Illustration to explain the syntax of GraphQL variables

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

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

  • schema

  • $

  • resolvers

  • graph

  • null

  • @

  • !

  • name

  • hardcoded

  • arguments

To pick up a draggable item, press the space bar. While dragging, use the arrow keys to move the item. Press space again to drop the item in its new position, or press escape to cancel.

In our case, we have a variable 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 the track ID we've been testing so far: c_0.

http://localhost:4000
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 fields 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 run query button, we see the data we're expecting! Awesome, let's add the rest of our fields by clicking the dropdown by the Fields subheading. When we click Select all fields recursively from the dropdown, we'll see all of our fields and subfields have been added to the query.

http://localhost:4000
Screenshot of the Fields dropdown, selecting the option to add all fields recursively to our query

The full query should look like this:

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

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.

http://localhost:4000
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!

http://localhost:4000
Screenshot showing the Explorer with a complete query and successful response
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 editor

Our server is ready for our client's queries, so let's hop on over to client-land and work on the UI.

Previous
Next

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.

              Apollo Sandbox

              A part of GraphOS Studio focused on local development, available at https://studio.apollographql.com/sandbox. Apollo Sandbox does not require an Apollo account.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              GraphOS Studio

              The web interface for GraphOS, which provides graph, variant, and organization management, metrics visualization, schema pipeline tools and more.

              SDL

              GraphQL's schema definition language (SDL). The syntax for writing GraphQL schemas. All GraphQL APIs can use SDL to represent their schema, regardless of the API's programming language.

              schema definition language

              GraphQL's schema definition language (SDL). The syntax for writing GraphQL schemas. All GraphQL APIs can use SDL to represent their schema, regardless of the API's programming language.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              field

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              variable

              A placeholder for dynamic values in an operation allowing parameterization and reusability in requests. Variables can be used to fill arguments or passed to directives.

              query GetUser($userId: ID!) {
                user(id: $userId) {
                  firstName
                }
              }

              In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of variable is a non-nullable ID. A variable's type must match the type of any argument it's used for.

              GraphQL

              An open-source query language and specification for APIs that enables clients to request specific data, promoting efficiency and flexibility in data retrieval.

              variable

              A placeholder for dynamic values in an operation allowing parameterization and reusability in requests. Variables can be used to fill arguments or passed to directives.

              query GetUser($userId: ID!) {
                user(id: $userId) {
                  firstName
                }
              }

              In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of variable is a non-nullable ID. A variable's type must match the type of any argument it's used for.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              argument

              A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

              Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

              query GetHuman {
                human(id: "200") {
                  name
                  height(unit: "meters")
                }
              }
              Variables

              A placeholder for dynamic values in an operation allowing parameterization and reusability in requests. Variables can be used to fill arguments or passed to directives.

              query GetUser($userId: ID!) {
                user(id: $userId) {
                  firstName
                }
              }

              In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of variable is a non-nullable ID. A variable's type must match the type of any argument it's used for.

              argument

              A key-value pair associated with a particular schema field that lets operations pass data to that field's resolver.

              Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

              query GetHuman {
                human(id: "200") {
                  name
                  height(unit: "meters")
                }
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              variable

              A placeholder for dynamic values in an operation allowing parameterization and reusability in requests. Variables can be used to fill arguments or passed to directives.

              query GetUser($userId: ID!) {
                user(id: $userId) {
                  firstName
                }
              }

              In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of variable is a non-nullable ID. A variable's type must match the type of any argument it's used for.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              fields

              A unit of data that belongs to a type in a schema. Every GraphQL query requests one or more fields.

              type Author {
                # id, firstName, and lastName are all fields of the Author type
                id: Int!
                firstName: String
                lastName: String
              }
              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              query

              A request for specific data from a GraphQL server. Clients define the structure of the response, enabling precise and efficient data retrieval.

              NEW COURSE ALERT

              Introducing Apollo Connectors

              Connectors are the new and easy way to get started with GraphQL, using existing REST APIs.

              Say goodbye to GraphQL servers and resolvers—now, everything happens in the schema!

              Take the course