Add more robust section for useLazyQuery

Author: jerelmiller

docs/source/data/queries.mdx

@@ -281,7 +281,277 @@ function GetDogsOnClick() {
 
 The first item in `useLazyQuery`'s return tuple is the execution function, and the second item is an object that contains information about the executed query, such as the `loading`, `error`, `data`, and `dataState` properties.
 
-For a full list of supported options, see the [API reference](../api/react/useLazyQuery).
+### Re-rendering with new options
+
+Unlike `useQuery`, options provided to `useLazyQuery` that change on re-renders do not automatically execute the query. Instead, `useLazyQuery` waits to execute the query using the updated options until the execution function is called again.
+
+The following is an example that changes the fetch policy depending on whether the user is online or offline:
+
+```tsx
+function GetDogs({ isOnline }) {
+  const [getDogs, { loading, data }] = useLazyQuery(GET_DOGS, {
+    fetchPolicy: isOnline ? "network-only" : "cache-only",
+  });
+
+  if (loading) return <p>Loading ...</p>;
+
+  return (
+    <div>
+      {data && <Dogs data={data.dogs} />}
+      <button onClick={() => getDogs()}>Get dogs</button>
+    </div>
+  );
+}
+```
+
+<Note>
+
+The changed options are immediately applied to the underlying `ObservableQuery` (accessible by the `observable` property) even though the query is not executed. Inspecting the options on the `observable` will return the updated options. This means the updated options will be used for other APIs (e.g. such as `refetch`), even before calling the execution function again.
+
+</Note>
+
+### Working with variables
+
+You provide `variables` to the execution function when executing the query.
+
+The following is an example that gets a specific dog's photo when clicking the "Get photo" button:
+
+```jsx
+function DogPhoto() {
+  const [getDogPhoto, { loading, error, data }] = useLazyQuery(GET_DOG_PHOTO);
+
+  if (loading) return <p>Loading ...</p>;
+  if (error) return `Error! ${error.message}`;
+
+  return (
+    <div>
+      {data?.dog && <img src={data.dog.displayImage} />}
+      <button onClick={() => getDogPhoto({ variables: { name: "Lucky" } })}>
+        Get photo
+      </button>
+    </div>
+  );
+}
+```
+
+<Note>
+
+When using TypeScript, the `variables` option is required along with any required variables when the query provided to `useLazyQuery` contains required variables. If the options argument is not provided to the execution function, or the `variables` option is missing required variables, you will see a TypeScript error.
+
+</Note>
+
+#### Changing variables
+
+You change variables by calling the execution function with updated variables.
+
+The following is an example that get's the selected dog's photo when clicking the "Get photo" button.
+
+```jsx
+function DogPhoto() {
+  const [selectedDog, setSelectedDog] = useState(null);
+  const [getDogPhoto, { loading, error, data }] = useLazyQuery(GET_DOG_PHOTO);
+
+  if (loading) return <p>Loading ...</p>;
+  if (error) return `Error! ${error.message}`;
+
+  return (
+    <div>
+      <DogSelect
+        onChange={(dogName) => setSelectedDog(dogName)}
+        value={selectedDog}
+      />
+      {data?.dog && <img src={data.dog.displayImage} />}
+      {selectedDog && (
+        <button
+          onClick={() => getDogPhoto({ variables: { name: selectedDog } })}
+        >
+          Get photo
+        </button>
+      )}
+    </div>
+  );
+}
+```
+
+If you need to reference the currently executed query's variables, use the `variables` property returned by `useLazyQuery`. The `variables` property contains the value of the most recently used variables provided from the last execution of the query.
+
+<Tip>
+
+The `variables` property is empty until the execution function is called for the first time. Use the `called` property returned by `useLazyQuery` to determine when the execution function has been called at least once.
+
+</Tip>
+
+```jsx
+function DogPhoto() {
+  const [getDogPhoto, { called, variables }] = useLazyQuery(GET_DOG_PHOTO);
+
+  return (
+    <div>
+      {/* ... */}
+      <button onClick={() => getDogPhoto({ variables: { name: selectedDog } })}>
+        Get photo
+      </button>
+
+      {called && <span>Last fetched: {variables.name}</span>}
+    </div>
+  );
+}
+```
+
+### Using the promise returned from the execution function
+
+The execution function returns a promise that resolves with the query result:
+
+```jsx
+function GetDogs() {
+  const [getDogs, { data, loading, error }] = useLazyQuery(GET_DOGS);
+
+  const handleClick = async () => {
+    const { data } = await getDogs();
+
+    // Do something with `data`
+  };
+
+  return (
+    <div>
+      {/* ... */}
+      <button onClick={handleClick}>Get dogs</button>
+    </div>
+  );
+}
+```
+
+The result returned from the promise is useful when you need to execute side-effects using the data returned by the query.
+
+<Tip>
+
+Use the `data`, `error`, and other properties returned by `useLazyQuery` to sync the query state with your component. Avoid using your own state setters from React's `useState` hook with data resolved from the promise. This ensures your component is kept up-to-date with cache changes as they occur throughout your application.<br /><br />
+
+In cases where you don't need to keep your component in sync with query state, use `client.query()` directly because it won't unnecessarily render your component for data that you don't use.
+
+<ExpansionPanel title="Example">
+
+```ts
+import { useApolloClient } from "@apollo/client/react";
+
+function GetDogs() {
+  const client = useApolloClient();
+
+  const handleClick = async () => {
+    const { data } = await client.query({ query: GET_DOGS });
+
+    // Do something with `data`
+  };
+
+  return <button onClick={handleClick}>Get dogs</button>;
+}
+```
+
+</ExpansionPanel>
+
+</Tip>
+
+#### Handling errors
+
+The promise resolves or rejects depending on the configured [`errorPolicy`](./error-handling#setting-an-error-policy). For a more comprehensive guide on working with errors, read the [Error handling documentation](./error-handling).
+
+##### `errorPolicy: "none"`
+
+The promise rejects with the error that caused the query to fail.
+
+```ts
+const handleClick = async () => {
+  try {
+    const { data } = await getDogs();
+  } catch (error) {
+    if (CombinedGraphQLErrors.is(error)) {
+      // handle GraphQL errors
+    }
+
+    // Handle other error types
+    console.log(error.message);
+  }
+};
+```
+
+<Note>
+
+Errors always cause the promise to reject. The `error` property is never set when the promise resolves.
+
+</Note>
+
+##### `errorPolicy: "all"`
+
+The promise resolves with an object that includes the error and any partial data returned by the query. Read the partial data on the `data` property and the error that caused the query to fail on the `error` property.
+
+```ts
+const handleClick = async () => {
+  const { data, error } = await getDogs();
+
+  if (error && CombinedGraphQLErrors.is(error)) {
+    // handle GraphQL errors returned by the query
+  }
+};
+```
+
+<Note>
+
+`data` might not contain any partial data will instead be set as `undefined`. This typically occurs when a [network error](./error-handling#network-errors) causes the query to fail since the error might not be associated with GraphQL execution.
+
+</Note>
+
+##### `errorPolicy: "ignore"`
+
+The promise resolves with an object that includes any partial data returned by the query. Errors are discarded.
+
+```ts
+const handleClick = async () => {
+  const { data } = await getDogs();
+
+  if (data !== undefined) {
+    // Do something with the returned data
+  }
+};
+```
+
+<Tip>
+
+`data` might be `undefined` in the event a [network error](./error-handling#network-errors) is raised. We recommend checking if `data` is `undefined` before attempting to use it in case an error occurs during query execution.
+
+</Tip>
+
+#### Retaining query results
+
+In-flight queries executed by `useLazyQuery` are aborted when the component unmounts, causing the promise to reject. In some cases, you may find this behavior undesirable and would prefer to let the query run to completion.
+
+The promise returned by the execution function includes a `.retain()` method. When called, it ensures the query continues running even when the component unmounts.
+
+```jsx
+function GetDogs() {
+  const [getDogs] = useLazyQuery(GET_DOGS);
+
+  const handleClick = async () => {
+    const promise = getDogs();
+
+    // Retain the query even if component unmounts
+    promise.retain();
+
+    const { data } = await promise;
+
+    // Do something with data
+  };
+
+  return <button onClick={handleClick}>Get dogs</button>;
+}
+```
+
+The `retain()` method returns the original promise. The previous example can be shortened to a single line:
+
+```ts
+const { data } = await getDogs().retain();
+```
+
+For a complete list of supported options and result properties, see the [API reference](../api/react/useLazyQuery).
 
 ## Setting a fetch policy