RDoc-2451 Client API > Session > Querying > Queries lazily - Part 10

ravendb · Jun 25, 2023 · 5a27a44 · 5a27a44
1 parent 2edce6a
commit 5a27a44
Show file tree

Hide file tree

Showing 7 changed files with 234 additions and 60 deletions.
diff --git a/...ation.Pages/client-api/session/how-to/perform-operations-lazily.dotnet.markdown b/...ation.Pages/client-api/session/how-to/perform-operations-lazily.dotnet.markdown
@@ -1,5 +1,4 @@
 # Perform requests lazily
-
 ---
 
 {NOTE: }
@@ -35,6 +34,8 @@
 
 {NOTE/}
 
+---
+
 {PANEL: Requests that can be executed lazily}
 
 {NOTE: }

diff --git a/...mentation.Pages/client-api/session/how-to/perform-operations-lazily.js.markdown b/...mentation.Pages/client-api/session/how-to/perform-operations-lazily.js.markdown
@@ -1,26 +1,41 @@
 # Perform requests lazily
-
 ---
 
 {NOTE: }
 
-* **Defining a lazy operation** allows deferring the execution of the operation until it is needed.  
+* __Lazy request__:
+
+    * You can define a lazy request within a session (e.g. a lazy-query or a lazy-load request)  
+      and defer its execution until actually needed.
+
+    * The lazy request definition is stored in the session and a `Lazy` instance is returned.  
+      The request will be sent to the server and executed only when you access the value of this instance.
+
+* __Multiple lazy requests__:
 
-* Multiple pending lazy operations can be executed together, see below. 
+    * Multiple lazy requests can be defined within the same session.
+
+    * When triggering the deferred execution (whether implicitly or explicitly),  
+      ALL pending lazy requests held up by the session will be sent to the server in a single call.  
+      This can help reduce the number of remote calls made to the server over the network.
 
 * In this page:
-   * [Operations that can be executed lazily](../../../client-api/session/how-to/perform-operations-lazily#operations-that-can-be-executed-lazily)  
-      * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)  
-      * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)  
-      * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
-      * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
-      * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
-      * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)  
-      * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)     
-   * [Execute all pending lazy operations](../../../client-api/session/how-to/perform-operations-lazily#execute-all-pending-lazy-operations)  
+    * [Requests that can be executed lazily:](../../../client-api/session/how-to/perform-operations-lazily#requests-that-can-be-executed-lazily)
+        * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)
+        * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)
+        * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
+        * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
+        * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
+        * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)
+        * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)
+    * [Multiple lazy requests](../../../client-api/session/how-to/perform-operations-lazily#multiple-lazy-requests)
+        * [Execute all requests - implicitly](../../../client-api/session/how-to/perform-operations-lazily#implicit)
+        * [Execute all requests - explicitly](../../../client-api/session/how-to/perform-operations-lazily#explicit)
 
 {NOTE/}
 
+---
+
 {PANEL: Operations that can be executed lazily}
 
 {NOTE: }
@@ -94,11 +109,21 @@
 
 {PANEL/}
 
-{PANEL: Execute all pending lazy operations}
+{PANEL: Multiple lazy requests }
 
-* Use `executeAllPendingLazyOperations` to execute **all** pending lazy operations at once. 
+{NOTE: }
+<a id="implicit" /> __Execute all requests - implicitly__
 
-{CODE:nodejs lazy_executeAllPendingLazyOperations@ClientApi\Session\HowTo\lazy.js /}
+{CODE:nodejs lazy_ExecuteAll_Implicit@ClientApi\Session\HowTo\lazy.js /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="explicit" /> __Execute all requests - explicitly__
+
+{CODE:nodejs lazy_ExecuteAll_Explicit@ClientApi\Session\HowTo\lazy.js /}
+
+{NOTE/}
 
 {PANEL/}
 

diff --git a/Documentation/5.2/Samples/nodejs/ClientApi/Session/HowTo/lazy.js b/Documentation/5.2/Samples/nodejs/ClientApi/Session/HowTo/lazy.js
@@ -134,19 +134,51 @@ async function lazyExamples() {
         //endregion
     }
     {
-        //region lazy_executeAllPendingLazyOperations
+        //region lazy_ExecuteAll_Implicit
         // Define multiple lazy requests
         const lazyUser1 = session.advanced.lazily.load("users/1-A");
         const lazyUser2 = session.advanced.lazily.load("users/2-A");
-        const lazyEmployees = session.query({ collection: "employees" }).lazily();
+
+        const lazyEmployees = session.query({ collection: "employees" })
+            .lazily();
+        const lazyProducts = session.query({ collection: "products" })
+            .search("Name", "Ch*")
+            .lazily();
+
+        // Accessing the value of ANY of the lazy instances will trigger
+        // the execution of ALL pending lazy requests held up by the session
+        // This is done in a SINGLE server call
+        const user1 = await lazyUser1.getValue();
+
+        // ALL the other values are now also available
+        // No additional server calls are made when accessing these values
+        const user2 = await lazyUser2.getValue();
+        const employees = await lazyEmployees.getValue();
+        const products = await lazyProducts.getValue();
+        //endregion
+    }
+    {
+        //region lazy_ExecuteAll_Explicit
+        // Define multiple lazy requests
+        const lazyUser1 = session.advanced.lazily.load("users/1-A");
+        const lazyUser2 = session.advanced.lazily.load("users/2-A");
+
+        const lazyEmployees = session.query({ collection: "employees" })
+            .lazily();
+        const lazyProducts = session.query({ collection: "products" })
+            .search("Name", "Ch*")
+            .lazily();
 
-        // Execute all pending lazy operations
+        // Explicitly call 'executeAllPendingLazyOperations'
+        // ALL pending lazy requests held up by the session will be executed in a SINGLE server call
         await session.advanced.eagerly.executeAllPendingLazyOperations();
 
-        // All values are now available
+        // ALL values are now available
+        // No additional server calls are made when accessing the values
         const user1 = await lazyUser1.getValue();
         const user2 = await lazyUser2.getValue();
         const employees = await lazyEmployees.getValue();
+        const products = await lazyProducts.getValue();
         //endregion
     }
     {

diff --git a/...ation.Pages/client-api/session/how-to/perform-operations-lazily.dotnet.markdown b/...ation.Pages/client-api/session/how-to/perform-operations-lazily.dotnet.markdown
@@ -1,26 +1,41 @@
 # Perform requests lazily
-
 ---
 
 {NOTE: }
 
-* **Defining a lazy operation** allows deferring the execution of the operation until it is needed.  
+* __Lazy request__:
+
+    * You can define a lazy request within a session (e.g. a lazy-query or a lazy-load request)  
+      and defer its execution until actually needed.
+
+    * The lazy request definition is stored in the session and a `Lazy<T>` instance is returned.  
+      The request will be sent to the server and executed only when you access the value of this instance.
+
+* __Multiple lazy requests__:
 
-* Multiple pending lazy operations can be executed together, see below. 
+    * Multiple lazy requests can be defined within the same session.
+
+    * When triggering the deferred execution (whether implicitly or explicitly),  
+      ALL pending lazy requests held up by the session will be sent to the server in a single call.  
+      This can help reduce the number of remote calls made to the server over the network.
 
 * In this page:
-   * [Operations that can be executed lazily](../../../client-api/session/how-to/perform-operations-lazily#operations-that-can-be-executed-lazily)  
-      * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)  
-      * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)  
-      * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
-      * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
-      * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
-      * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)  
-      * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)     
-   * [Execute all pending lazy operations](../../../client-api/session/how-to/perform-operations-lazily#execute-all-pending-lazy-operations)  
+    * [Requests that can be executed lazily:](../../../client-api/session/how-to/perform-operations-lazily#requests-that-can-be-executed-lazily)
+        * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)
+        * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)
+        * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
+        * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
+        * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
+        * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)
+        * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)
+    * [Multiple lazy requests](../../../client-api/session/how-to/perform-operations-lazily#multiple-lazy-requests)
+        * [Execute all requests - implicitly](../../../client-api/session/how-to/perform-operations-lazily#implicit)
+        * [Execute all requests - explicitly](../../../client-api/session/how-to/perform-operations-lazily#explicit)
 
 {NOTE/}
 
+---
+
 {PANEL: Operations that can be executed lazily}
 
 {NOTE: }
@@ -94,11 +109,21 @@
 
 {PANEL/}
 
-{PANEL: Execute all pending lazy operations}
+{PANEL: Multiple lazy requests }
 
-* Use `ExecuteAllPendingLazyOperations` to execute **all** pending lazy operations at once. 
+{NOTE: }
+<a id="implicit" /> __Execute all requests - implicitly__
 
-{CODE lazy_ExecuteAllPendingLazyOperations@ClientApi\Session\HowTo\Lazy.cs /}
+{CODE lazy_ExecuteAll_Implicit@ClientApi\Session\HowTo\Lazy.cs /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="explicit" /> __Execute all requests - explicitly__
+
+{CODE lazy_ExecuteAll_Explicit@ClientApi\Session\HowTo\Lazy.cs /}
+
+{NOTE/}
 
 {PANEL/}
 

diff --git a/...mentation.Pages/client-api/session/how-to/perform-operations-lazily.js.markdown b/...mentation.Pages/client-api/session/how-to/perform-operations-lazily.js.markdown
@@ -1,26 +1,41 @@
 # Perform requests lazily
-
 ---
 
 {NOTE: }
 
-* **Defining a lazy operation** allows deferring the execution of the operation until it is needed.  
+* __Lazy request__:
+
+    * You can define a lazy request within a session (e.g. a lazy-query or a lazy-load request)  
+      and defer its execution until actually needed.
+
+    * The lazy request definition is stored in the session and a `Lazy` instance is returned.  
+      The request will be sent to the server and executed only when you access the value of this instance.
+
+* __Multiple lazy requests__:
 
-* Multiple pending lazy operations can be executed together, see below. 
+    * Multiple lazy requests can be defined within the same session.
+
+    * When triggering the deferred execution (whether implicitly or explicitly),  
+      ALL pending lazy requests held up by the session will be sent to the server in a single call.  
+      This can help reduce the number of remote calls made to the server over the network.
 
 * In this page:
-   * [Operations that can be executed lazily](../../../client-api/session/how-to/perform-operations-lazily#operations-that-can-be-executed-lazily)  
-      * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)  
-      * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)  
-      * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
-      * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
-      * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
-      * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)  
-      * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)     
-   * [Execute all pending lazy operations](../../../client-api/session/how-to/perform-operations-lazily#execute-all-pending-lazy-operations)  
+    * [Requests that can be executed lazily:](../../../client-api/session/how-to/perform-operations-lazily#requests-that-can-be-executed-lazily)
+        * [Load entities](../../../client-api/session/how-to/perform-operations-lazily#loadEntities)
+        * [Load entities with include](../../../client-api/session/how-to/perform-operations-lazily#loadWithInclude)
+        * [Load entities starting with](../../../client-api/session/how-to/perform-operations-lazily#loadStartingWith)
+        * [Conditional load](../../../client-api/session/how-to/perform-operations-lazily#conditionalLoad)
+        * [Run query](../../../client-api/session/how-to/perform-operations-lazily#runQuery)
+        * [Get revisions](../../../client-api/session/how-to/perform-operations-lazily#getRevisions)
+        * [Get compare-exchange value](../../../client-api/session/how-to/perform-operations-lazily#getCompareExchange)
+    * [Multiple lazy requests](../../../client-api/session/how-to/perform-operations-lazily#multiple-lazy-requests)
+        * [Execute all requests - implicitly](../../../client-api/session/how-to/perform-operations-lazily#implicit)
+        * [Execute all requests - explicitly](../../../client-api/session/how-to/perform-operations-lazily#explicit)
 
 {NOTE/}
 
+---
+
 {PANEL: Operations that can be executed lazily}
 
 {NOTE: }
@@ -94,11 +109,21 @@
 
 {PANEL/}
 
-{PANEL: Execute all pending lazy operations}
+{PANEL: Multiple lazy requests }
 
-* Use `executeAllPendingLazyOperations` to execute **all** pending lazy operations at once. 
+{NOTE: }
+<a id="implicit" /> __Execute all requests - implicitly__
 
-{CODE:nodejs lazy_executeAllPendingLazyOperations@client-api\Session\HowTo\lazy.js /}
+{CODE:nodejs lazy_ExecuteAll_Implicit@client-api\Session\HowTo\lazy.js /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="explicit" /> __Execute all requests - explicitly__
+
+{CODE:nodejs lazy_ExecuteAll_Explicit@client-api\Session\HowTo\lazy.js /}
+
+{NOTE/}
 
 {PANEL/}
 

diff --git a/Documentation/5.3/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/HowTo/Lazy.cs b/Documentation/5.3/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/HowTo/Lazy.cs
@@ -116,7 +116,7 @@ public Lazy()
                 using (var session = store.OpenSession())
                 {
                     #region lazy_Revisions 
-                    var lazyRevisions = session
+                    Lazy<List<Employee>> lazyRevisions = session
                          // Add a call to Lazily 
                         .Advanced.Revisions.Lazily
                          // Revisions will Not be fetched here, no server call is made
@@ -140,7 +140,7 @@ public Lazy()
                     session.SaveChanges();
 
                     // Get the compare-exchange value lazily: 
-                    var lazyCmpXchg = session
+                    Lazy<CompareExchangeValue<string>> lazyCmpXchg = session
                         // Add a call to Lazily 
                         .Advanced.ClusterTransaction.Lazily
                         // Compare-exchange values will Not be fetched here, no server call is made
@@ -156,19 +156,53 @@ public Lazy()
 
                 using (var session = store.OpenSession())
                 {
-                    #region lazy_ExecuteAllPendingLazyOperations
+                    #region lazy_ExecuteAll_Implicit
                     // Define multiple lazy requests
                     Lazy<User> lazyUser1 = session.Advanced.Lazily.Load<User>("users/1-A");
                     Lazy<User> lazyUser2 = session.Advanced.Lazily.Load<User>("users/2-A");
-                    Lazy<IEnumerable<Employee>> lazyEmployees = session.Query<Employee>().Lazily();
+
+                    Lazy<IEnumerable<Employee>> lazyEmployees = session.Query<Employee>()
+                        .Lazily();
+                    Lazy<IEnumerable<Product>> lazyProducts = session.Query<Product>()
+                        .Search(x => x.Name, "Ch*")
+                        .Lazily();
+
+                    // Accessing the value of ANY of the lazy instances will trigger
+                    // the execution of ALL pending lazy requests held up by the session
+                    // This is done in a SINGLE server call
+                    User user1 = lazyUser1.Value;
+
+                    // ALL the other values are now also available
+                    // No additional server calls are made when accessing these values
+                    User user2 = lazyUser2.Value;
+                    IEnumerable<Employee> employees = lazyEmployees.Value;
+                    IEnumerable<Product> products = lazyProducts.Value;
+                    #endregion
+                }
+
+                using (var session = store.OpenSession())
+                {
+                    #region lazy_ExecuteAll_Explicit
+                    // Define multiple lazy requests
+                    Lazy<User> lazyUser1 = session.Advanced.Lazily.Load<User>("users/1-A");
+                    Lazy<User> lazyUser2 = session.Advanced.Lazily.Load<User>("users/2-A");
+
+                    Lazy<IEnumerable<Employee>> lazyEmployees = session.Query<Employee>()
+                        .Lazily();
+                    Lazy<IEnumerable<Product>> lazyProducts = session.Query<Product>()
+                        .Search(x => x.Name, "Ch*")
+                        .Lazily();
 
-                    // Execute all pending lazy operations
+                    // Explicitly call 'ExecuteAllPendingLazyOperations'
+                    // ALL pending lazy requests held up by the session will be executed in a SINGLE server call
                     session.Advanced.Eagerly.ExecuteAllPendingLazyOperations();
 
-                    // All values are now available
+                    // ALL values are now available
+                    // No additional server calls are made when accessing the values
                     User user1 = lazyUser1.Value;
                     User user2 = lazyUser2.Value;
                     IEnumerable<Employee> employees = lazyEmployees.Value;
+                    IEnumerable<Product> products = lazyProducts.Value;
                     #endregion
                 }
             }