Skip to main content

Query Extraction

This documentation isn’t up to date with the latest version of Gatsby.

Outdated areas are:

  • queries in dependencies (node_modules) and themes are now extracted as well
  • add meta key for hook in JSON in diagram

You can help by making a PR to update this documentation.

Extracting Queries from Files

Up until now, we have sourced all nodes into redux, inferred a schema from them, and created all pages. The next step is to extract and compile all graphql queries from our source files. The entrypoint to this phase is query-watcher extractQueries(), which immediately compiles all graphql queries by calling into query-compiler.js.

Query Compilation

The first thing it does is use babylon-traverse to load all JavaScript files in the site that have graphql queries in them. This produces AST results that are passed to the relay-compiler. This accomplishes a couple of things:

  1. It informs us of any malformed queries, which are promptly reported back to the user.
  2. It builds a tree of queries and fragments they depend on. And outputs a single optimized query string with the fragments.

After this step, we will have a map of file paths (of site files with queries in them) to Query Objects, which contain the raw optimized query text, as well as other metadata such as the component path and page jsonName. The following diagram shows the flow involved during query compilation

%0cluster_compilerquery-compiler.jsfragmentsfragments. e.g.cache/fragments/fragment1.jssrcFilessource files. e.gsrc/pages/my-page.jscomponentsredux.state.components(via createPage)fileQueriesfiles containing queriesfragments->fileQueriessrcFiles->fileQueriescomponents->fileQueriesschemaGatsby schemarelayCompilerRelay Compilerschema->relayCompilerbabylonparse files with babylonfilter those with queriesfileQueries->babylonqueryAstQueryASTsbabylon->queryAstqueryAst->relayCompilerqueriesQueriesfilePathqueryrelayCompiler->queriesquery{    name: filePath,    text: rawQueryText,    originalText: original text from file,    path: filePath,    isStaticQuery: if it is,    hash: hash of query} queries:query->query

Store Queries in Redux

We’re now in the handleQuery function.

If the query is a StaticQuery, we call the replaceStaticQuery action to save it to to the staticQueryComponents namespace which is a mapping from a component’s path to an object that contains the raw GraphQL Query amongst other things. More details in Static Queries. We also remove component’s jsonName from the components Redux namespace. See Page -> Node Dependencies.

If the query is just a normal every day query (not StaticQuery), then we update its component’s query in the redux components namespace via the replaceComponentQuery action.

%0cluster_watcherquery-watcher.js:handleQuery()compilerquery-compiler.jsquery{    name: filePath,    text: rawQueryText,    originalText: original text from file,    path: filePath,    isStaticQuery: if it is,    hash: hash of query} compiler->queryfor each compiled queryreplaceStaticQueryreplaceStaticQuery()query->replaceStaticQueryif static queryreplaceComponentQueryreplaceComponentQuery()query->replaceComponentQueryif not staticstaticQueryComponentsstaticQueryComponents (redux)replaceStaticQuery->staticQueryComponentscomponentscomponents (redux)replaceComponentQuery->componentsset `query` attribute

Queue for execution

Now that we’ve saved our query, we’re ready to queue it for execution. Query execution is mainly handled by page-query-runner.js, so we accomplish this by passing the component’s path to queueQueryForPathname function.

%0cluster_watcherquery-watcher.js:handleQuery()cluster_pageQueryRunnerpage-query-runner.jscompilerquery-compiler.jsquery{    name: filePath,    text: rawQueryText,    originalText: original text from file,    path: filePath,    isStaticQuery: if it is,    hash: hash of query} compiler->queryfor each compiled queryqueueQueryForPathnamequeueQueryForPathname()query->queueQueryForPathnamequeue for execution

Now let’s learn about Query Execution.

Edit this page on GitHub