RDoc-2874 [Node.js] Document extensions > Time series > Querying > Choose query range [Replace C# samples]

Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.dotnet.markdown

@@ -17,11 +17,11 @@
         * [Query usage](../../../../document-extensions/timeseries/client-api/session/querying#query-usage)
         * [Query examples](../../../../document-extensions/timeseries/client-api/session/querying#query-examples)  
         * [Query syntax](../../../../document-extensions/timeseries/client-api/session/querying#query-syntax)
-    * [DocumentQuery](../../../../document-extensions/timeseries/client-api/session/querying#document-query)
+    * [DocumentQuery](../../../../document-extensions/timeseries/client-api/session/querying#documentquery)
         * [DocumentQuery usage](../../../../document-extensions/timeseries/client-api/session/querying#documentquery-usage)
         * [DocumentQuery examples](../../../../document-extensions/timeseries/client-api/session/querying#documentquery-examples)
-        * [DocumentQuery Syntax](../../../../document-extensions/timeseries/client-api/session/querying#documentquery-examples)
-    * [RawQuery](../../../../document-extensions/timeseries/client-api/session/querying#raw-query)
+        * [DocumentQuery Syntax](../../../../document-extensions/timeseries/client-api/session/querying#documentquery-syntax)
+    * [RawQuery](../../../../document-extensions/timeseries/client-api/session/querying#rawquery)
         * [RawQuery usage](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-usage)
         * [RawQuery examples](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-examples)
         * [RawQuery syntax](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-syntax)
@@ -101,11 +101,34 @@ The aggregated results are retrieved as `List<TimeSeriesAggregationResult>`.
 
 ### Query syntax
 
-`session.Query` Definition:
+* The `session.Query` syntax is available [here](../../../../client-api/session/querying/how-to-query#syntax).
 
-{CODE Query-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+* To define a time series query use `RavenQuery.TimeSeries` within the query `Select` clause.
 
-Learn more about `session.Query` [here](../../../../client-api/session/querying/how-to-query#session.query).
+* `RavenQuery.TimeSeries` overloads:
+
+    {CODE RavenQuery-TimeSeries-Definition-Without-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+    {CODE RavenQuery-TimeSeries-Definition-With-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+
+    | Parameter            | Type       | Description                             |
+    |----------------------|------------|-----------------------------------------|
+    | **documentInstance** | `object`   | Document Instance                       |
+    | **name**             | `string`   | Time Series Name                        |
+    | **from** (optional)  | `DateTime` | Range Start<br> Default: `DateTime.Min` |
+    | **to** (optional)    | `DateTime` | Range End<br> Default: `DateTime.Max`   |
+
+* `RavenQuery.TimeSeries` can be extended with the following time series methods:
+
+    {CODE-BLOCK:csharp}
+Offset(TimeSpan offset);
+Scale(double value);
+FromLast(Action<ITimePeriodBuilder> timePeriod);
+FromFirst(Action<ITimePeriodBuilder> timePeriod);
+LoadByTag<TEntity>();
+GroupBy(string s);
+GroupBy(Action<ITimePeriodBuilder> timePeriod);
+Where(Expression<Func<TimeSeriesEntry, bool>> predicate);
+    {CODE-BLOCK/}
 
 {PANEL/}
 
@@ -133,11 +156,13 @@ Learn more about `session.Query` [here](../../../../client-api/session/querying/
 
 {NOTE: }
 A _DocumentQuery_ using only the `From()` method.  
+The query returns all entries from the 'HeartRates' time series.
 {CODE TS_DocQuery_1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}  
 {NOTE/}
 
 {NOTE: }
 A _DocumentQuery_ using `Between()`.  
+The query returns only entries from the specified time range.
 {CODE TS_DocQuery_2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}  
 {NOTE/}
 

Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.js.markdown

@@ -16,7 +16,7 @@
         * [Query usage](../../../../document-extensions/timeseries/client-api/session/querying#query-usage)
         * [Query examples](../../../../document-extensions/timeseries/client-api/session/querying#query-examples)  
         * [Query syntax](../../../../document-extensions/timeseries/client-api/session/querying#query-syntax)
-    * [RawQuery](../../../../document-extensions/timeseries/client-api/session/querying#raw-query)
+    * [RawQuery](../../../../document-extensions/timeseries/client-api/session/querying#rawquery)
         * [RawQuery usage](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-usage)
         * [RawQuery examples](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-examples)
         * [RawQuery syntax](../../../../document-extensions/timeseries/client-api/session/querying#rawquery-syntax)

Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.dotnet.markdown

@@ -0,0 +1,199 @@
+# Choosing Time Series Range
+
+---
+
+{NOTE: }
+
+* Queries can retrieve data from the entire time series or from a specific range of entries,  
+  such as those collected in the last 7 days.
+
+* For an overview of the available time series queries and their syntax, please refer to [Time series querying](../../../document-extensions/timeseries/client-api/session/querying).
+
+* In this page:
+    * [Choose range in a query](../../../document-extensions/timeseries/querying/choosing-query-range#choose-range-in-a-query)
+      * [Specify range](../../../document-extensions/timeseries/querying/choosing-query-range#specify-range)
+      * [Retrieve first or last entries](../../../document-extensions/timeseries/querying/choosing-query-range#retrieve-first-or-last-entries)
+    * [Choose range - RQL syntax](../../../document-extensions/timeseries/querying/choosing-query-range#choose-range---rql-syntax)
+      * [`between` and `and`](../../../document-extensions/timeseries/querying/choosing-query-range#and)
+      * [`first` and `last`](../../../document-extensions/timeseries/querying/choosing-query-range#and-1)
+
+{NOTE/}
+
+---
+
+{PANEL: Choose range in a query}
+
+{NOTE: }
+
+#### Specify range
+
+* Provide 'from' & 'to' DateTime values to the time series query to retrieve entries only from that range (inclusive).
+  Omitting these parameters will retrieve the entire series.
+
+* The provided DateTime values are treated by the server as UTC.  
+  The client does Not perform any conversion to UTC prior to sending the request to the server.
+
+* In this example, we specify a 10-minute range from which to retrieve "HeartRates" entries for UK employees.  
+
+{CODE-TABS}
+{CODE-TAB:csharp:Query choose_range_1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB:csharp:DocumentQuery choose_range_2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB:csharp:RawQuery choose_range_3@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB-BLOCK:sql:RQL}
+from "Employees" as employee
+where employee.Address.Country == "UK"
+select timeseries(
+    from employee.HeartRates
+    between "2020-05-17T00:00:00.0000000"
+    and "2020-05-17T00:10:00.0000000"
+    offset "03:00"
+)
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+{NOTE/}
+
+{NOTE: }
+
+#### Retrieve first or last entries
+
+* Use `FromFirst()` to specify the time frame from the start of the time series.  
+  Use `FromLast()` to specify the time frame from the end of the time series.  
+  Only one of them can be used in the same query function.  
+
+* In this example, we select only the entries in the last 30 minutes of time series "HeartRates".
+
+{CODE-TABS}
+{CODE-TAB:csharp:Query choose_range_4@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB:csharp:DocumentQuery choose_range_5@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB:csharp:RawQuery choose_range_6@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE-TAB-BLOCK:sql:RQL}
+from "Employees" as e 
+select timeseries(
+    from e.HeartRates
+    last 30 min
+    offset "03:00"
+)
+{CODE-TAB-BLOCK/}
+{CODE-TABS/}
+
+{NOTE/}
+{PANEL/}
+
+{PANEL: Choose range - RQL syntax}
+
+{NOTE: }
+
+#### `between` and `and`
+
+---
+
+* Use the `between` and `and` keywords to retrieve time series entries from the specified range (inclusive).  
+  Provide the timestamps in UTC format.
+  E.g.:  
+
+    {CODE-TABS}
+{CODE-TAB-BLOCK:sql:RQL_select_syntax}
+from "Employees"
+where Address.Country == "UK"
+select timeseries(
+    from HeartRates
+    between "2020-05-17T00:00:00.0000000Z" // start of range
+    and "2020-05-17T01:00:00.0000000Z"     // end of range
+)
+
+// Results will include only time series entries within the specified range for employees from UK.
+{CODE-TAB-BLOCK/}
+{CODE-TAB-BLOCK:sql:RQL_declare_syntax}
+declare timeseries getHeartRates(employee)
+{
+    from HeartRates
+    between "2020-05-17T00:00:00.0000000Z" // start of range
+    and "2020-05-17T01:00:00.0000000Z"     // end of range
+}
+
+from "Employees" as e
+where e.Address.Country == "UK"
+select getHeartRates(e) 
+
+// Results will include only time series entries within the specified range for employees from UK.
+{CODE-TAB-BLOCK/}
+    {CODE-TABS/}
+
+* RQL queries can be run from the [query view](../../../studio/database/queries/query-view) in the Studio.  
+  Using the Studio, you can use parameters in the following way for a clearer query.  
+
+    {CODE-BLOCK:sql}
+$from = "2020-05-17T00:00:00.0000000Z"
+$to = "2020-05-17T01:00:00.0000000Z"
+
+from "Employees"
+where Address.Country == "UK"
+select timeseries(
+    from HeartRates
+    between $from and $to  // using parameters
+)
+    {CODE-BLOCK/}
+
+{NOTE/}
+
+{NOTE: }
+
+#### `first` and `last`
+
+---
+
+* Use `first` to specify the time frame from the start of the time series.  
+  Use `last` to specify the time frame from the end of the time series.  
+  Only one of them can be used in the same query function. E.g.:  
+
+    {CODE-BLOCK: sql}
+// Retrieve all entries from the last day, starting from the end of time series "HeartRates"
+from "Employees"
+select timeseries(
+    from HeartRates
+    last 1 day
+)
+    {CODE-BLOCK/}
+
+    {CODE-BLOCK: sql}
+// Retrieve the first 10 minutes of entries from the beginning of time series "HeartRates"
+from "Employees"
+select timeseries(
+    from HeartRates
+    first 10 min
+)
+    {CODE-BLOCK/}
+
+* The range is specified using a whole number of one of the following units.  
+
+    * **seconds**  ( seconds/ second / s )
+    * **minutes**  ( minutes / minute / min )
+    * **hours**    ( hours / hour / h )
+    * **days**     ( days / day / d )
+    * **months**   ( months / month / mon / mo )
+    * **quarters** ( quarters / quarter / q )
+    * **years**    ( years / year / y )
+    * Note: **milliseconds** are currently not supported by 'first' and 'last' in a time series query.
+
+{NOTE/}
+{PANEL/}
+
+## Related articles
+
+**Time Series Overview**  
+[Time Series Overview](../../../document-extensions/timeseries/overview)  
+
+**Studio Articles**  
+[Studio Time Series Management](../../../studio/database/document-extensions/time-series)  
+
+**Time Series Indexing**  
+[Time Series Indexing](../../../document-extensions/timeseries/indexing)  
+
+**Time Series Queries**  
+[Filtering](../../../document-extensions/timeseries/querying/filtering)  
+[Aggregation and Projection](../../../document-extensions/timeseries/querying/aggregation-and-projections)  
+[Indexed Time Series Queries](../../../document-extensions/timeseries/querying/using-indexes)  
+
+**Policies**  
+[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention)