Discover a remote schema
A schema-aware client needs to learn an endpoint’s available types and fields before generating requests.
GraphQL · Function
getIntrospectionQuery
getIntrospectionQuery returns a standard GraphQL query string that asks an endpoint for schema metadata. Clients can send it to discover the API’s types, fields, descriptions, and other introspection information.
How it works
getIntrospectionQuery creates a GraphQL query document that requests schema metadata through the introspection system. A client can send the resulting string to an endpoint and use the response with GraphQL tooling, such as schema construction or code generation.
Syntax
getIntrospectionQuery(options?: IntrospectionOptions): stringReturns
A GraphQL query string for retrieving schema information through introspection.
Key points
- The function produces a query for GraphQL’s built-in schema-introspection mechanism.
- Generated introspection documents are commonly useful to tooling that analyzes or presents a schema.
- The query can retrieve the schema through the
__schemafield on the query root. - The returned data can describe schema elements rather than application records.
- The standard query covers broad metadata, while GraphQL’s introspection system supports additional schema details.
Common mistakes
- The generated document is intended for schema discovery, not ordinary application data fetching.
Example: Fetch and build a client schema
import { getIntrospectionQuery, buildClientSchema } from "graphql";
const query = getIntrospectionQuery();
const response = await fetch("https://example.com/graphql", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ query }),
});
const { data } = await response.json();
const schema = buildClientSchema(data);
console.log(schema.getQueryType()?.name);Builds the standard introspection document, sends it to a GraphQL endpoint, and converts the returned introspection data into a client schema.
When to use it
Power GraphQL tooling
Development tools need server metadata to provide autocomplete, validation, documentation, or schema exploration.
Generate client artifacts
A build step needs server schema data to construct a client schema or generate typed artifacts.
Interview questions
QWhat does getIntrospectionQuery do?
It generates a standard GraphQL introspection query as a string. That query asks the server for schema information, including types, fields, and descriptions, through the introspection system.
Follow-up: What server field does the query ultimately use? The schema is exposed through the __schema field on the query root, with related metadata available through introspection types.
QHow is the generated query used?
The returned query can be posted to a GraphQL endpoint like any other query. Its response contains schema metadata that client-side tools can inspect or convert into a usable schema representation.
Follow-up: Why is this useful for tooling? Introspection queries help power GraphQL development tools by exposing the API’s supported schema features.
QWhat deployment limitation should you consider?
Introspection is not guaranteed to be available in every deployment. Some first-party GraphQL APIs disable introspection outside development, so an introspection-based client must handle rejection or use another schema distribution approach.
Follow-up: Does disabling introspection fully hide the schema? No; the documentation describes it as security through obscurity and recommends broader controls such as trusted documents and authorization.
Related
__schema__type__typename__Schema__Type__TypeKind__Field__InputValue