Query extraction

The first step in the process is query extraction, which involves the extraction and validation of all GraphQL queries found in Gatsby pages, components, and templates. At this point in the build process, Gatsby has finished creating all the nodes in the associated Redux namespace, inferred a schema from those nodes, and completed page creation. Next, it needs to extract and compile every GraphQL query present in your source files. In the Gatsby source code, the entry point to this step in the process is extractQueries in src/query/query-watcher.js, which compiles each GraphQL query by invoking the logic in src/query/query-compiler.js.

TIP

For a diagram illustrating the flow involved in query compilation, consult the Gatsby documentation’s guide to query extraction. For more information about the libraries involved in this step, consult the Babel and Relay documentation for babylon-traverse and relay-compiler, respectively.

The query compiler’s first step is to utilize babylon-traverse, a Babel library, to load every JavaScript file available in the Gatsby site that contains a GraphQL query, yielding an abstract syntax tree (AST; a tree representation of source code) of results that are passed to the relay-compiler library. The query compilation process thus achieves two important goals:

• It lets Gatsby know if there are any malformed or invalid queries, which are immediately reported to the user.
• It constructs a tree of queries and fragments depended on by the queries and outputs an optimized query string containing all the relevant fragments.

Once this step is complete, Gatsby will have access to a map of filepaths (namely of site files containing queries) to individual query objects, each of which contains the raw optimized query text from query compilation. Each query object will also house other metadata, such as the component’s path and the relevant page’s jsonName, allowing it to connect the dots between the component and the page on which it will render.

NOTE

For more information about how Gatsby establishes dependencies between pages and nodes during this stage, consult the Gatsby documentation’s guide to page → node dependency tracking.

Next, Gatsby executes the handleQuery function in src/query/query-watcher.js. If the query being handled is a StaticQuery, Gatsby invokes replaceStaticQuery to store it in the staticQueryComponents namespace, which maps each component’s path to an object containing the raw GraphQL query and other items. In the process, Gatsby also removes the component’s jsonName from the components Redux namespace.

On the other hand, if the query is a non-StaticQuery, Gatsby will update the relevant component’s query in the Redux components namespace by calling the replaceComponentQuery action. The final step, once Gatsby has saved each query under its purview to Redux, is to queue the queries for execution. Because query execution is primarily handled by src/query/page-query-runner.ts, Gatsby invokes queueQueryForPathname while passing the component’s path as a parameter.

TIP

For diagrams illustrating the flows involved in storing queries in Redux and queuing queries for execution, consult the query extraction guide in the Gatsby documentation.