GraphQL - Query

About

A query has the same function as a SQL query for a database but is written in a hierarchical format (ie GraphQL can nest queries, one by node).

A GraphQL query is a string interpreted by a server that returns data in a specified format.

Structure

For more info, see the language directory in GraphQL.js contains code implementing a specification-compliant GraphQL query language parser and lexer.

Basic

Hero Id and Friends: One query for the hero, one query for the friends

Full Notation

# query = the schema's root query type (Optional if there is only one operation)
# HeroNameQuery  = operation name 
query HeroNameQuery { 
  hero {
    id
    name
    friends {
      id
      name
      friends {
        id
        name
      }
    }
  }
}

Short Notation

when there is only one possible operation, you can use the short notation.

{
  hero {
    id
    name
    friends {
      id
      name
      friends {
          id
          name
      }
    }
  }
}

Example of responses

{
  "hero": {
    "id": "2001",
    "name": "R2-D2",
    "friends": [
      {
        "id": "1000",
        "name": "Luke Skywalker"
        "friends": [
          {
             "id": "2001",
             "name": "R2-D2"
          }
      },
      {
        "id": "1002",
        "name": "Han Solo"
        "friends": [
          {
             "id": "2001",
             "name": "R2-D2"
          }
      },
      {
        "id": "1003",
        "name": "Leia Organa"
        "friends": [
          {
             "id": "2001",
             "name": "R2-D2"
          }
      }
    ]
  }
}

Validation

When we query for fields, we have to query for a field that exists on the given type.
Whenever we query for an field that is not a scalar or an enum (ie object), we need to specify the child fields

The validation directory in GraphQL.js contains code implementing a specification-compliant GraphQL validator.

Filtering

Op id

query FetchLukeQuery {
  human(id: "1000") {
    name
  }
}

Response:

{
  "human": {
    "name": "Luke Skywalker"
  }
}

Parameters

A little bit the same as SQL - Parameter (Bind | Substitution) (Marker | Variable).

query FetchSomeIDQuery($someId: String!) {
  human(id: $someId) {
    name
  }
}

where $someId: String! is the parameter

It's known as Query Caching where the query parsing is cached (not the result)

Alias

A little bit the same as SQL - Alias.

query FetchLukeAndLeiaAliased {
  luke: human(id: "1000") {
    name
  }
  leia: human(id: "1003") {
    name
  }
}

{
  "luke": {
    "name": "Luke Skywalker"
  },
  "leia": {
    "name": "Leia Organa"
  }
}

Fragment (set of column)

A fragment represents a set of properties.

fragment HumanFragment on Human {
  name
  homePlanet
}

that you can use in a query with …

query UseFragment {
  luke: human(id: "1000") {
    ...HumanFragment
  }
  leia: human(id: "1003") {
    ...HumanFragment
  }
}

Response

{
  "luke": {
    "name": "Luke Skywalker",
    "homePlanet": "Tatooine"
  },
  "leia": {
    "name": "Leia Organa",
    "homePlanet": "Alderaan"
  }
}

Query fields of the root type (Sort of join)

A hero is a character (interface) that can be be a droid or a human. The primaryFunction is only a field of a droid.

When asking for hero's, we need to specify that the primaryFunction is a droid field with the fragment statement.

fragment DroidFields on Droid {
  primaryFunction
}
query DroidFieldInFragment {
  hero {
    name
    ...DroidFields
  }
}

or with less verbosity:

query DroidFieldInInlineFragment {
  hero {
    name
    ... on Droid {
      primaryFunction
    }
  }
}

Built-in Fied

__typename returns the type (not the type interface but the root type)

Example

Queries of the getting started tutorial

starWarsQuery-test.js contains the list of all test queries for the getting started tutorial.

Complex query example:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50)  {
      uri,
      width,
      height
    }
  }
}

Reponse:

{
  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}