Stuck with NULL value in cache after initial network query, even after subsequent mutation

[Frank-D]

Hi!

I'm trying to understand how the cache works between Queries and Mutations. I was expecting that Mutation results would populate the cache in a way that queries would then be able to get that cached data, but after some testing, my observations lead me to believe that Mutations and Queries use separate caching entires that are "independent", wondering if that is accurate??

I've executed 2 different scenarios:

• A (Mutation + Query + Query),
  and
• B (Query + Mutation + Query)

..in order to understand how the cache behaves, and precisely to understand the bug that I'm currently having in my app around scenario B. I don't understand why in the last query of scenario B, I'm still getting the NULL value cached from initial Query. I would have expected the Mutation in the middle to reset the original NULL value from the cache, since they have the same ID..

However, a problem that I see is, when a query returns 'empty/null' result, is that there's no "__typename" being returned for obvious reason, so perhaps that is my problem, and I'm wondering how am I supposed to deal with the cache for all those ~not found queries that have no __typename being returned.

The library will cache the query with the query name (not the type) and the id, so the mutation probably is unable to override such null cached entry by the lack of typename, and most likely my problem here, unless they are just entirely independent (I see cache entries with "Query" as the main key, and other entires with "Mutation" as the main cache key, so they seem to be separated/independent, is that accurate?

I'm looking for confirmation of this caching Query/Mutation independent behaviour, and suggestions on how to deal with scenario B around my NULL issue, but first, I'll share scenario A (the tested happy path), to show how the cache is being populated for happy path, which helps better understand my scenario B's NULL caching issue..

Here's my setup:

GraphQL Client Definition:
(relying on default policies, so queries are using 'cache first', and mutations, 'network')

    GraphQLClient(
      cache: GraphQLCache(
        typePolicies: {
          'UserType': TypePolicy(
            keyFields: {
              'authId': true,
            },
          ),
        },
      ),
      link: _link,
    );

Here's how I display the cache entries after each operations:

      _graphqlClient.cache.store.toMap().entries.forEach((MapEntry mapEntry) {
        print("- KEY: " + mapEntry.key.toString());
        print("- VALUE: " + mapEntry.value.toString());
      });

======================================
SCENARIO A): 1- MUTATION + 2- QUERY + 3- QUERY

[ State 0 ] Scenario: Initial App Start --> GraphQL cache is empty

GQL Cache entries: EMPTY

[ State 1 ] Scenario: After graphql creation of new UserType entity (MUTATION) --> GraphQL cache now populated from mutation

Mutation: createUser with authId = 12345
Mutation result: success --> expected.
Mutation result source: NETWORK --> expected.
GQL Cache entries:

- KEY: UserType:{"authId":"12345"}
- VALUE: { __typename: UserType, authId: 12345, fullName: John Doe, email: [email protected] }

- KEY: Mutation
- VALUE: { __typename: Mutation, createUser({"input":{"authId":"12345","fullName":"John Doe","email":"[email protected]"}}): {$ref: UserType:{"authId":"12345"}} }

[ State 2 ] Scenario: After graphql read of UserType entity just created in previous step (QUERY) --> GraphQL cache now populated from mutation + query

Query: query user with authId = 12345
Query result: success with data --> expected.
Query result source: NETWORK --> NOT expected. Why such query can't read from the cached mutation entries? are they really independent from each other?? One caching ~sub-system for "Mutation", and another caching separate sub-system for "Query", is that the case? This would mean, I always need to "manually" update my "Query" caching sub-system after each Mutation operation? I was hoping for some more automation between the 2, at least when __typename and id/keyFields are the same...

GQL Cache entries:

- KEY: UserType:{"authId":"12345"}
- VALUE: { __typename: UserType, authId: 12345, fullName: John Doe, email: [email protected] }

- KEY: Mutation
- VALUE: { __typename: Mutation, createUser({"input":{"authId":"12345","fullName":"John Doe","email":"[email protected]"}}): {$ref: UserType:{"authId":"12345"}} }

- KEY: Query
- VALUE: { __typename: Query, user({"authId":"12345"}): {$ref: UserType:{"authId":"12345"}} }

[ State 3 ] Scenario: After graphql RE-read of UserType entity (QUERY)

Query: query user with authId = 12345
Query result: success with data --> expected.
Query result source: CACHE --> expected.
GQL Cache entries: (...no change from the above..)

At this point, Scenario A is completed, and everything worked as expected, in terms of GraphQL queries and its caching behaviours. Now let's move on to Scenario B, where order of operations are slightly different, which introduces a NULL value caching issue that doesn't seem to be 'automatically' recoverable, unless I manually remove the NULL value entry from the cache, but I was hoping to find a way to avoid having to manually fix the cache myself, at least for this simple scenario.

=========================================
SCENARIO B): 1- QUERY + 2- MUTATION + 3- QUERY

[ State 0 ] Scenario: Initial App Start --> GraphQL cache is empty

GQL Cache entries: EMPTY

[ State 1 ] Scenario: After graphql read of UserType entity, which does NOT exist yet in backend DB (QUERY) --> GraphQL cache now populated from query

Query: query user with authId = 12345
Query result: success WITHOUT data (null result) --> expected.
Query result source: NETWORK --> expected.
GQL Cache entries:

- KEY: Query
- VALUE: { __typename: Query, user({"authId":"12345"}): null }

[ State 2 ] Scenario: After graphql creation of new UserType entity (MUTATION) --> GraphQL cache now populated from query + mutation

Mutation: createUser with authId = 12345
Mutation result: success --> expected.
Mutation result source: NETWORK --> expected.
GQL Cache entries:

- KEY: Query
- VALUE: { __typename: Query, user({"authId":"12345"}): null }

- KEY: UserType:{"authId":"12345"}
- VALUE: { __typename: UserType, authId: 12345, fullName: John Doe, email: [email protected] }

- KEY: Mutation
- VALUE: { __typename: Mutation, createUser({"input":{"authId":"12345","fullName":"John Doe","email":"[email protected]"}}): {$ref: UserType:{"authId":"12345"}} }

[ State 3 ] Scenario: After graphql read of UserType entity (QUERY) --> *** STILL RETURNS NULL FROM CACHE, EVEN AFTER PREVIOUS MUTATION !! ***

Query: query user with authId = 12345
Query result: success WITHOUT data (null result) !!!!! --> NOT expected. THIS IS MY MAIN PROBLEM HERE THAT I'M TRYING TO UNDERSTAND / RESOLVE. I was expecting the mutation to replace that NULL query cache entry with the real UserType user data that was created during previous Mutation operation, but it doesn't seem to work this way....right?
Query result source: CACHE --> expected.
GQL Cache entries: (...no change from the above..)

---

Any help regarding the above NULL caching issue is welcome!
Thank you, and sorry for the long msg!

[budde377]

Thanks for opening this discussion @Frank-D. This is a reoccurring question in different shapes and conditions (e.g. #1117).

As I can see you have two questions in your example:

1. Query result source: NETWORK --> NOT expected.
2. Query result: success WITHOUT data (null result) !!!!! --> NOT expected

For the first question. The reason why it's fetching the query from the network is that you haven't cached the Query with the user field. The client can't assume that fetching user(authID: 12345) maps to the user with auth-id 12345. While it might intuitively make sense for us as developers, codifying such an assumption would be prone to bugs. E.g., consider the API where you're only allowed to fetch a subset of users, how would we correctly guess which users you'd be allowed to fetch? So the client needs to fetch the query from network.

The answer to your second question is related. Performing a mutation will not store any information about the relationship between the Query and the User in the cache. According to the cache, the field user (with argument authID: 12345) yields null. The Mutation doesn't fetch the Query, so this assumption stands.

How can you fix this?

You can do three things on the top of my mind:

• Manually update the cache with writeFragment or writeQuery cache methods. This'll allow you to express the assumption that you have, i.e., that creating a user will allow you to fetch it from the user field.
• You can rewrite your API to return the Query (with the User?). The Query, Mutation, and Subscription objects are just objects, there's no special logic around them.
• You can refetch your query.

[Frank-D]

First of all, thank you so much for your quick answer @budde377, and for taking the time to write your whole response. That was my first msg to this repo, as I just started recently playing with the graphql client pub package, and so, that's a good first impression to start...tx ;-)

Alright, so I've a few comments back to your post, or a few remaining questions and then I think I'll be good to resolve and unblock my work with this lib! I'll identify each of those remaining comments/questions with IDs to make this easier..

1)

For the first question. The reason why it's fetching the query from the network is that you haven't cached the Query with the user field. The client can't assume that fetching user(authID: 12345) maps to the user with auth-id 12345. While it might intuitively make sense for us as developers, codifying such an assumption would be prone to bugs. E.g., consider the API where you're only allowed to fetch a subset of users, how would we correctly guess which users you'd be allowed to fetch? So the client needs to fetch the query from network.

I understand your point regarding, for instance, a list of objects where it's definitely more tricky to guess, but unless it's because of my lack of experience with this lib, and/or graphql in general, having used or built a few caching systems in the past, usually the caching logic is never built around the cached values, but the cached keys for obvious reasons..

And so, I was hoping here that, whether it's a mutation or query operation, if they both reference the same caching key (in my case, the user field of __typename 'UserType' with key field 'authId' of value '12345'......so we can compute the caching key here using all this information and obtain a unique caching key in the end..), then, no matter what's the caching value associated to this caching key, it doesn't matter, whether it's a list of objects or just a simple object (that's my case, a unique user record), it should be possible to interact with the same cache entry in those conditions between the Query and the Mutation.....at least, that was my understanding, and so, I'm still struggling to understand why can't we implement that particular logic, but again, it could be for my lack of understanding of more advanced/partial use cases around some graphql concepts that I haven't played with yet..

To add on top of this, both my Query and my Mutation are sharing the same "query", so that was my main reason to believe that they would interact with the same cache entry:

    // Execute GraphQL Query
    final QueryResult gqlApiResult = await _myGraphQlClientWrapper.executeQuery(
      r'''
        query readUserByAuthId($authId: String!) {  
          user(authId: $authId) {
          ''' +
          BackendUserServiceUtils.userQueryString +
          '''
          }
        }
      ''',
      {
        'authId': authId,   // --> in this example, I'll be providing value '12345' for 'authId'
      },
    );

    -------------------------------------------------------------------------------------

    // Execute GraphQL Mutation
    final QueryResult gqlApiResult = await _myGraphQlClientWrapper.executeMutation(
      r'''
        mutation CreateUser($createUserInput: CreateUserInput!) {
          action: createUser(input: $createUserInput) {
          ''' +
          BackendUserServiceUtils.userQueryString +
          '''
          }
        }
      ''',
      {
        'createUserInput': userProfileToCreate.toJson(),  // --> in this example, the user profile will have the main key field 'authId' = '12345' when this mutation operation will be called...
      },
    );

...where, as we can see, both share the same internal query structure/fields, BackendUserServiceUtils.userQueryString:
(stripping out additional fields to keep this post/example simple with just 3 basic fields and the type...)

class BackendUserServiceUtils {
  static String userQueryString = r'''
            __typename,
            authId,
            fullName,
            email
      ''';
}

And so, to close on that never-ending point 1) ; ), I know that you wrote..:

The Mutation doesn't fetch the Query, so this assumption stands.

..but I was hoping that perhaps the caching logic would consider that the mutation's query/response that I manually requested should be cached using the __typename and the 'authId' key/value, exactly the same way the Query should be doing it, instead of separating the 2 operations results in 2 separate/independent caching entries, one for the Mutation, and one for the Query. To me, they should both refer to the same caching "key" (no matter the value(s) to be cached..), and again, such caching key would have been built using the typename and the key fields that I've specified for this type (or default, id or _id). No? : )

2)

Assuming I'm wrong on my above understanding of what's possible and what's not in terms of caching capabilities between Mutation and Query operations, is it fair to assume that this library will "never" try to create any caching link whatsoever between Mutation and Query operations?

And so, this means, whenever I do a Mutation operation, it's quite possible that I may have to 'manually' clear/update some potential existing Query cached entry(ies) that could have turned wrong/misleading, following my last mutation operation, and this includes basic ~ single-object-with-unique-key use cases, correct?

If this question is common (or similar to others), perhaps it would be a good idea to add an additional section in the caching section of the documentation, to provide some further explanation, with concrete cache entries and mutation/query examples similar to what I've provided in my first post, to let the users understand better how the cache of this lib really behaves etc, just a suggestion..)

3)

You can do three things on the top of my mind:
a) Manually update the cache with writeFragment or writeQuery cache methods. This'll allow you to express the assumption that you have, i.e., that creating a user will allow you to fetch it from the user field.
b) You can rewrite your API to return the Query (with the User?). The Query, Mutation, and Subscription objects are just objects, there's no special logic around them.
c) You can refetch your query.

Thank you very much for sharing those options.
I understand the first option a) and that's what seems to me the most natural thing to do at this point (would this be your recommendation as well?), however, could you please describe just a bit more your other 2 options b) and c), I'm not fully understanding them.

b) I've no clue what you mean I'm sorry,

as for c), are you suggesting that after the mutation, I can always avoid updating manually my existing cached query that is now wrong/obsolete post-mutation, by simply calling the original query again (..that's what I was doing, but since it was using 'cache first' policy, it was simply returning the wrong cached entry, so I guess perhaps you meant to force a 'network' query post mutation in my case, to fetch the updated data from the server, and then get it updated in my local cache by overriding the previous existing wrong cached query entry, is that right? (in which case, I believe your option a) seems more efficient since it avoids an additional round-trip to the server with such additional network query..)

Thanks again!

[budde377]

Happy to help!

So if I understand this correctly, you're wondering why the mutation and query don't seem to reference the same cache entry for the User with id 12345. The good news is that they do!

The problem here is that the mutation and query return different root types. The query will return a subset of the Query which contains the User and the mutation will return a subset of Mutation which also contains a reference to the same User.

Let's say that you have a mutation that alters a User, e.g. sets a new name. The mutation can return the changed User as part of the Mutation and it will correctly propagate the changes to any other reference to this user (whether it's contained in a list, query, mutation, etc.). In other words, let's say we have the following operations:

query FetchUser {
  user(authId: 12345) {
    authId
    fullName
    email
  }
}

mutation UpdateUser {
  updateUserName(authId: 12345, fullName: "New name") {
    authId
    fullName
  }
}

and then the sequence of events:

1. FetchUser: yielding the response {data: { user: {authId: 12345, fullName: "Bob", email: "[email protected]" } } }.
2. UpdateUser: yielding the response {data: {updateUserName: {authId: 12345, fullName: "New name"}}}
3. FetchUser (from cache) will now yield {data: { user: { authId: 12345, fullName: "New name", email: "[email protected]" }}}

this is because they share the same reference to the User, which is what you expected.

So how is this different from your case?

Scenario A: After the Mutation, you have correctly populated the cache with your User with id 12345. So when you perform your first query, the returned data will correctly reference the cached user entry, updating any changed fields. The reason why it needs to fetch the query from the network regardless is that you haven't populated the Query in the cache yet! This is what I mean with Query and Mutation types being treated no different than any other object in the cache. So your query will look up the cache for an entry with the key Query with the field (and arguments)user(authId: 12345).

So in this example, what you could do after the mutation and before your first query, is to manually update the cache:

// Plz. lookup the right API, this is just to illustrate my point
writeQuery(
  gql("""
  query LinkUser(id: $id) {
    user(authId: $id) { 
      authId
      __typename
    }
  }
  """),
  { "__typename": "Query", "user": { "authId": 12345, "__typename": "User" } }
)

This will populate your cache with the Query object containing the field with the argument user(authId: 12345) which links to the user cache entry returned from the mutation.

For your Scenario B, this is really not much different in its core. In this case, you have performed the query first, but now you have a cached Query with the field user(authId: 12345) pointing to null. Performing the mutation will update the cache for keys Mutation and User(authId: 12345) but not Query. This means when you try and fetch the query from the cache, it'll still point to null because this is what it knows! You can use the same technique as above to update the cached Query to contain a field user(authId: 12345) to point at the User(authId: 12345).

So to summarise, the underlying problem isn't with the cached User. You have correctly setup key fields and fetched necessary data to update the cache. The problem is that the mutations are performed with the Mutation type as root, and the queries are performed with the Query type as root. So the cache entries of the Query and Mutation are not updated correctly.

Going back to the three solutions, I've roughly outlined how you may perform direct cache updates (1) above. Here's a link to the documentation on direct cache updates.

The third solution is to refetch. Here you'll need to set appropriate fetch policies as you noticed (e.g. networkOnly). If you're using the graphql_flutter package, the widgets (or hooks) will expose a refetch method for you to use.

The second solution is a bit more "controversial". So I'm saying that the Mutation and Query types in your schema are treated no differently than any other cache entry. Then you should be able to update your schema

type Mutation {

  createUser(input: CreateUserInput): CreateUserResult
}

type CreateUserResult {
  user: User
  query: Query
}

then you could re-write your query as

mutation {
  createUser(input: input) {
    query {
      user(authId: $id) {
        authId
        __typename
      }
    }
  }
}

this of course requires you to know the ID upfront, which is probably not the case in most scenarios. So while this example might not be practically useful, it really illustrates my point on how these cache entries work and you might find it useful in other situations, e.g. when expressing changing relationships between other entities.

Finally, as a comment on your operations, I'd recommend that you save the result of calling gql() in a const so you don't have to parse the query and mutations on every request. Then, I'd probably use GraphQL Fragments to re-use the BackendUserServiceUtils.userQueryString, so you can re-write your operations to something like

mutation {
  createUser { ...BackendUserServiceUtilsUser }
}

query {
  user(authId: 12345) { ...BackendUserServiceUtilsUser }
}

You can get great fragment support and typed cache methods with the graphql-codegen library.

[Frank-D]

Amazing @budde377, very clear explanations!

I now fully understand how I ran into being stuck with my NULL issue (scenario B), and how to recover from/fix it.
I'll go with your first suggestion, and simply updating the cache directly/manually after my mutation.

Also, thanks for going the extra mile with your last 2 suggestions; I was effectively storing in const 'string' variables my queries and mutations, and my intent was to make this as abstract as possible by the use of string, rather than the use of library-specific type(s) such as DocumentNode in this case (..the return type of gql() method), in case one day I ever want to try a different gql lib...but still, I'll find a way to store the DocumentNode gql() result through the use of some kind of bridge/adapter pattern, to get that little perf. boost, great suggestion.

As for the codegen suggestion, that's also a good one. I initially evaluated it, but thought of skipping it for this current project, too many moving parts and dependencies on external libs/packages, so at this point I'm trying to keep things as simple as possible and avoid too much magic etc, but I'll definitely keep that in mind for later or next project and try, leaving some room to be impressed by it. I'm usually not so thrilled about adding code-generation steps in my projects (it's very useful, but at times also frustrating, whether the IDE doesn't recognize or sees the generated files/classes, or when you want to make just a simple change the process is less trivial and takes longer than simply changing the code right away, etc), but I've seen success scenarios about it on some other projects at my job too, such as, generating lots of boilerplate rest api code from swagger files, so never say no:)..

Thanks again @budde377 for all your help 🙏 🙌