Skip to content

Commit

Permalink
Merge pull request #1854 from Danielle9897/RDoc-2874-TS-query-range
Browse files Browse the repository at this point in the history
RDoc-2874 [Node.js] Document extensions > Time series > Querying > Choose query range [Replace C# samples]
  • Loading branch information
ppekrol authored Jun 25, 2024
2 parents ebda707 + f0812bf commit 78705d4
Show file tree
Hide file tree
Showing 7 changed files with 838 additions and 24 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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/}

Expand Down Expand Up @@ -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/}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
@@ -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`&nbsp;and&nbsp;`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`&nbsp;and&nbsp;`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)
Loading

0 comments on commit 78705d4

Please sign in to comment.