GraphQL - Query

> (World Wide) Web - (W3|WWW) > Web - (Web Service|Webservice) > GraphQL

1 - About

A query has the same function than a SQL request 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.

Advertising

3 - Structure

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

3.1 - Basic

  • Hero Id and Friends: One query for the hero, one query for the friends
fullNotation
query HeroNameQuery { // query = the schema's root query type (Optional if there is only one operation), HeroNameQuery  = operation name 
  hero {
    id
    name
    friends {
      id
      name
      friends {
        id
        name
      }
    }
  }
}
  • or because there is only one possible operation
shortNotation
{
  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"
          }
      }
    ]
  }
}

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

3.3 - Filtering

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

Response:

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

3.4 - 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

3.5 - 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"
  }
}

3.6 - 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"
  }
}
Advertising

3.7 - 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
    }
  }
}

3.8 - Built-in Fied

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

4 - Example

4.1 - Queries of the getting started tutorial

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

4.2 - 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
    }
  }
}