Building Queries

GraphQL Queries

• Schema
• Fields
• Types

Let's talk about the structure of a the GraphQL query we just ran.

The structure of all your data is known as the schema

Searches are done by using looking through different fields and sub-fields. So, in our example, query is a field we're looking for.

The fields can be of different types. You're probably familiar with some traditional types like strings, integers and booleans, but each GraphQL instance also has it's own custom types.

GraphQL Requests

• Queries
• Mutations

In the Github GraphQL API, there are two root types you can use.

The first is queries. This is a simple request for information from the server. The query type has a number of sub-fields you can request. In our example, we asked for the viewer, but you can also ask for information about organizations, repos or users.

The second is a mutation. This creates a request to modify data on the Github servers.

Adding other Fields

{
  viewer {
    login
    name
    bio
    company
    avatarUrl
  }
}

You can request more than one field, so let's add name, bio, company and avatarUrl

In the explorer, there are pop-up hints that appear as you type in the editor. It will show up if you type a letter, or you can use ctrl-m to make he hints appear at any time.

Notes: It doesn't matter what order things are in, by the way and you can add a comment using a pound sign.

Arguments

{
  license(key: "MIT") {
    name
    description
    body
    url
  }
}

You can pass arguments to repositories, so let's say I wanted information about a specific license you can use in repos.

Let's use the docs to read how we would do this. Click on the Query field and scroll down to the license field. Note that it expects an argument called key and then a string. Now click on the license type to see details.

Notice that it expects a SPDX ID, which are shortnames for all of the difference licenses.

Because it has an ! mark, I know that this is a required field. And notice that afterwards it explains that this item returns a License.

I happen to know that the SPXID for the MIT license is just the word MIT, so let's try sending that.

This type will also want to know which fields we want to ask for. If you click on the license type, you'll see that there are lots of other things we can ask for like the name, description,body, etc.

Now take a peek at the explorer and you'll notice that you can also choose things from there, or see the structure of the fields. Somtimes it helps to see then in that outline format.

Nodes

{
  viewer {
    repositories(first: 2) {
      totalCount
      nodes {
        name
        description
        id
      }
    }
  }
}

Nodes give you access to a list of elements. For example here, we can retrieve a list of repository information.

They do require an argument that at least describes how many results. There is a limit of a 100 results, so keep that in mind.

Qualifying Results

{
  viewer {
    repositories(first: 2, orderBy: {field: CREATED_AT, direction: DESC}) {
      totalCount
      nodes {
        name
        description
        id
      }
    }
  }
}

There are a number of ways to qualify your results, so for example here, I'm asking for only the first two items ordered by the created date in descending order.

Edges

{
  viewer {
    repositories(first: 2, orderBy: {field: CREATED_AT, direction: DESC}) {
      totalCount
      edges {
        node {
          name
          description
          id
        }
      }
    }
  }
}

Paginating is done with a field called edges. You wrap the nodes with an edges request and then change the name of nodes to node.

Cursors

{
  viewer {
    repositories(first: 2, after: "Y3Vyc29yOnYyOpK5MjAyMC0xMi0zMVQyMDoxMDoyNi0wODowMM4TbQ-E", orderBy: {field: CREATED_AT, direction: DESC}) {
      totalCount
      edges {
        node {
          name
          description
          id
        }
        cursor
      }
      pageInfo {
        hasPreviousPage
        startCursor
        endCursor
        hasNextPage
      }
    }
  }
}

Cursors are unique identifiers in each
To paginate, you'll need to know some information about the current 'page'. To do that we can ask for the pageInfo field.

That will give you information about what wether there will be a page before or after this, as well as the beginning and ending cursors.