It's often useful to ask a GraphQL schema for information about what queries it supports. GraphQL allows us to do so using the introspection system!
For our Star Wars example, the file starWarsIntrospection-test.js contains a number of queries demonstrating the introspection system, and is a test file that can be run to exercise the reference implementation's introspection system.
We designed the type system, so we know what types are available, but if
we didn't, we can ask GraphQL, by querying the
__schema field, always
available on the root type of a Query. Let's do so now, and ask what types
Wow, that's a lot of types! What are they? Let's group them:
Now, let's try and figure out a good place to start exploring what queries are available. When we designed our type system, we specified what type all queries would start at; let's ask the introspection system about that!
And that matches what we said in the type system section, that
Query type is where we will start! Note that the naming here
was just by convention; we could have named our
Query type anything
else, and it still would have been returned here had we specified it
was the starting type for queries. Naming it
Query, though, is a useful
It is often useful to examine one specific type. Let's take a look at
What if we want to know more about Droid, though? For example, is it an interface or an object?
kind returns a
__TypeKind enum, one of whose values is
we asked about
Character instead we'd find that it is an interface:
It's useful for an object to know what fields are available, so let's
ask the introspection system about
Those are our fields that we defined on
id looks a bit weird there, it has no name for the type. That's
because it's a "wrapper" type of kind
NON_NULL. If we queried for
ofType on that field's type, we would find the
ID type there,
telling us that this is a non-null ID.
appearsIn have no name, since they are the
LIST wrapper type. We can query for
ofType on those types, which will
tell us what these are lists of.
Let's end with a feature of the introspection system particularly useful for tooling; let's ask the system for documentation!
So we can access the documentation about the type system using introspection, and create documentation browsers, or rich IDE experiences.
This has just scratched the surface of the introspection system; we can query for enum values, what interfaces a type implements, and more. We can even introspect on the introspection system itself. The specification goes into more detail about this topic in the "Introspection" section, and the introspection file in GraphQL.js contains code implementing a specification-compliant GraphQL query introspection system.