From e9dd7efa8eb684e31a4b3d1d900fff4a6fe86cfe Mon Sep 17 00:00:00 2001
From: Joe Reuter <johannes.reuter@elastic.co>
Date: Fri, 12 Aug 2022 20:57:06 +0200
Subject: [PATCH] [Lens] Add section for how to handle refresh using search
 sessions (#138396)

* update readme

* use refresh in example
---
 .../embedded_lens_example/public/app.tsx         | 16 ++++++++++++++++
 .../embedded_lens_example/public/mount.tsx       |  5 ++++-
 x-pack/plugins/lens/readme.md                    |  8 ++++++++
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/x-pack/examples/embedded_lens_example/public/app.tsx b/x-pack/examples/embedded_lens_example/public/app.tsx
index 3ef7721c58c02..fead11db04ed4 100644
--- a/x-pack/examples/embedded_lens_example/public/app.tsx
+++ b/x-pack/examples/embedded_lens_example/public/app.tsx
@@ -126,6 +126,9 @@ export const App = (props: {
     from: 'now-5d',
     to: 'now',
   });
+  const [searchSession, setSearchSession] = useState(() =>
+    props.plugins.data.search.session.start()
+  );
 
   const LensComponent = props.plugins.lens.EmbeddableComponent;
   const LensSaveModalComponent = props.plugins.lens.SaveModalComponent;
@@ -239,6 +242,18 @@ export const App = (props: {
                   Change time range
                 </EuiButton>
               </EuiFlexItem>
+              <EuiFlexItem grow={false}>
+                <EuiButton
+                  aria-label="Refresh"
+                  data-test-subj="lns-example-refresh"
+                  isDisabled={!attributes}
+                  onClick={() => {
+                    setSearchSession(props.plugins.data.search.session.start());
+                  }}
+                >
+                  Refresh
+                </EuiButton>
+              </EuiFlexItem>
             </EuiFlexGroup>
             <LensComponent
               id=""
@@ -246,6 +261,7 @@ export const App = (props: {
               style={{ height: 500 }}
               timeRange={time}
               attributes={attributes}
+              searchSessionId={searchSession}
               onLoad={(val) => {
                 setIsLoading(val);
               }}
diff --git a/x-pack/examples/embedded_lens_example/public/mount.tsx b/x-pack/examples/embedded_lens_example/public/mount.tsx
index 49775bca09b72..1c4608f17b52d 100644
--- a/x-pack/examples/embedded_lens_example/public/mount.tsx
+++ b/x-pack/examples/embedded_lens_example/public/mount.tsx
@@ -40,5 +40,8 @@ export const mount =
     );
 
     render(reactElement, element);
-    return () => unmountComponentAtNode(element);
+    return () => {
+      unmountComponentAtNode(element);
+      plugins.data.search.session.clear();
+    };
   };
diff --git a/x-pack/plugins/lens/readme.md b/x-pack/plugins/lens/readme.md
index 340931efdcd52..f851486e1581c 100644
--- a/x-pack/plugins/lens/readme.md
+++ b/x-pack/plugins/lens/readme.md
@@ -109,6 +109,14 @@ if (!dataView) {
 }
 const dataViewIdForLens = dataView.id;
 ```
+## Refreshing a Lens embeddable
+
+The Lens embeddable is handling data fetching internally, this means as soon as the props change, it will trigger a new request if necessary. However, in some situations it's necessary to trigger a refresh even if the configuration of the chart doesn't change at all. Refreshing is managed using search sessions is Lens. To trigger a refresh without changing the actual configuration of a Lens embeddable, follow these steps:
+* Pull in the contract of the `data` plugin. It contains the session service at `plugins.data.search.session`.
+* When loading the app containing a Lens embeddable, start a new session using `session.start`. It returns the current session id - keep it in the state of our app (e.g. a `useState` hook or your redux store)
+* Pass the current session id to the Lens embeddable component via the `searchSessionId` property
+* When refreshing, simply call `session.start` again and update your state - Lens will discard the existing cache and re-fetch even if the query doesn't change at all
+* When unmounting your app, call `session.clear` to end the current session
 
 # Lens Development