Why is counting GraphQL field usage from request document text unreliable?

## Selection is not resolution It is tempting to answer "who still uses this field?" by grepping request bodies, or by walking the AST of every document a server received. It is cheap, it needs no execution instrumentation, and it is wrong often enough to be dangerous - in both directions. A document is a *request* for fields. Execution decides which of those requests are actually carried out. Five mechanisms drive the two apart. ### 1. Conditional inclusion `@skip(if:)` and `@include(if:)` are executable directives evaluated during field collection, using the operation's variable values. A field guarded by `@include(if: $withHistory)` appears in the document text of every single request, and resolves only in the subset where the client passed `true`. Parsing text says the field is used constantly; it may in fact never have run in production. ### 2. Type conditions that do not match A selection inside a fragment - named or inline - with a type condition only executes when the runtime object satisfies that condition. Over a real-estate graph where `Property` is an interface implemented by `Listing` and `Rental`, a document that selects both variants has both in its text on every request, while any given object satisfies exactly one. ### 3. Branches never reached Execution walks down from the root. If `Query.listing` resolves to `null`, or a resolver raises a field error and the error propagates, every selection beneath it is abandoned: those coordinates are in the text and were never resolved. The same happens, less dramatically, when a list resolves empty - a document selecting `PriceChange.amount` under a listing with no recorded price changes resolves the parent list field and never the child. ### 4. Operations that never execute A request can be rejected before execution begins: a parse error, a validation error, a depth or cost limit, a failed authorization check, a rate limit. The text arrived; nothing ran. A text-based counter treats the rejected request exactly like a successful one. ### 5. You may not have the text When a client sends only a hash of a previously registered document, the server has an identifier and no document body on that request. A text-scraping collector either misses that traffic entirely or has to resolve every hash back to a stored document, which is a second system to keep correct. ## The interface question There is one place where text is not merely unreliable but genuinely less informative. When a document selects `address` on the interface `Property`, execution resolves that field against the concrete object type it found - `Listing.address` or `Rental.address`. The text records the abstract selection; execution records who really answered. That distinction matters directly: a field declared on an interface can only be removed once every implementer's coordinate is quiet, and only execution data tells you which implementers were involved. ## The one case text is better Execution-derived usage undercounts in exactly one situation, and it is worth naming because it is the situation where deleting on evidence would break someone. A field whose parent resolves to null for almost all data never resolves, so it reads as dead - while clients still *select* it, and their documents would fail validation the moment the field is removed from the schema. Recording the coordinates that validated documents selected, as a second and weaker signal, covers that gap. The rule of thumb: resolved coordinates tell you what is *being read*; selected coordinates in validated documents tell you what would *break*. ## What to collect instead Hook field resolution, build the coordinate from the parent type name and the field name, and add it to a per-request set. That single change removes every problem above at once: skipped fields never fire the hook, unmatched fragments never fire it, unreached branches never fire it, rejected operations never reach execution, and hashed documents execute exactly like any other. Aliases are handled for free, since the alias lives in the response key and never touches the field being resolved. The cost is real - the hook runs on every resolved field, and a deep document over a list that grew without a bound can resolve thousands of them - which is why the accumulator is a set rather than a counter, and why the coordinate string is best interned once at schema build time rather than concatenated per resolution.