What optimizations does GraphQL afford?

[abaco]

I'm reviewing Gatsby for my employer, and I have a question that I can't reply on my own. I've read all I could find about GraphQL in the docs, as well as issues #420 and and #4994, and found this remark from @KyleAMathews:

I wanted a way for users to declaratively specify (aka write a query) for what data a page component needs as there's a ton of optimizations we can do because of this

My question is: what optimizations have been implemented / planned, and in general what kind of optimizations are possible?

[sidharthachatterjee]

@abaco Good question. One of the biggest benefits of GraphQL is the fact that it prevents both under-fetching and over-fetching. What this means is that the data that is present in your site's bundle ends up only being the keys you specify in your GraphQL queries (which you use in your components). This prevents the common issue where we tend to load more data than what is used in web projects, leading to a slowdown in load times etc

The other advantage (not an optimisation per se) that GraphQL affords in Gatsby specifically is that it enables fetching data from multiple services or data formats (via plugins) in a conveniently coherent way. You don't need to write API calls for respective APIs of services for data that you'd like to use at build time. They are all available (via gatsby and its plugins) in GraphQL. This makes access to data simpler as well.

Hope this helps!

[herecydev]

Say for some reason you need the first and last elements of an array: you can't express that in GraphQL.

I don't think thats true. GraphQL doesn't do much out the box but it allows for custom directives to be added, so you could easily build one that resolves the first and last elements. Granted, it's not infinitely flexible but it's often simple enough where it needs to be

I think the motiviation is to have a declarative, well-understood way of data-fetching. Designing a custom API like you've suggested is possible, but it presents yet another barrier for learning a framework. I'm not sure what optimizations graphQL is specficially affording though

[abaco]

I think the Gatsby team should take a hard look at the role of GraphQL within the framework. I’ve spent a lot of time examining this matter and, frankly, I came to the conclusion that adopting GraphQL was a mistake.

As users we aren’t provided with a well articulated rationale for why GraphQL was introduced. Instead, the documentation conflates GraphQL with the data layer, listing as advantages of the former what are actually features of the latter. Elsewhere we’re explained that opting out of GraphQL prevents us from using many other useful features of Gatsby, but this just tells how Gatsby is structured, not why. As a result we aren’t able to judge whether the use of GraphQL involves a trade-off that’s good for us.

One should think twice before replacing JavaScript with a special-purpose language like GraphQL, but you don’t seem to have really thought through it once. The argument that GraphQL is a well understood way of querying data, almost a de-facto standard, is weak because GraphQL was created to minimize the number of requests and their payloads when querying a remote database, while Gatsby’s database is local. The documentation even touts the uniqueness of Gatsby’s approach to querying a local db, implicitly admitting that for that use case the default choice is a different one - namely, JavaScript. However the JavaScript route was apparently never considered.

As for the optimizations that are possible with GraphQL, I think they were never implemented. And that’s perfectly fine, because there’s really no point in optimizing queries against a local, in memory database, not to mention that they’re only run at build time.

Gatsby users routinely run into issues connected to the use of GraphQL. The question is: is it worth it? If there are specific advantages to the GraphQL language compared to JavaScript they should be discussed in the documentation, so that beginners would be better able to understand what they’re signing up to. If instead the advantages are not so clear it may be worth to add a JavaScript API for querying the local database alongside the current GraphQL interface. Source plugins wouldn’t need to be touched, while transformer plugins would probably require some adaptations.

[herecydev]

because GraphQL was created to minimize the number of requests and their payloads when querying a remote database, while Gatsby’s database is local

That's true the advantage of minimising requests isn't relevant. Whether you use graphql or you pass a JS object, a single request will still be made during hydration. However the advantage of minimising the size of the request is there. Consider the following:

createPage({
  path: "/",
  component: someComponent
  context: {
    massiveArray: [],
    bigObject: {}
  },
})

If the object was massive, Gatsby has no choice but to request all of this as props (as it has no understanding what's used and what isn't). In the case of graphQL it's baked into the design of the language to prevent this happening.

One should think twice before replacing JavaScript with a special-purpose language like GraphQL

Nobodys forcing this, you can happily pass pure javascript objects if you feel that's best. You can also fetch data at runtime as well. Gatsby has a number of tools to make static site rendering leaner and efficient but you don't have to use them if it's not appropriate.

If instead the advantages are not so clear it may be worth to add a JavaScript API for querying the local database alongside the current GraphQL interface

Maybe it's worth putting an RFC together if you feel strongly enough that it delivers value. In any case, relevant to the comment above you could do this already (even if Gatsby doesn't support this). You could put together a plugin that uses onCreatePage and then calls this new "javascript api" and pulls out the right data for the page.

[abaco]

@herecydev You're making the same comparison as in Gatsby without GraphQL, namely data-layer-cum-GraphQL vs. no data layer. I'm aware of the positive sides of the data layer, from the many source plugins to live-reloading, but I don't see them as necessarily linked to GraphQL. In short, I'd like to use the data layer without GraphQL.

When did GraphQL become shorthand for data layer? That's not helpful. For instance that article should be titled Gatsby without the Data Layer, because that's actually what it discusses. This conceptual confusion hides the fact that GraphQL is logically independent from the rest of Gatsby's architecture. You could have source plugins without GraphQL. You could have live-reloading without GraphQL. You could prevent over-fetching without GraphQL. Whether it would be better to do all those things without GraphQL is a different question, but one that deserves to be considered carefully.

For the sake of the argument I alluded at the possibility to query data through a JavaScript API. My very rough idea is to replace a page query like:

export const query = graphql`
  query {
    site {
      siteMetadata {
        title
      }
    }
  }
`

with a JavaScript function like:

export const query = (store):  => {
  return selectFromStore(store, {
    site: select({
      siteMetadata: select('title')
    })
  });
};

where select returns an operation on a node (i.e. a special object), and selectFromStore returns a plain object with the result of the query.

This would enable nested queries and data transformations like so:

import { blogQuery } from '../components/Blog';
import { myTransformation } from '../data-processing';

// ...
// Page component here
// ...

export const query = (store) => {
  const results = selectFromStore(store, {
    site: select({
      siteMetadata: select('title')
        .transform((t) => t.toUppercase()), // transform single field
      blogContent: blogQuery('content') // imported query instead of fragment
    })
  });

  // transform whole tree
  const resultsWithFluidImages = processDataSharp(sharpConfig, results); 
  const resultsWithCustomTransformation = myTransformation(resultsWithFluidImages);

  return resultsWithCustomTransformation;
};

This is admittedly very fuzzy. I also doubt I'll make an RFC any time soon, because I don't know much about Gatsby's internals.

In any case I'd like this discussion to remain at the abstract level, not my specific needs or the specific alternative I just quickly threw together.

[herecydev]

What you're suggesting above is reasonable but is tied entirely to Gatsby. So it presents another barrier to learning. If you have a solution that solves:

• Easy to learn (preferably already learnt outside of Gatsby)
• Performant
• Prevents over-fetching (in turn performance, seo, etc)
• ....

Then definitely create an RFC. Right now it seems that you're suggesting a few Gatsby specific helper functions that can leveraged, but that's more stuff that people will have to learn and reason with. See here why that's a big problem.

[vladar]

and in general what kind of optimizations are possible?

Some examples of what's possible:

1. Declarative data requirements may help us to eventually switch to lazy sourcing mode (for develop and per-page builds). By analyzing your page query we can figure out which data this page needs before we actually have this data available in the local storage. Then we can ask source plugins to source data required for this page only (and postpone sourcing everything else).

2. Someday we may have Gatsby GraphQL available as a remote service as well. In this case, all the network-related benefits of GraphQL will be also important.

3. We can hook external GraphQL APIs into Gatsby schema and provide a unified querying interface for those. We do this already with gatsby-source-graphql but at the moment it acts like a proxy at the query step (not the source nodes step).

4. Declarative queries enable efficient "live" queries. Say, a new node is sourced - you can match this node against registered queries and just update results of the matching queries without re-running all of those. Could be useful for near real-time incremental re-builds. This is somewhat similar to KSQL (but there are also other similar projects).

This is just what immediately came to mind. Also, to clarify: I partially agree with your attitude on this topic and currently we don't utilize the power of declarative queries and schema to its full capacity.

But also as @herecydev mentioned - JavaScript API for data-querying will likely be unique to Gatsby. So it won't help much with the learning curve + this learning will be only useful for Gatsby projects.

[abaco]

Thanks @vladar, that's really helpful! Now I can see how GraphQL fits in your vision for Gatsby.

I hope I didn't upset anybody, and that this information will be useful to other Gatsby users and contributors.