Enhance customer experiences with Apollo GraphOS


<p>When building complex applications today, Apollo Client users typically reach for <code>useQuery</code> to get data to their components. This is no surprise as this is considered a <a href="https://www.apollographql.com/docs/react/data/operation-best-practices#query-only-the-data-you-need-where-you-need-it">best practice</a> by the Apollo Client documentation. However, this can cause challenges while trying to minimize over-fetching while maintaining a clear separation of concern.</p>



<p>During my time at <a href="https://redshelf.com/" data-type="link" data-id="https://redshelf.com/" target="_blank" rel="noreferrer noopener">RedShelf</a>, a leader in the Higher EdTech space, I’ve been an advocate for Apollo’s best practices including “query only the data you need, where you need it.” However, this led to over-fetching because we naturally pushed our queries (a.k.a. network requests) as far down the component tree as possible, in most cases usually to the individual components.</p>



<p>Enter the power of the <a href="https://www.apollographql.com/docs/react/data/fragments/#usefragment">useFragment</a> hook and <a href="https://www.apollographql.com/docs/react/data/fragments#colocating-fragments">colocated fragments</a>. Combining these two techniques have enabled us to separate accountability from responsibility, remaining aligned with Apollo’s best practice while optimizing our client application’s fetching strategies along the way.</p>



<h2 class="wp-block-heading"><a href="#exploring-colocated-fragments" aria-hidden="true" class="aal_anchor" id="exploring-colocated-fragments"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Exploring Colocated Fragments</h2>



<p>Colocated fragments are not a new concept and, in fact, they <a href="https://relay.dev/docs/tutorial/fragments-1/">are one of the distinguishing features of Relay</a>. Essentially, colocated fragments move the responsibility of declaring data needs from parents to children further decoupling the two. Although a step in the right direction, they still require parent components to provide fragmented data through React props, or components that have defined their own data needs to manually access the Apollo Client cache.</p>



<p>However, with the introduction of the <code>useFragment</code> hook, we can now leverage the benefits of colocated fragments with the simplicity of accessing the fragmented data via a streamlined hook.</p>



<h2 class="wp-block-heading"><a href="#understanding-apollos-usefragment-hook" aria-hidden="true" class="aal_anchor" id="understanding-apollos-usefragment-hook"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Understanding Apollo&#8217;s <code>useFragment</code> Hook</h2>



<p>A clear separation between accountability and responsibility in data fetching is important. While components should be responsible for declaring the data they need, they shouldn&#8217;t necessarily be accountable for fetching it. This is where the <code>useFragment</code> hook shines.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="472" src="https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1024x472.png" alt="A diagram showing a parent component and child components.  The child components each contain a useFragment call with fragments named ProductBrand, ProductImage, and ProductDetails.  The parent component contains a useQuery call with a query that spreads each of the aforementioned fragments.  The parent component is annotated with &quot;Accountable for fetching data&quot; and the child components are annotated with &quot;Responsible for declaring data needs&quot;" class="wp-image-23693" srcset="https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1024x472.png 1024w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-300x138.png 300w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-768x354.png 768w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1536x708.png 1536w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-2048x943.png 2048w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1200x553.png 1200w, https://wp.apollographql.com/wp-content/uploads/2024/04/fragment-architecture1-1980x912.png 1980w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow">
<p>This article mainly focuses on mitigating over-fetching and improving code maintainability, but the <code>useFragment</code> hook provides other performance gains, too, like handling re-renders more efficiently. Read more about it in <a href="https://www.apollographql.com/blog/introducing-apollo-clients-nonreactive-directive-and-usefragment-hook">this Apollo blog post</a>.</p>
</blockquote>



<p>Introduced in <a href="https://github.com/apollographql/apollo-client/releases/tag/v3.7.0">Apollo Client 3.7</a> and stabilized in <a href="https://github.com/apollographql/apollo-client/releases/tag/v3.8.0">3.8</a>, the <code>useFragment</code> hook enables components to directly access fragment data from the normalized cache.</p>



<p>This not only helped our team stay true to Apollo’s best practice of querying only necessary data, but also helped solve some of the over-fetching we were doing by following the best practice in the first place.</p>



<h2 class="wp-block-heading"><a href="#integration-into-the-teams-applications" aria-hidden="true" class="aal_anchor" id="integration-into-the-teams-applications"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Integration into the Team&#8217;s Applications</h2>



<p>The first place we leveraged colocated fragments and the <code>useFragment</code> hook was to refactor a “Product Details” drawer within one of our applications where over-fetching had become a major problem. When the drawer mounted, it sent 9 network requests(!) &#8211; one for each component &#8211; because they were responsible for declaring AND accountable for fetching their data.</p>



<p>By associating colocated fragments and replacing <code>useQuery</code> with <code>useFragment</code> in every component, we were able to reduce the network requests count from 9 to 2 within the drawer. The only thing that kept us from only needing a single network request was some of the data required a network-only fetch policy.</p>



<p>Since then, we’ve propagated this pattern throughout our client applications, reducing over-fetching without compromising data requirements. This technique has been truly transformative for our team, improving the performance of our applications and enhancing the maintainability of our codebases.</p>



<h2 class="wp-block-heading"><a href="#lessons-learned" aria-hidden="true" class="aal_anchor" id="lessons-learned"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Lessons Learned</h2>



<p>While challenges are inevitable when adopting new patterns, we couldn’t have made the progress we did in the timeframe we did without the help and support from the <a href="https://events097286.typeform.com/joincommunity">Apollo Supergraph Champions community</a>.</p>



<p>For example, while replacing the <code>useQuery</code> hooks in each component with the <code>useFragment</code> hook, we weren’t receiving the fragmented data we were expecting. After trying a few approaches, we reached out to the Apollo community channel and had a great conversation with <a href="https://www.linkedin.com/in/adamluikart/">Adam Luikart</a>, a Principal Software Engineer at Indeed, who helped us realize we needed to pass the same exact variables we passed to <code>useQuery</code> to the <code>useFragment</code> hook or it won’t have a valid way to locate the data in the cache.</p>



<p>Thanks to that conversation, our team gained a deeper understanding of the inner workings of the Apollo Client cache and a working example that led to the eventual buy-in and integration of colocated fragments and the <code>useFragment</code> hook into our pattern library.</p>



<h2 class="wp-block-heading"><a href="#takeaways" aria-hidden="true" class="aal_anchor" id="takeaways"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Takeaways</h2>



<p>Apollo’s maxim of “query only the data you need, where you need it” is a great starting point.&nbsp; But certain component structures can result in more network calls than is needed. When we used the new <code>useFragment</code> hook in Apollo Client, though, we were able to stay true to the principle behind that best practice while reducing the number of fetches in our app.</p>



<p>By embracing this pattern, our team effectively separated the responsibility and accountability for data requirements.&nbsp; This helped us control the total demand on our network and enhance the end user experience without compromising our architecture.</p>


Optimizing Data Fetching with Apollo Client: Leveraging useFragment and Colocated Fragments


<p>Apollo Client 3.9 is out in beta now, and it fixes various memory leaks, adds granular control over internal cache sizes, and deprecates the canonizeResults option due to a conceptual and non-fixable memory leak associated with it.</p>



<p>We want your help to find the correct default cache sizes &#8211; see the last paragraph for details on that.</p>



<h2 class="wp-block-heading"><a href="#the-memory-story" aria-hidden="true" class="aal_anchor" id="the-memory-story"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>The memory story</strong></h2>



<p>Sometimes, in an open source project, you have that issue that sticks around for a long time because it&#8217;s not clear how you would tackle it.</p>



<p><a href="https://github.com/apollographql/apollo-client/issues/7942">Apollo Client Issue #7942</a> was undoubtedly one of those tickets.</p>



<p>A user had reported a memory leak, and the maintainer at the time put out a fix. This likely saved someone else from a memory leak but, unfortunately, did not help that specific user.</p>



<p>As maintainers, oftentimes, our hands are bound to figure out how to proceed. We can only stare at heap dumps so long before we would need access to the user&#8217;s Kubernetes cluster and &#8220;play&#8221; with the live production system that is seeing the issue.&nbsp;</p>



<p>Of course, that&#8217;s not feasible.</p>



<p>As a result, <a href="https://github.com/apollographql/apollo-client/issues/7942">issue #7942</a> stayed around for a while. Because it was an issue that described a memory leak, other users started reporting memory leaks there, too. Because a memory leak is a memory leak, right? In most cases, we&#8217;ll never know if those users saw the same memory leak. It&#8217;s not very likely.&nbsp;</p>



<p>Eventually, the original user reported that upgrading to Apollo Client 3.6.0 in combination with following another user&#8217;s recommendation to call <code>cache.gc()</code> fixed the memory leak.&nbsp;</p>



<p>This would have been a good moment to close the issue since the original problem had been fixed &#8211; but because the issue now contained a lot of reports of different memory leaks, it stayed open.</p>



<p>Some users found new memory leaks and gave each other tips on avoiding them &#8211; which was great for those users, but unfortunately, we didn&#8217;t get a reproduction for any of those issues so they were really hard to investigate.</p>



<p>This issue was a constant reminder that something might be wrong somewhere, but we had no way of reproducing the issue and no access to any of those users&#8217; code bases.</p>



<p>This fall, we set time aside to start a memory-themed spike &#8211; hunting for memory leaks that we could not locally reproduce previously. With artificially scaling benchmarks, hundreds of megabytes of heap dumps, and Facebook&#8217;s handy<a href="https://facebook.github.io/memlab/"> memlab</a> tool, we finally found and fixed many of them. But even when these tools wouldn&#8217;t produce any more signs of memory leaks, we had that lingering feeling that we were not done yet.&nbsp;</p>



<p>So we did the next reasonable thing: We read the whole source code, with a particular focus on any usage of internal data structures we frequently used for memoized results. That uncovered some more potential memory leaks.</p>



<p>Last Monday (December 18, 2023), we shipped Apollo Client 3.9 beta. This release contains over 20 memory-related pull requests, which not only fixes memory leaks, but also deprecates a feature, adds new configuration for tight control over Apollo Client&#8217;s internal memoization caches, and provides the necessary preparations to get insights into these caches from our DevTools.</p>



<h2 class="wp-block-heading"><a href="#overview-of-changes" aria-hidden="true" class="aal_anchor" id="overview-of-changes"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Overview of changes</strong></h2>



<p>Here&#8217;s an overview of some of the things we did:</p>



<h3 class="wp-block-heading"><a href="#granular-configuration-for-apollo-clients-internal-memoization" aria-hidden="true" class="aal_anchor" id="granular-configuration-for-apollo-clients-internal-memoization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Granular configuration for Apollo Client&#8217;s internal memoization</strong></h3>



<p>Apollo Client does a lot of expensive work internally. To speed things up, it memoizes results for intense calculations.&nbsp;</p>



<p>Memoization is always a trade-off between processing time and memory. In the past, Apollo Client erred on the side of &#8220;using more memory is better than using more CPU time&#8221; and had either very generous cache limits or used a <code>WeakMap</code> approach that kept memoized values around for as long as some user-defined variable kept the computation source value in memory.</p>



<p>While the <code>WeakMap</code> approach should have been fine in most cases, we can&#8217;t deny that it can cause a memory leak if user code does not follow our expectations. That, or we make a mistake ourselves, like using one of the source objects we use as memoization keys as keys in a strong <code>Map</code> somewhere else!</p>



<p>We also believe that our cache limits were too generous, so we revisited every internal memoization cache, double-checked our key usage, replaced all <code>WeakMaps</code> with a new Weak LRU Cache implementation, and made sure that each cache has a more reasonable maximum size that better represents the results it stores.</p>



<p>While those defaults should be sufficient in 90% of applications, we know that some applications will need to make different trade-offs, so we made each cache size individually configurable. You can read up on all the new configuration options<a href="https://www.apollographql.com/docs/react/caching/memory-management"> in this new documentation page on memory management</a>.</p>



<h3 class="wp-block-heading"><a href="#reflecting-on-the-role-of-inmemorycache-gc" aria-hidden="true" class="aal_anchor" id="reflecting-on-the-role-of-inmemorycache-gc"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Reflecting on the role of inMemoryCache.gc</strong></h3>



<p>If you read through that issue, you will notice that many people regularly started calling <code>inMemoryCache.gc()</code> to eliminate their memory problems. With the changes we made in 3.9, you should have less of a reason to do that.&nbsp;</p>



<p>At the same time, we realize there is a time in life when you just need that hammer, so for those moments, we want to make sure you hit your target. <code>inMemoryCache.gc()</code> now will clear many more caches than before, so if you encounter any memory weirdness and have exhausted all the other options, the chances of this working out for you will be much higher.</p>



<h3 class="wp-block-heading"><a href="#deprecating-canonizeresults" aria-hidden="true" class="aal_anchor" id="deprecating-canonizeresults"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Deprecating canonizeResults.</strong></h3>



<p>You might have seen Apollo Client&#8217;s <code>canonizeResults</code> option &#8211; it&#8217;s a very cool feature: it ensures that if you encounter two objects of the same shape and contents, they are references to the same in-memory object. Since all results returned by Apollo Client are frozen, you also can&#8217;t accidentally modify these objects, so it is a clever way to save memory and computation time for deep equality checks.&nbsp;</p>



<p>Unfortunately, to offer this functionality, the underlying <code>ObjectCanon</code> class has to keep a reference to all these one-of-a-kind objects. Although the <code>ObjectCanon</code> uses a lot of weakly referenced data structures, we noticed that it just doesn&#8217;t let them go. Objects that end up in an <code>ObjectCanon</code> are very likely to stay in there forever.</p>



<p>This behavior might be acceptable (and still very beneficial) in a shorter-lived application or an application that doesn&#8217;t see a lot of data. Still, it can lead to serious memory problems in very long-lived applications that see a lot of data.</p>



<p>No matter what we tried &#8211; we can&#8217;t find a way around this problem, and we believe that keeping the <code>ObjectCanon</code> around as an option is too much of a foot gun for our users, especially as applications grow.</p>



<p>So, with Apollo Client 3.9 we are deprecating the option. The majority of our users won&#8217;t notice this change, as it was disabled by default. For the users that are currently using it (and happy with it), we will keep it around until the next major version. We will look into alternatives that enable similar behavior with a lower memory footprint.</p>



<h3 class="wp-block-heading"><a href="#other-memory-related-changes-in-3-9" aria-hidden="true" class="aal_anchor" id="other-memory-related-changes-in-3-9"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Other memory-related changes in 3.9</strong></h3>



<p>While these are the biggest changes we&#8217;re shipping, they are not the only ones.&nbsp;</p>



<ul class="wp-block-list">
<li>A potential memory leak in <code>RetryLink</code> was fixed, which also greatly reduced the bundle size for this link.</li>



<li><code>PersistedQueryLink</code> will now clear its internal cache if the server signals that it cannot work with persisted queries.</li>



<li>In React Native with the Hermes engine we now use <code>WeakMap</code>s/<code>WeakSet</code>s and the Weak LRU cache. In previous React Native engines, these were not supported, so we would have to fall back strong <code>Map</code> instances, which could cause memory issues. Unfortunately, Hermes does not support <code>WeakRef</code>s and <code>FinalizationRegistry</code> yet, so in some situations we have to fall back to strongly referenced data &#8211; but in every case it will have a maximum cache size.</li>



<li>We fixed a potential memory leak if you changed variables in <code>useBackgroundQuery</code> or <code>useSuspenseQuery</code> very frequently.</li>



<li>We fixed a potential memory leak that could occur in <code>Concast</code> if you directly used that in your code. This leak could never occur inside of Apollo Client due to the way we used <code>Concast</code> ourselves. We don&#8217;t assume that a lot of our users are using <code>Concast</code> directly, so this likely had a very low impact.</li>



<li><code>canonicalStringify</code> is now decoupled from <code>ObjectCanon</code> and will use a lot less memory.</li>



<li>All APIs that use internal memoization caches now expose the ability to reset the cache.</li>
</ul>



<h2 class="wp-block-heading"><a href="#your-help-wanted" aria-hidden="true" class="aal_anchor" id="your-help-wanted"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a><strong>Your Help Wanted</strong></h2>



<p>A lot of work has gone into all of this, and we have done our best to find good defaults for all the new cache sizes. Unfortunately, as library authors, we don&#8217;t have access to a lot of &#8220;real&#8221; apps that we can measure to validate our assumptions.</p>



<p>This is where we need your help!</p>



<p>Please try our beta in your application, run our development builds in your dev or staging environments, and after using your app for a while, run <code>__APOLLO_CLIENT__.getMemoryInternals()</code>, and submit the results to<a href="https://github.com/apollographql/apollo-client/issues/11444"> our feedback collection issue</a>. The more measurements we get from real-life apps, the better we can choose those default cache sizes!</p>



<p>The current plan is to wait until January 15 for measurements, at which point we will decide on our final cache sizes and put out a first release candidate.</p>



<p>Your help would be greatly appreciated!</p>


Apollo Client 3.9 Feature Spotlight – The memory story


<p>One of the most common use cases front-end developers face is re-render the UI after executing a <code>mutation</code> and changing something in the backend.</p>



<p>To solve this problem, a lot of developers like to use the <code>refetchQueries</code> API.</p>



<p>For example, if I wanted to <strong>add</strong> a <code>todo</code> to a list of <code>todos</code>, I might pass a <code>GET_ALL_TODOS</code> query to my list of queries to refetch, like so:</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      refetchQueries: [
        { query: GET_ALL_TODOS }
      ]
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p>While this approach works, the biggest disadvantage is that we have to make multiple network round-trips to get our UI to re-render, even if we already have the data we need on the client-side.</p>



<p>It also introduces the question of &#8220;what do we do if we have a lot of queries relying on the same data? Do we have to remember to add all of <em>those</em> to the same <code>refetchQueries</code> list as well?&#8221;</p>



<p>Luckily, you don&#8217;t.</p>



<p>In this post, I&#8217;ll explain when it makes sense to use <code>refetchQueries</code>, and when you should rely on Apollo Client&#8217;s automatic cache normalization algorithm or <code>update</code> functions.</p>



<blockquote class="wp-block-quote is-layout-flow wp-block-quote-is-layout-flow"><p>The following example uses the Apollo Client 3 Todos app example from <a href="https://github.com/apollographql/ac3-state-management-examples">@apollographql/ac3-state-management-examples</a>.</p></blockquote>



<h2 class="wp-block-heading"><a href="#use-refetchqueries-when-youre-first-getting-started" aria-hidden="true" class="aal_anchor" id="use-refetchqueries-when-youre-first-getting-started"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Use refetchQueries when you&#8217;re first getting started</h2>



<p>If you&#8217;re just getting started with GraphQL, I think the mental model of passing in the queries that you&#8217;d like to re-run after a mutation is an easy one to wrap your head around.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png" alt="" class="wp-image-5972" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.32_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>Looking back at our trivial <code>todo</code> app, if we have a list of <code>todos</code> and we want to <strong>add</strong> an item, we can accomplish that and re-render the UI with the <code>ADD_TODO</code> operation passed into a <code>useMutation</code> hook and the <code>GET_ALL_TODOS</code> query passed into the <code>refetchQueries</code> array.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">const [mutate, { data, error }] = useMutation&lt;
  AddTodoTypes.AddTodo, 
  AddTodoTypes.AddTodoVariables
&gt;(
  // Execute this
  ADD_TODO, 
  {
    // Then re-run 
    refetchQueries: [
      { query: GET_ALL_TODOS }
    ]
  }
)
return { mutate, data, error };
﻿</code></pre>



<p>This works. It runs the query and after successfully completing the mutation, it executes the <code>GET_ALL_TODOS</code> query and pulls in all the new <code>todos</code>.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png" alt="" class="wp-image-5976" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_1.51.02_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>The advantage here is that this approach is straightforward. The disadvantage is that we&#8217;re fetching the entire list of data again when we might not need to.</p>



<h2 class="wp-block-heading"><a href="#cache-normalization-and-update-functions" aria-hidden="true" class="aal_anchor" id="cache-normalization-and-update-functions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Cache Normalization and Update Functions</h2>



<p>For a more efficient use of bandwidth and network round-trips, we can rely on cache normalization and <code>update</code> functions.</p>



<p>As we previously learned in the &#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; blog post, for certain operations, the Apollo Client cache is smart enough to <strong>automatically update the cache for you</strong>. For others, we can utilize an <code>update</code> function to tell the cache how we want it to update.</p>



<h3 class="wp-block-heading"><a href="#automatically-updating-with-cache-normalization" aria-hidden="true" class="aal_anchor" id="automatically-updating-with-cache-normalization"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Automatically Updating with Cache Normalization</h3>



<p>For mutations that <strong>change only a single entity,</strong> the cache is smart enough to update the item in place automatically, but only if we return the changed item (containing the unique identifier) in the mutation response.</p>



<p>Here&#8217;s an example of <strong>editing a</strong> <code>todo</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as EditTodoTypes from &#039;./__generated__/EditTodo&#039;

export const EDIT_TODO = gql`
  mutation EditTodo ($id: Int!, $text: String!) {
    editTodo (id: $id, text: $text) {
      success
      todo { # Return the new todo in the mutation response
        id
        text 
        completed
      }
      error {
        ... on TodoNotFoundError {
          message
        }
        ... on TodoValidationError {
          message
        }
      }
    }
  }
`

export function useEditTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    EditTodoTypes.EditTodo, 
    EditTodoTypes.EditTodoVariables
  &gt;(
    EDIT_TODO
  )

  return { mutate, data, error };
}
﻿</code></pre>



<p>And since we&#8217;ve returned the <strong>changed data</strong> in the <code>mutation</code> response, it works.</p>



<figure class="wp-block-image size-large"><img loading="lazy" decoding="async" width="1024" height="789" src="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png" alt="" class="wp-image-5980" srcset="https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-1024x789.png 1024w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-300x231.png 300w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM-768x591.png 768w, https://wp.apollographql.com/wp-content/uploads/2020/11/Screen_Shot_2020-11-16_at_2.08.21_PM.png 1061w" sizes="auto, (max-width: 1024px) 100vw, 1024px" /></figure>



<p>But for other operations, like <em>adding</em> to a list or <em>removing</em> elements from a list, we need to give the cache a little bit of help to figure out exactly what we want to do.</p>



<h3 class="wp-block-heading"><a href="#using-update-functions" aria-hidden="true" class="aal_anchor" id="using-update-functions"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Using Update Functions</h3>



<p>Here&#8217;s the <code>ADD_TODO</code> example again, but this time using an <code>update</code> function to update the existing list of <code>todos</code>.</p>



<pre class="wp-block-prismatic-blocks"><code class="language-typescript">import { gql, useMutation } from &quot;@apollo/client&quot;;
import * as AddTodoTypes from &#039;./__generated__/AddTodo&#039;;
import { GET_ALL_TODOS } from &quot;../queries/getAllTodos&quot;;
import { GetAllTodos } from &quot;../queries/__generated__/GetAllTodos&quot;;

export const ADD_TODO = gql`
  mutation AddTodo ($text: String!) {
    addTodo (text: $text) {
      success
      todo {
        id
        text 
        completed
      }
      error {
        message
      }
    }
  }
`

export function useAddTodo () {
  const [mutate, { data, error }] = useMutation&lt;
    AddTodoTypes.AddTodo, 
    AddTodoTypes.AddTodoVariables
  &gt;(
    ADD_TODO,
    {
      update (cache, { data }) {
        // We use an update function here to write the 
        // new value of the GET_ALL_TODOS query.
        const newTodoFromResponse = data?.addTodo.todo;
        const existingTodos = cache.readQuery&lt;GetAllTodos&gt;({
          query: GET_ALL_TODOS,
        });

        if (existingTodos &amp;&amp; newTodoFromResponse) {
          cache.writeQuery({
            query: GET_ALL_TODOS,
            data: {
              todos: [
                ...existingTodos?.todos,
                newTodoFromResponse,
              ],
            },
          });
        }
      }
    }
  )
  return { mutate, data, error };
}
﻿</code></pre>



<p>In this example, we use the <code>readQuery</code> and <code>writeQuery</code> APIs to write the new value of the <code>todos</code> list which contains the <code>todo</code> we created in the <code>mutation</code>.</p>



<p>One way we could omit needing to write this <code>update</code> function is if the mutation response returned the <strong>entire list of new todos</strong> in the <code>mutation</code> response, but that&#8217;s not always possible.</p>



<p>Sometimes you don&#8217;t own the API.</p>



<p>Sometimes, it can get expensive to be doing that after every <code>mutation</code>.</p>



<p>So here, we utilize the <code>update</code> function.</p>



<p>Admittedly, this is a little bit more work than using <code>refetchQueries</code>, but that&#8217;s the trade off for a performance improvement. You don&#8217;t have to re-request the same data from your server and wait for another entire roundtrip to update the UI.</p>



<h2 class="wp-block-heading"><a href="#conclusion" aria-hidden="true" class="aal_anchor" id="conclusion"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Conclusion</h2>



<p>In summary best times to use <code>refetchQueries</code> are:</p>



<ol class="wp-block-list"><li>When you don&#8217;t yet know how ACC normalization works</li><li>If you&#8217;re not able to return the changed data in a mutation response</li></ol>



<p>To reduce round-trips after mutations, we generally recommend relying on the Apollo Client automatic caching normalization and when necessary, <code>update</code> functions.</p>



<h2 class="wp-block-heading"><a href="#resources" aria-hidden="true" class="aal_anchor" id="resources"><svg aria-hidden="true" class="aal_svg" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Resources</h2>



<ul class="wp-block-list"><li>&#8220;<a href="https://www.apollographql.com/blog/demystifying-cache-normalization/">Demystifying Cache Normalization</a>&#8221; from the Apollo Blog</li><li>&#8220;<a href="https://www.apollographql.com/docs/react/caching/advanced-topics/#updating-after-a-mutation">Updating after a Mutation</a>&#8221; from the Apollo Docs</li></ul>


Caching

Optimizing Data Fetching with Apollo Client: Leveraging useFragment and Colocated Fragments

Apollo Client 3.9 Feature Spotlight – The memory story

When To Use Refetch Queries in Apollo Client

Local State Management with Reactive Variables

Demystifying Cache Normalization

Dispatch This: Using Apollo Client 3 as a State Management Solution

Caching

Optimizing Data Fetching with Apollo Client: Leveraging useFragment and Colocated Fragments

Apollo Client 3.9 Feature Spotlight – The memory story

When To Use Refetch Queries in Apollo Client

Local State Management with Reactive Variables

Demystifying Cache Normalization

Dispatch This: Using Apollo Client 3 as a State Management Solution

Stay in our orbit