Introspection | GraphQL (original) (raw)

Learn how to query information about a GraphQL schema

It’s often useful to ask a GraphQL schema for information about what features it supports. GraphQL allows us to do so using the introspection system.

Introspection queries are special kinds of queries that allow you to learn about a GraphQL API’s schema, and they also help power GraphQL development tools. On this page, we’ll learn how to run different queries to learn more about an underlying schema’s types, fields, and descriptions.

Type name introspection

We have already seen an example of introspection on the Schemas and Types page. When querying a field that returned Union type, we included the meta-field directly in a selection set to get the string value of the names of the different types returned by a search query. Let’s look at this example again:

We didn’t add the field to our GraphQL API explicitly—the GraphQL specification says that it must be provided to clients by a GraphQL implementation. This field can be queried for any field with an Object, Interface, or Union type as the underlying output type.

Schema introspection

Introspection can do more than provide type names in a query. If you designed the type system for a GraphQL API, then you’ll likely already know what types are available. But if you didn’t design it, you can ask GraphQL by querying the field, which is always available on the root operation type.

Let’s do so now and ask what types are available in the Star Wars schema:

Wow, that’s a lot of types! What are they? Let’s group them:

Now, let’s try to 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:

The result matches what we said in the type system section—that the type is where we will start. Note that the naming here was just by convention; we could have named our type anything else, and it still would have been returned here had we specified it was the starting type for queries. Naming it , though, is a useful convention.

It is often useful to examine one specific type. Let’s take a look at the type:

But what if we want to know more about Droid? For example, is it an Interface or Object type?

returns a Enum type, one of whose values is . If we asked about instead we’d find that it is an Interface type:

It’s useful for an Object type to know what fields are available, so let’s ask the introspection system about :

Those are the fields that we defined on !

looks a bit weird there, it has no name for the type. That’s because it’s a wrapper type of kind . If we queried for on that field’s type, we would find the type there, telling us this is a non-null ID.

Similarly, both and have no name, since they are the wrapper type. We can query for on those types, which will tell us what types are inside the list:

Let’s end with a feature of the introspection system particularly useful for tooling; let’s ask the system for documentation:

As demonstrated above, 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 type values, what Interface types another type implements, and more. We can even introspect on the introspection system itself.

To see an example of a specification-compliant GraphQL query introspection system implemented in code, you can view src/type/introspection.ts in the reference implementation.

Introspection in production

Introspection is a useful feature of GraphQL, especially for client developers and tooling. However, for APIs intended only for your own applications, it’s typically not needed in production—required operations are usually baked into these applications at build time, making runtime introspection unnecessary.

Disabling introspection in production is common in order to reduce the API’s attack surface. This is often part of a broader API security strategy, which may also include authentication and authorization, operation safe-listing (or a range of alternative protections, such as depth-limiting, breadth-limiting, alias limits, cycle rejection, cost analysis, etc.), execution timeouts, and more.

Next steps

To recap what we’ve learned about introspection:

Now that you’ve explored the GraphQL type system, how to query data from an API, and what the lifecycle of a request looks like, head over to the Best Practices section to learn more about running GraphQL in production.

ResponseBest Practices