RDoc-2464_LongCountAsync - various updates in how-to-count-query-resu…

…lts and in how-to-get-query-statistics, including references to equivalent statistics methods.

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-count-query-results.markdown

@@ -1,54 +1,85 @@
-# Count Query Results  
+# Querying: Count Query Results  
 
 ---
 
 {NOTE: }
 
-* Count query results using one of the methods described below.  
+* To count query results, use the `Count` and `LongCount` methods as demonstrated below.  
+
+    {INFO: }
+    Read [here](../../../client-api/session/querying/how-to-get-query-statistics) 
+    how to retrieve query statistics, including the counting statistics described 
+    here and many others, using the `Statistics` method and references to 
+    `QueryStatistics` properties.  
+    {INFO/}
 
 * In This Page:  
-    * [CountAsync](../../../client-api/session/querying/how-to-count-query-results#countasync)  
-    * [LongCount and LongCountAsync](../../../client-api/session/querying/how-to-count-query-results#longcount-and-longcountasync)  
+    * [Count](../../../client-api/session/querying/how-to-count-query-results#count)  
+    * [LongCount](../../../client-api/session/querying/how-to-count-query-results#longcount)  
 
 {NOTE/}
 
 ---
 
-{PANEL: CountAsync}
+{PANEL: Count}
+
+To count the number of items returned by a query where an `Int32` 
+variable is expected to be sufficient for the resulting number, use 
+`Count` in a synchronous session or `CountAsync` in an async session.  
+
+### Exception
+If the number of items returned by the query exceeds `Int32.MaxValue`, 
+an `OverflowException` will be thrown.  
 
-To count query results where an `Int32` variable is sufficient, use the `CountAsync` method.  
-{CODE CountAsync@ClientApi\Session\Querying\HowToCountResults.cs /}
+### Example 
+{CODE-TABS}
+{CODE-TAB:csharp:Count Count@ClientApi\Session\Querying\HowToCountResults.cs /}
+{CODE-TAB:csharp:Count_async CountAsync@ClientApi\Session\Querying\HowToCountResults.cs /}
+{CODE-TABS/}
+
+{NOTE: }
+The query results count provided by `Count` can also be provided using 
+`QueryStatistics.TotalResults`, as demonstrated [here](../../../client-api/session/querying/how-to-get-query-statistics#example).  
+{NOTE/}
 
 {PANEL/}
 
-{PANEL: LongCount and LongCountAsync}
+{PANEL: LongCount}
 
-To count query results where an `Int64` variable is needed, use the 
-`LongCount` or `LongCountAsync` method.  
+To count query results where an `Int64` variable is needed for 
+the result, use `LongCount` in a synchronous session or `LongCountAsync` 
+in an async session.  
 
+### Example
 {CODE-TABS}
 {CODE-TAB:csharp:LongCount LongCount@ClientApi\Session\Querying\HowToCountResults.cs /}
-{CODE-TAB:csharp:LongCount_async LongCount_async@ClientApi\Session\Querying\HowToCountResults.cs /}
+{CODE-TAB:csharp:LongCount_async LongCountAsync@ClientApi\Session\Querying\HowToCountResults.cs /}
 {CODE-TABS/}
 
+{NOTE: }
+The query results count provided by `LongCount` can also be provided using 
+`QueryStatistics.LongTotalResults`, as explained [here](../../../client-api/session/querying/how-to-get-query-statistics).  
+{NOTE/}
+
 {PANEL/}
 
 ## Related Articles
 
 ### Client API
 
-- [What is a Document Query](../../../client-api/session/querying/document-query/what-is-document-query)
-- [How to Filter by Field Presence](../../../client-api/session/querying/how-to-filter-by-field)
+- [What is a Document Query](../../../client-api/session/querying/document-query/what-is-document-query)  
+- [Filter by Field Presence](../../../client-api/session/querying/how-to-filter-by-field)  
+- [Get Query Statistics](../../../client-api/session/querying/how-to-get-query-statistics)  
 
 ### Querying
 
-- [Querying: Filtering](../../../indexes/querying/filtering)
-- [Query vs DocumentQuery](../../../client-api/session/querying/document-query/query-vs-document-query)
-- [RQL - Raven Query Language](../../../client-api/session/querying/what-is-rql)
+- [Filtering](../../../indexes/querying/filtering)  
+- [Query vs DocumentQuery](../../../client-api/session/querying/document-query/query-vs-document-query)  
+- [RQL - Raven Query Language](../../../client-api/session/querying/what-is-rql)  
 
 ---
 
-### Code Walkthrough
+### Code Walkthrough: Queries
 
-- [Queries - Filtering Results - Basics](https://demo.ravendb.net/demos/csharp/queries/filtering-results-basics)
-- [Queries - Filtering with Multiple Conditions](https://demo.ravendb.net/demos/csharp/queries/filtering-results-multiple-conditions)
+- [Filtering Results Basics](https://demo.ravendb.net/demos/csharp/queries/filtering-results-basics)  
+- [Filtering with Multiple Conditions](https://demo.ravendb.net/demos/csharp/queries/filtering-results-multiple-conditions)  

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-get-query-statistics.dotnet.markdown

@@ -0,0 +1,58 @@
+# Querying: How to Get Query Statistics
+
+---
+
+{NOTE: }
+
+* Detailed **Query Statistics** can be retrieved for every executed query 
+  using the `Statistics` method.  
+* Statistics are returned in a `QueryStatistics` instance, including query 
+  duration, total results number, and various other details.  
+
+* In This Page:  
+   * [QueryStatistics](../../../client-api/session/querying/how-to-get-query-statistics#querystatistics)  
+
+{NOTE/}
+
+---
+
+{PANEL: QueryStatistics}
+
+### Syntax
+
+{CODE stats_1@ClientApi\Session\Querying\HowToGetQueryStatistics.cs /}
+
+| Parameters | Type | Details |
+| ------------- | ------------- | ----- |
+| **stats** | `QueryStatistics` | Query Statistics |
+
+
+### `QueryStatistics`
+{CODE QueryStatisticsDefinition@ClientApi\Session\Querying\HowToGetQueryStatistics.cs /}
+
+| Property | Type | Details |
+| ------------- | ------------- | ----- |
+| **IsStale** | `bool` | Are the results returned by the query potentially stale |
+| **DurationInMs** | `long` | Query duration on the server side in Milliseconds |
+| **TotalResults** | `int` | The total count of results that matched the query. <br> Matching query results can also be counted using [Count](../../../client-api/session/querying/how-to-count-query-results#count). |
+| **LongTotalResults** | `long` | The total count of the results that matched the query as `int64`. <br> Matching query results can also be counted as `int64` using [LongCount](../../../client-api/session/querying/how-to-count-query-results#longcount). |
+| **SkippedResults** | `int` | Gets or sets the [skipped results](../../../indexes/querying/paging#paging-through-tampered-results) |
+| **Timestamp** | `DateTime` | The time when the query results were unstale |
+| **IndexName** | `string` | The name of the queried index |
+| **DateTime** | `IndexTimestamp` | The timestamp of the queried index |
+| **LastQueryTime** | `DateTime` | The timestamp of the last time the index was queried |
+| **ResultEtag** | `long?` | Results Etag |
+| **NodeTag** | `string` | Tag of a cluster node that responded to the query |
+
+### Example
+
+{CODE stats_2@ClientApi\Session\Querying\HowToGetQueryStatistics.cs /}
+
+{PANEL/}
+
+## Related articles
+
+### Session
+
+- [How to Query](../../../client-api/session/querying/how-to-query)
+- [How to **Customize** Query?](../../../client-api/session/querying/how-to-customize-query)

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-get-query-statistics.java.markdown

@@ -0,0 +1,22 @@
+# Session: Querying: How to Get Query Statistics
+
+Query statistics can provide important information about a query like duration, total number of results, staleness information, etc. To access statistics use the `statistics` method.
+
+## Syntax
+
+{CODE:java stats_1@ClientApi\Session\Querying\HowToGetQueryStatistics.java /}
+
+| Parameters | | |
+| ------------- | ------------- | ----- |
+| **stats** | `QueryStatistics` | Statistics for query. |
+
+## Example
+
+{CODE:java stats_2@ClientApi\Session\Querying\HowToGetQueryStatistics.java /}
+
+## Related articles
+
+### Session
+
+- [How to Query](../../../client-api/session/querying/how-to-query)
+- [How to **Customize** Query?](../../../client-api/session/querying/how-to-customize-query)

Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-get-query-statistics.js.markdown

@@ -0,0 +1,22 @@
+# Session: Querying: How to Get Query Statistics
+
+Query statistics can provide important information about a query like duration, total number of results, staleness information, etc. To access statistics use the `statistics()` method.
+
+## Syntax
+
+{CODE:nodejs stats_1@ClientApi\Session\Querying\howToGetQueryStatistics.js /}
+
+| Parameters | | |
+| ------------- | ------------- | ----- |
+| **statsCallback** | `(stats) => void` | Callback passing the `QueryStatistics` object for query. |
+
+## Example
+
+{CODE:nodejs stats_2@ClientApi\Session\Querying\howToGetQueryStatistics.js /}
+
+## Related articles
+
+### Session
+
+- [How to Query](../../../client-api/session/querying/how-to-query)
+- [How to **Customize** Query?](../../../client-api/session/querying/how-to-customize-query)

Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/Querying/HowToCountResults.cs

@@ -7,11 +7,42 @@
 using static NodaTime.TimeZones.ZoneEqualityComparer;
 using Xunit;
 using System.Threading.Tasks;
+using System.Linq;
 
 namespace Raven.Documentation.Samples.ClientApi.Session.Querying
 {
     public class CountQueryResults
     {
+        public void CanUseCount(Options options)
+        {
+            using (var store = new DocumentStore())
+            {
+                using (var s = store.OpenSession())
+                {
+                    s.Store(new User
+                    {
+                        Name = "John"
+                    });
+
+                    s.SaveChanges();
+                }
+
+                using (var s = store.OpenSession())
+                {
+                    QueryStatistics stats;
+
+                    #region Count
+                    // Use Count in a synchronous session
+                    System.Int32 Count = 
+                        s.Query<User>()
+                            .Statistics(out stats)
+                            .Search(u => u.Name, "John")
+                            .Count();
+                    #endregion
+                }
+            }
+        }
+
         public async Task CanUseCountAsync(Options options)
         {
             using (var store = new DocumentStore())
@@ -31,6 +62,7 @@ await s.StoreAsync(new User
                     QueryStatistics stats;
 
                     #region CountAsync
+                    // Use CountAsync in an Async session
                     System.Int32 count = await
                         s.Query<User>()
                             .Statistics(out stats)
@@ -61,10 +93,11 @@ public void CanUseLongCount(Options options)
 
                     #region LongCount
                     // Use LongCount in a synchronous session
-                    System.Int64 longCount = s.Query<User>()
-                        .Statistics(out stats)
-                        .Search(u => u.Name, "John")
-                        .LongCount();
+                    System.Int64 longCount = 
+                        s.Query<User>()
+                            .Statistics(out stats)
+                            .Search(u => u.Name, "John")
+                            .LongCount();
                     #endregion
                 }
             }
@@ -88,7 +121,7 @@ await s.StoreAsync(new User
                 {
                     QueryStatistics stats;
 
-                    #region LongCount_async
+                    #region LongCountAsync
                     // Use LongCountAsync in an Async session
                     System.Int64 longCount = await
                         s.Query<User>()

Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/Querying/HowToGetQueryStatistics.cs

@@ -0,0 +1,59 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Raven.Client.Documents;
+using Raven.Client.Documents.Linq;
+using Raven.Client.Documents.Session;
+using Raven.Documentation.Samples.Orders;
+
+namespace Raven.Documentation.Samples.ClientApi.Session.Querying
+{
+    public class HowToGetQueryStatistics
+    {
+        private interface IFoo<TResult>
+        {
+            #region stats_1
+            IRavenQueryable<T> Statistics(out QueryStatistics stats);
+            #endregion
+        }
+
+        public HowToGetQueryStatistics()
+        {
+            using (var store = new DocumentStore())
+            {
+                using (var session = store.OpenSession())
+                {
+                    #region stats_2
+                    List<Employee> employees = session.Query<Employee>()
+                        .Where(x => x.FirstName == "John")
+                        .Statistics(out QueryStatistics stats) // Get query statistics
+                        .ToList();
+
+                    int totalResults = stats.TotalResults; // Get matching results count
+                    long durationInMilliseconds = stats.DurationInMs; // Get query duration
+                    #endregion
+                }
+            }
+        }
+    }
+
+    public class foo
+    {
+        #region QueryStatisticsDefinition
+        public class QueryStatistics
+        {
+            public bool IsStale { get; set; }
+            public long DurationInMs { get; set; }
+            public int TotalResults { get; set; }
+            public long LongTotalResults { get; set; }
+            public int SkippedResults { get; set; }
+            public DateTime Timestamp { get; set; }
+            public string IndexName { get; set; }
+            public DateTime IndexTimestamp { get; set; }
+            public DateTime LastQueryTime { get; set; }
+            public long? ResultEtag { get; set; }
+            public string NodeTag { get; set; }
+        }
+        #endregion
+    }
+}

Documentation/5.2/Samples/java/src/test/java/net/ravendb/ClientApi/Session/Querying/HowToGetQueryStatistics.java

@@ -0,0 +1,40 @@
+package net.ravendb.ClientApi.Session.Querying;
+
+import net.ravendb.client.documents.DocumentStore;
+import net.ravendb.client.documents.IDocumentStore;
+import net.ravendb.client.documents.session.IDocumentQuery;
+import net.ravendb.client.documents.session.IDocumentSession;
+import net.ravendb.client.documents.session.QueryStatistics;
+import net.ravendb.client.primitives.Reference;
+
+import java.util.List;
+
+public class HowToGetQueryStatistics {
+    private interface IFoo<T> {
+        //region stats_1
+        IDocumentQuery<T> statistics(Reference<QueryStatistics> stats);
+        //endregion
+    }
+
+    public HowToGetQueryStatistics() {
+        try (IDocumentStore store = new DocumentStore()) {
+            try (IDocumentSession session = store.openSession()) {
+                //region stats_2
+                Reference<QueryStatistics> stats = new Reference<>();
+
+                List<Employee> employees = session.query(Employee.class)
+                    .whereEquals("FirstName", "Robert")
+                    .statistics(stats)
+                    .toList();
+
+                int totalResults = stats.value.getTotalResults();
+                long durationInMs = stats.value.getDurationInMs();
+                //endregion
+            }
+        }
+    }
+
+    private static class Employee {
+
+    }
+}