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, Gatsby has 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 your 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, Gatsby 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

Gatsby is now in the handleQuery function.

If the query is a StaticQuery, Gatsby will call the replaceStaticQuery action to save it 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 can be found in the doc on Static Queries. Gatsby also removes a 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 Gatsby updates 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 Gatsby has saved your query, it’s ready to queue for execution. Query execution is mainly handled by page-query-runner.js, so it accomplishes this by passing the component’s path to queueQueryForPathname function.

%0cluster_pageQueryRunnerpage-query-runner.jscluster_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 queryqueueQueryForPathnamequeueQueryForPathname()query->queueQueryForPathnamequeue for execution

Now let’s learn about Query Execution.

Edit this page on GitHub
Docs
Tutorials
Plugins
Blog
Showcase