Introduce ObservableQuery#refresh as an alternative to refetch.

The difference is that refresh overwrites existing fields by not passing
existing data to field merge functions, whereas refetch passes existing
data to merge functions, thereby combining it with the refetch result.

If we continue down this path, we can say "the solution to #7491 is to
switch from using refetch to using refresh," but that involves conscious
effort by the developer, and would mean maintaining two very similar
methods of the ObservableQuery class (refetch and refresh).

src/core/ObservableQuery.ts

@@ -224,6 +224,16 @@ export class ObservableQuery<
    * the previous values of those variables will be used.
    */
   public refetch(variables?: Partial<TVariables>): Promise<ApolloQueryResult<TData>> {
+    return this.refresh(variables, NetworkStatus.refetch);
+  }
+
+  // Forces a network query, like fetchMore and refetch, but overwrites
+  // existing cache fields with incoming data, rather than merging field
+  // values. Can be useful for restarting paginated fields with fresh data.
+  public refresh(
+    variables?: Partial<TVariables>,
+    networkStatus = NetworkStatus.refresh,
+  ): Promise<ApolloQueryResult<TData>> {
     const reobserveOptions: Partial<WatchQueryOptions<TVariables, TData>> = {
       // Always disable polling for refetches.
       pollInterval: 0,
@@ -250,9 +260,13 @@ export class ObservableQuery<
 
     this.queryInfo.resetLastWrite();
 
-    return this.newReobserver(false).reobserve(
+    return (
+      networkStatus === NetworkStatus.refresh
+        ? this.getReobserver()
+        : this.newReobserver(false)
+    ).reobserve(
       reobserveOptions,
-      NetworkStatus.refetch,
+      networkStatus,
     );
   }
 

src/core/QueryManager.ts

@@ -886,7 +886,7 @@ export class QueryManager<TStore> {
     options: WatchQueryOptions<TVars, TData>,
     // The initial networkStatus for this fetch, most often
     // NetworkStatus.loading, but also possibly fetchMore, poll, refetch,
-    // or setVariables.
+    // refresh, or setVariables.
     networkStatus = NetworkStatus.loading,
   ): Concast<ApolloQueryResult<TData>> {
     const query = this.transform(options.query).document;
@@ -1039,7 +1039,7 @@ export class QueryManager<TStore> {
     options: WatchQueryOptions<TVars, TData>,
     // The initial networkStatus for this fetch, most often
     // NetworkStatus.loading, but also possibly fetchMore, poll, refetch,
-    // or setVariables.
+    // refresh, or setVariables.
     networkStatus: NetworkStatus,
   ): ConcastSourcesIterable<ApolloQueryResult<TData>> {
     const {
@@ -1097,7 +1097,7 @@ export class QueryManager<TStore> {
 
     const cacheWriteBehavior =
       fetchPolicy === "no-cache" ? CacheWriteBehavior.FORBID :
-      networkStatus === NetworkStatus.refetch ? CacheWriteBehavior.OVERWRITE :
+      networkStatus === NetworkStatus.refresh ? CacheWriteBehavior.OVERWRITE :
       CacheWriteBehavior.MERGE;
 
     const resultsFromLink = () =>

src/core/networkStatus.ts

@@ -27,6 +27,18 @@ export enum NetworkStatus {
    */
   refetch = 4,
 
+  /**
+   * Similar to NetworkStatus.refetch, but existing cache fields will be
+   * overwritten by the incoming network data, rather than merging. Useful
+   * for restarting a paginated field with fresh initial data.
+   *
+   * This enum value uses the string "refetch" rather than a number,
+   * because it was added after the other values, and we did not want to
+   * change the existing numbers. Any other values added in the future
+   * should also use strings rather than numbers.
+   */
+  refresh = "refresh",
+
   /**
    * Indicates that a polling query is currently in flight. So for example if you are polling a
    * query every 10 seconds then the network status will switch to `poll` every 10 seconds whenever
@@ -52,5 +64,6 @@ export enum NetworkStatus {
 export function isNetworkRequestInFlight(
   networkStatus?: NetworkStatus,
 ): boolean {
-  return networkStatus ? networkStatus < 7 : false;
+  return networkStatus === "refresh" ||
+    (typeof networkStatus === "number" && networkStatus < 7);
 }

src/react/components/__tests__/client/__snapshots__/Query.test.tsx.snap

@@ -28,6 +28,7 @@ Object {
   "networkStatus": 1,
   "previousData": undefined,
   "refetch": [Function],
+  "refresh": [Function],
   "startPolling": [Function],
   "stopPolling": [Function],
   "subscribeToMore": [Function],

src/react/data/QueryData.ts

@@ -495,6 +495,9 @@ export class QueryData<TData, TVariables> extends OperationData<
   private obsRefetch = (variables?: Partial<TVariables>) =>
     this.currentObservable?.refetch(variables);
 
+  private obsRefresh = (variables?: Partial<TVariables>) =>
+    this.currentObservable?.refresh(variables);
+
   private obsFetchMore = (
     fetchMoreOptions: FetchMoreQueryOptions<TVariables, TData> &
       FetchMoreOptions<TData, TVariables>
@@ -530,6 +533,7 @@ export class QueryData<TData, TVariables> extends OperationData<
     return {
       variables: this.currentObservable?.variables,
       refetch: this.obsRefetch,
+      refresh: this.obsRefresh,
       fetchMore: this.obsFetchMore,
       updateQuery: this.obsUpdateQuery,
       startPolling: this.obsStartPolling,

src/react/hoc/types.ts

@@ -1,4 +1,4 @@
-import { ApolloClient } from '../../core';
+import { ApolloClient, ObservableQuery } from '../../core';
 import { ApolloError } from '../../errors';
 import {
   ApolloQueryResult,
@@ -28,6 +28,7 @@ export interface QueryControls<
       FetchMoreOptions<TData, TGraphQLVariables>
   ) => Promise<ApolloQueryResult<TData>>;
   refetch: (variables?: TGraphQLVariables) => Promise<ApolloQueryResult<TData>>;
+  refresh: ObservableQuery<TData, TGraphQLVariables>["refresh"];
   startPolling: (pollInterval: number) => void;
   stopPolling: () => void;
   subscribeToMore: (options: SubscribeToMoreOptions) => () => void;

src/react/types/types.ts

@@ -61,6 +61,7 @@ export type ObservableQueryFields<TData, TVariables> = Pick<
   | 'subscribeToMore'
   | 'updateQuery'
   | 'refetch'
+  | 'refresh'
   | 'variables'
 > & {
   fetchMore: ((