What does an in-browser GraphQL explorer read to build its docs pane and autocomplete?
answer
- The pane is not reading a file on disk
- One request, at tab load
- Meta-fields that start with a double underscore
- __schema and __type feed all of it
- Shape and prose only, never behaviour
basics
~20 sAn introspection response from the same endpoint, fetched once when the tab loads. Every type, field, argument, default value and description shown in the docs pane and offered by the completion list comes from that single reply.
solid answer
~50 sAn interactive explorer is an ordinary HTTP client with no privileged channel to the server. On load it sends one introspection document built from the `__schema` and `__type` meta-fields, and the result — every type, its fields, their argument names and default values, the nullability and list modifiers, and the description strings the schema author wrote — is the entire source for the docs pane and for as-you-type completion. Completion is then computed locally: the explorer tracks which type is in scope at the cursor and offers that type's fields from the cached introspection result, with no request per keystroke. Two consequences matter in practice. The pane is a snapshot, so a schema deployed after the tab opened is invisible until it refetches. And introspection carries shape and prose only — never whether your credentials may resolve a field, what it costs, or how fresh its value is.
code
graphql · 17 linesquery ExplorerBootstrap {
__schema {
queryType { name }
mutationType { name }
types {
kind
name
description
fields {
name
description
args { name type { name } defaultValue }
type { kind name ofType { kind name } }
}
}
}
}go deeper
Be ready to say the words: the explorer runs an introspection query against the same endpoint, and the docs pane and completion are rendered from that response. Knowing the meta-field names __schema and __type is enough at this level.
Explain the mechanics: one request at load, held for the tab, completion computed locally from the type in scope at the cursor. Be able to walk the __Type / __Field shape and explain how ofType transmits list and non-null modifiers.
Show the diagnostic instinct. When someone reports a missing or phantom field, your first two questions are whether the tab has refetched and which environment it points at. Be clear that introspection carries no authorization, cost or freshness information at all.
Own the consequence for the platform: an explorer is the schema's default documentation, so description quality and deprecation reasons are a product decision, not a nicety. Decide deliberately which environments answer introspection and what developers use where it is off.
## The explorer is just another client Nothing in the GraphQL specification describes an explorer, a docs pane or a completion list. What the specification does define is **introspection**: a small set of meta-fields, available on every schema, that let a client ask the server to describe itself using GraphQL itself. An explorer is built entirely on top of that. It opens the same endpoint your application opens, over the same HTTP, with no back door and no special file access. If you can run an introspection document with a plain HTTP client, you have everything the explorer has. The meta-fields are `__schema` (available on the query root), `__type(name: String!)` (also on the query root), and `__typename` (available on every object, interface and union). `__schema` yields the root operation types, the full list of types in the schema, and the directive definitions. Each type in that list is a `__Type` carrying its `kind` (`OBJECT`, `INTERFACE`, `UNION`, `ENUM`, `INPUT_OBJECT`, `SCALAR`, `LIST`, `NON_NULL`), its `name`, its `description`, its `fields`, its `interfaces`, its `possibleTypes` and its `enumValues`. Each field is a `__Field` with a `name`, a `description`, its `args`, its `type`, and the `isDeprecated` / `deprecationReason` pair. Type references nest through `ofType`, which is how `[Track!]!` is transmitted: a `NON_NULL` wrapping a `LIST` wrapping a `NON_NULL` wrapping the named type. That is the whole feed. A docs pane is a rendering of it; the description text you read is the string literal the schema author wrote above the definition in SDL, carried verbatim in the `description` field. ## Why completion feels instant Because it is local. When the cursor sits inside a selection set, the explorer knows which type is in scope — it parsed your document and walked from the root operation type down through the fields you already selected — and it lists that type's fields from the introspection result it already has. No keystroke reaches the server. This is worth being able to say out loud in an interview, because it explains a whole family of behaviour: completion works with the network tab silent, it works while the backend databases are down, and it keeps happily offering a field the server no longer has. ## The snapshot problem, in one incident A music catalogue graph has a `Release` type with 37 fields. A colleague ships a change that removes `Release.masteringNotes` and adds `Release.credits`. Your explorer tab has been open since the morning. The docs pane still documents `masteringNotes` in full, completion still offers it, and running a document that selects it now comes back with an error — while `credits`, which does exist, is not offered at all and is underlined as unknown. Nothing is broken. The pane is serving stale data about the schema for exactly the reason any cache serves stale data: the copy was taken at a moment in the past and nothing has invalidated it. Refetching the schema — reloading the tab, or using the explorer's refresh control — fixes it. When a colleague reports "the explorer says this field doesn't exist", *reload first* is the correct first question, followed by *which environment is the tab pointed at*. ## What the pane can never tell you This is the half of the answer that separates a candidate who has used an explorer from one who has thought about it. Introspection describes the **type system**. It says nothing about behaviour: - **Authorization.** The pane documents every field in the schema. Whether the identity on your request may resolve one of them is decided during execution, by logic introspection cannot see. - **Cost.** Nothing in the response says a field triggers one cheap lookup or a fan-out across several backends. A one-word field can be the most expensive thing in the graph. - **Freshness.** Nothing distinguishes a value read live from one served from a cache. - **Failure modes.** You can see that a field is declared `String!` and therefore cannot be null; you cannot see under what conditions it errors. - **Limits.** Depth caps, cost caps, rate limits and document allowlists are all invisible to introspection, which is why a document that runs here can still be rejected in production. One operational caveat rounds this out: a deployment that does not answer introspection outside development leaves an explorer with an empty pane and dead completion, even though the endpoint still executes ordinary documents perfectly well. The explorer degrades to a plain request box, because the pane was never anything more than a rendering of a reply it can no longer get.
- A colleague deployed a new field an hour ago and the explorer's completion list still doesn't offer it. What do you check first?Whether the tab has refetched the schema since the deploy. The introspection result is fetched on load and held for the tab, so completion and the docs pane keep describing the schema as it was at that moment. Reload or use the refresh control. If the field is still absent afterwards, check which environment the endpoint URL points at — an explorer aimed at a staging deployment describes a different schema entirely.
- Name three things the docs pane can never tell you about a field it is happily documenting.Whether the identity on your request is permitted to resolve it, what resolving it costs in backend work, and how fresh the value will be. Introspection transmits the type system — names, kinds, arguments, defaults, nullability and description prose — and nothing about execution behaviour. Depth and cost limits, document allowlists and rate limits are invisible to it too, which is why passing here is not a promise about production.
- The docs pane shows no descriptions at all for a whole set of types. Whose problem is that?The schema authors'. Descriptions are string literals written above definitions in SDL; introspection carries them in the `description` field and the explorer renders whatever arrives. An empty pane means the definitions were written without descriptions, not that the explorer failed to fetch them. The fix belongs in the schema source, and it is the kind of rule teams enforce automatically rather than by review.
The docs pane is a photograph of the schema taken the moment the tab opened, not a live window onto it — everything in the frame was true then, and stays in the frame until you take another picture.
saying these in an interview costs you the question
- Says the explorer reads an SDL file from the server's disk
- Thinks completion sends a request on every keystroke
- Believes the docs pane shows only fields your identity may access
- Assumes the pane updates itself the instant a schema deploys
- Claims introspection reveals a field's cost or data freshness