Tutorial

Introspection Queries With GraphQL

Published on April 23, 2017
author

Alligator.io

Introspection Queries With GraphQL

While we believe that this content benefits our community, we have not yet thoroughly reviewed it. If you have any suggestions for improvements, please let us know by clicking the “report an issue“ button at the bottom of the tutorial.

With GraphQL you can run introspection queries to learn about the available fields and types of a GraphQL schema. That introspection capability is also what gives GraphiQL the ability to provide documentation about the schema and autocompletion.

Let’s use the Star Wars SWAPI public API endpoint to run a few introspection queries against.

__type

First let’s run a query to enquire about the Film type using the built-in __type:

query FilmType {
  __type(name: "Film") {
    kind
    name
    fields {
      name
      description
      type {
        name
      }
    }
  }
}
  • Kind gives us the enum value for the type, like OBJECT, SCALAR or INTERFACE.
  • Name gives us the name of the type.
  • Description, well, gives us the description!

And here’s what the response looks like:

{
  "data": {
    "__type": {
      "kind": "OBJECT",
      "name": "Film",
      "fields": [
        {
          "name": "title",
          "description": "The title of this film.",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "episodeID",
          "description": "The episode number of this film.",
          "type": {
            "name": "Int"
          }
        },
        ...

Notice the use of the built-in __type (of type __Type) here to get information on the type of a particular object or interface.


Here’s another example using a fragment to learn even more about a particular type:

query LearnAboutFilm {
  __type(name: "Film") {
    ...AboutType
  }
}

fragment AboutType on __Type {
  fields {
    name
    description
    args {
      name
      description
    }
  }
  interfaces {
    name
    description
  }
  inputFields {
    name
    description
  }
  possibleTypes {
    kind
    name
    fields {
      name
      description
      type {
        kind
        name
        description
      }
    }
  }
}

__schema

With __schema we can ask the server about the schema itself. Let’s look at an example:

query LearnAboutSchema {
  __schema {
    types {
      name
      kind
    }
    queryType {
      fields {
        name
        description
      }
    }
  }
}

And the response:

{
  "data": {
    "__schema": {
      "types": [
        {
          "name": "Root",
          "kind": "OBJECT"
        },
        {
          "name": "String",
          "kind": "SCALAR"
        },
        {
          "name": "Int",
          "kind": "SCALAR"
        },
        ...
        "queryType": {
        "fields": [
          {
            "name": "allFilms",
            "description": null
          },
          {
            "name": "film",
            "description": null
          },
          ...

__typename

__typename can be used as part of regular queries to enquire about the type of a particular field:

query LearnAboutFilm {
  allFilms {
    films {
      __typename
      title
    }
  }
  film (id: "ZmlsbXM6Mw==") {
    __typename
    title
  }
  starship(id: "c3RhcnNoaXBzOjc1") {
    __typename
    name
    model
  }
}

And here’s the response:

{
  "data": {
    "allFilms": {
      "films": [
        {
          "__typename": "Film",
          "title": "A New Hope"
        },
        {
          "__typename": "Film",
          "title": "The Empire Strikes Back"
        },
        ...
      ]
    },
    "film": {
      "__typename": "Film",
      "title": "Return of the Jedi"
    },
    "starship": {
      "__typename": "Starship",
      "name": "V-wing",
      "model": "Alpha-3 Nimbus-class V-wing starfighter"
    }
  }
}

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about our products


About the authors
Default avatar
Alligator.io

author

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
Leave a comment


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Featured on Community

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel