The garbage collection feature allows to remove unused data from the normalized cache to reduce its size.

Stale fields

A field is considered stale if its received date is older than its (client controlled) max age, or if its (server controlled) expiration date has passed.

See expiration for more information about staleness.

Stale fields can be removed from the cache by calling the ApolloStore.removeStaleFields() function.

If all fields of a record are stale, the record itself is removed.

Note: when a record is removed, any reference to it will become a dangling reference.

Dangling references

A dangling reference is a field whose value is a reference to a cache key that does not exist in the cache.

This can happen when:

• manually deleting records with ApolloStore.remove()

• records get deleted because all their fields are stale

Dangling references can be removed from the cache by calling the ApolloStore.removeDanglingReferences() function.

If all fields of a record are dangling references, the record itself is removed.

Note: if a field's value is a list for which one or more elements are dangling references, the entire list is removed, which can result in unreachable records.

Unreachable records

A record is unreachable if there exists no chain of references from the root record to it.

This can happen when:

• data that was previously returned by the server is no longer returned by a subsequent query

• manually adding records with ApolloStore.writeFragment()

• manually deleting records with ApolloStore.remove() and cascade = false: the deleted record could be the only one referencing others

• references get deleted because they're stale

Unreachable records can be removed from the cache by calling the ApolloStore.removeUnreachableRecords() function.

ApolloStore.garbageCollect()

The ApolloStore.garbageCollect() function is a convenience to remove all stale fields, dangling references, and unreachable records from the cache.

Guidance

We recommend calling ApolloStore.garbageCollect() periodically to keep the cache size under control. The frequency depends on your application's needs and the amount of data being cached.

Since the garbage collection process can potentially be resource-intensive and time-consuming, run it in a background task during periods of low activity in your application, for instance by using WorkManager on Android.