From 00a6e38db568fa33bf6e9157b44599a0c551b00d Mon Sep 17 00:00:00 2001 From: reebhub Date: Mon, 22 Jul 2024 08:40:11 +0300 Subject: [PATCH 1/4] added python markdown and sample files --- .../append-in-bulk.dotnet.markdown | 24 +- .../bulk-insert/append-in-bulk.js.markdown | 24 +- .../javascript-support.dotnet.markdown | 20 +- .../client-api/javascript-support.js.markdown | 20 +- .../named-time-series-values.dotnet.markdown | 27 +- .../named-time-series-values.js.markdown | 27 +- .../append-and-delete.dotnet.markdown | 18 +- .../operations/append-and-delete.js.markdown | 17 +- .../operations/patch.dotnet.markdown | 60 +- .../client-api/operations/patch.js.markdown | 64 +- .../client-api/session/append.dotnet.markdown | 60 +- .../client-api/session/append.js.markdown | 56 +- .../client-api/session/append.python.markdown | 109 ++ .../client-api/session/delete.dotnet.markdown | 42 +- .../client-api/session/delete.js.markdown | 52 +- .../client-api/session/delete.python.markdown | 80 + .../session/get/get-entries.dotnet.markdown | 17 +- .../session/get/get-entries.js.markdown | 28 +- .../session/get/get-entries.python.markdown | 130 ++ .../session/get/get-names.python.markdown | 51 + .../client-api/session/patch.dotnet.markdown | 14 +- .../client-api/session/patch.js.markdown | 14 +- .../client-api/session/patch.python.markdown | 92 ++ .../session/querying.dotnet.markdown | 115 +- .../client-api/session/querying.js.markdown | 72 +- .../timeseries/indexing.dotnet.markdown | 50 +- .../timeseries/indexing.js.markdown | 50 +- ...ggregation-and-projections.dotnet.markdown | 51 +- .../aggregation-and-projections.js.markdown | 42 +- .../choosing-query-range.dotnet.markdown | 72 +- .../querying/choosing-query-range.js.markdown | 76 +- .../choosing-query-range.python.markdown | 173 ++ .../overview-and-syntax.dotnet.markdown | 4 +- .../querying/overview-and-syntax.js.markdown | 4 +- .../overview-and-syntax.python.markdown | 281 ++++ .../querying/using-indexes.dotnet.markdown | 29 +- .../querying/using-indexes.js.markdown | 29 +- .../rollup-and-retention.dotnet.markdown | 16 +- .../rollup-and-retention.js.markdown | 16 +- .../rollup-and-retention.python.markdown | 135 ++ .../TimeSeries/RollupAndRetention.py | 63 + .../TimeSeries/TimeSeriesTests.py | 1414 +++++++++++++++++ 42 files changed, 2905 insertions(+), 833 deletions(-) create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown create mode 100644 Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/RollupAndRetention.py create mode 100644 Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/TimeSeriesTests.py diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown index 55be08b74c..0b49b7e0e6 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown @@ -46,42 +46,32 @@ {PANEL: Examples} -{NOTE: } - __Append single entry__: +#### Append single entry: ---- In this example, we append a single entry with a single value to time series "HeartRates". {CODE timeseries_region_Use-BulkInsert-To-Append-single-entry@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +--- -{NOTE: } - __Append multiple entries__: +#### Append multiple entries: ---- In this example, we append 100 entries with a single value to time series "HeartRates". {CODE timeseries_region_Use-BulkInsert-To-Append-100-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +--- -{NOTE: } - __Append multiple values per entry__: +#### Append multiple values per entry: ---- In this example, we append multiple values per entry in time series "HeartRates". {CODE BulkInsert-overload-2-Two-HeartRate-Sets@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +--- -{NOTE: } - __Append multiple time series__: +#### Append multiple time series: ---- In this example, we append multiple time series in different documents in the same batch. {CODE timeseries_region_Use-BulkInsert-To-Append-multiple-timeseries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown index 76de3d8c13..428463b938 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown @@ -46,42 +46,32 @@ {PANEL: Examples} -{NOTE: } - __Append single entry__: +#### Append single entry: ---- In this example, we append a single entry with a single value to time series "HeartRates". {CODE:nodejs append_1@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /} -{NOTE/} +--- -{NOTE: } - __Append multiple entries__: +#### Append multiple entries: ---- In this example, we append 100 entries with a single value to time series "HeartRates". {CODE:nodejs append_2@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /} -{NOTE/} +--- -{NOTE: } - __Append multiple values per entry__: +#### Append multiple values per entry: ---- In this example, we append multiple values per entry in time series "HeartRates". {CODE:nodejs append_3@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /} -{NOTE/} +--- -{NOTE: } - __Append multiple time series__: +#### Append multiple time series: ---- In this example, we append multiple time series in different documents in the same batch. {CODE:nodejs append_4@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /} -{NOTE/} - {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.dotnet.markdown index a971fbd781..dd97c775f4 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.dotnet.markdown @@ -97,22 +97,14 @@ Values are returned in an array of time series entries, i.e. - {PANEL: Examples} -{NOTE: } - -This example shows a script that appends 100 entries to time series "HeartRates" in document "Users/john". -The script is passed to method [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch). +* This example shows a script that appends 100 entries to time series "HeartRates" in document "Users/john". + The script is passed to method [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch). + {CODE TS_region-Session_Patch-Append-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{CODE TS_region-Session_Patch-Append-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +* This example shows a script that deletes time series "HeartRates" for documents that match the specified query. + The script is passed to the [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) operation. + {CODE TS_region-PatchByQueryOperation-Delete-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} -{NOTE: } - -This example shows a script that deletes time series "HeartRates" for documents that match the specified query. -The script is passed to the [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) operation. - -{CODE TS_region-PatchByQueryOperation-Delete-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.js.markdown index 5e29b9f67f..0de5b6a1f8 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.js.markdown @@ -97,22 +97,14 @@ Values are returned in an array of time series entries, i.e. - {PANEL: Examples} -{NOTE: } - -This example shows a script that appends 100 entries to time series "HeartRates" in document "Users/john". -The script is passed to method [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch). +* This example shows a script that appends 100 entries to time series "HeartRates" in document "Users/john". + The script is passed to method [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch). + {CODE:nodejs js_support_1@documentExtensions\timeSeries\client-api\javascriptSupport.js /} -{CODE:nodejs js_support_1@documentExtensions\timeSeries\client-api\javascriptSupport.js /} +* This example shows a script that deletes time series "HeartRates" for documents that match the specified query. + The script is passed to the [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) operation. + {CODE:nodejs js_support_2@documentExtensions\timeSeries\client-api\javascriptSupport.js /} -{NOTE/} -{NOTE: } - -This example shows a script that deletes time series "HeartRates" for documents that match the specified query. -The script is passed to the [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) operation. - -{CODE:nodejs js_support_2@documentExtensions\timeSeries\client-api\javascriptSupport.js /} - -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.dotnet.markdown index 01eb663767..3f76be02fc 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.dotnet.markdown @@ -61,27 +61,15 @@ public void Deconstruct(out DateTime timestamp, out T value, out string tag); #### Examples -{NOTE: } - -In this example, we define a StockPrice type and use it when appending StockPrice entries. - -{CODE Custom-Data-Type-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{CODE timeseries_region_Append-Named-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} -{NOTE: } +* In this example, we define a StockPrice type and use it when appending StockPrice entries. + {CODE Custom-Data-Type-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE timeseries_region_Append-Named-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + {CODE timeseries_region_Get-Named-Values@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{CODE timeseries_region_Get-Named-Values@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} -{NOTE: } - -In this query, we use the custom StockPrice type so we can address trade Volume by name. - -{CODE-TABS} +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + {CODE-TABS} {CODE-TAB:csharp:Query timeseries_region_Named-Values-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB-BLOCK:sql:RQL} from "companies" as c @@ -99,7 +87,6 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Register time series type} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.js.markdown index d79833d890..e044d954db 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/named-time-series-values.js.markdown @@ -50,27 +50,15 @@ The class can then be used by time series methods like _append_: #### Examples -{NOTE: } - -In this example, we define a StockPrice class and use it when appending StockPrice entries. - -{CODE:nodejs stockPrice_class@documentExtensions\timeSeries\client-api\namedValues.js /} - -{CODE:nodejs named_values_2@documentExtensions\timeSeries\client-api\namedValues.js /} - -{NOTE/} -{NOTE: } +* In this example, we define a StockPrice class and use it when appending StockPrice entries. + {CODE:nodejs stockPrice_class@documentExtensions\timeSeries\client-api\namedValues.js /} + {CODE:nodejs named_values_2@documentExtensions\timeSeries\client-api\namedValues.js /} -In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. +* In this example, we get StockPrice values by name and check whether a stock's closing-time prices are ascending over time. + {CODE:nodejs named_values_3@documentExtensions\timeSeries\client-api\namedValues.js /} -{CODE:nodejs named_values_3@documentExtensions\timeSeries\client-api\namedValues.js /} - -{NOTE/} -{NOTE: } - -In this query, we use the custom StockPrice type so we can address trade Volume by name. - -{CODE-TABS} +* In this query, we use the custom StockPrice type so we can address trade Volume by name. + {CODE-TABS} {CODE-TAB:nodejs:Query named_values_4@documentExtensions\timeSeries\client-api\namedValues.js /} {CODE-TAB-BLOCK:sql:RQL} from "companies" @@ -87,7 +75,6 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Register time series named values} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown index 4f04e4f97b..a263507b5c 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown @@ -48,29 +48,23 @@ {PANEL: Examples} -{NOTE: } - -#### Append multiple entries +#### Append multiple entries: In this example, we append four entries to a time series. {CODE timeseries_region_Append-Using-TimeSeriesBatchOperation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - -{NOTE: } +--- -#### Delete multiple entries +#### Delete multiple entries: In this example, we delete a range of two entries from a time series. {CODE timeseries_region_Delete-Range-Using-TimeSeriesBatchOperation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - -{NOTE: } +--- -#### Append & Delete entries in the same batch +#### Append & Delete entries in the same batch: * In this example, we append and delete entries in the same batch operation. @@ -78,8 +72,6 @@ In this example, we delete a range of two entries from a time series. {CODE timeseries_region-Append-and-Delete-TimeSeriesBatchOperation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.js.markdown index 4a3b1f5fdf..fde4bec687 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-delete.js.markdown @@ -48,29 +48,23 @@ {PANEL: Examples} -{NOTE: } - -#### Append multiple entries +#### Append multiple entries: In this example, we append four entries to a time series. {CODE:nodejs operation_1@documentExtensions\timeSeries\client-api\appendAndDeleteOperations.js /} -{NOTE/} - -{NOTE: } +--- -#### Delete multiple entries +#### Delete multiple entries: In this example, we delete a range of two entries from a time series. {CODE:nodejs operation_2@documentExtensions\timeSeries\client-api\appendAndDeleteOperations.js /} -{NOTE/} - -{NOTE: } +--- -#### Append & delete entries in the same batch +#### Append & delete entries in the same batch: * In this example, we append and delete entries in the same batch operation. @@ -78,7 +72,6 @@ In this example, we delete a range of two entries from a time series. {CODE:nodejs operation_3@documentExtensions\timeSeries\client-api\appendAndDeleteOperations.js /} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.dotnet.markdown index b1c196fe3c..b3aefd3cb7 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.dotnet.markdown @@ -50,30 +50,15 @@ ### Examples -{NOTE: } - -In this example, we **append** a single entry to time series "HeartRates" on the specified document. - -{CODE TS_region-Operation_Patch-Append-Single-TS-Entry@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} +* In this example, we **append** a single entry to time series "HeartRates" on the specified document. + {CODE TS_region-Operation_Patch-Append-Single-TS-Entry@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE: } - -In this example, we **append** 100 entries to time series "HeartRates" on the specified document. -Timestamps and values are drawn from an array and other arguments are provided in the "Values" property. - -{CODE TS_region-Operation_Patch-Append-100-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +* In this example, we **append** 100 entries to time series "HeartRates" on the specified document. + Timestamps and values are drawn from an array and other arguments are provided in the "Values" property. + {CODE TS_region-Operation_Patch-Append-100-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - -{NOTE: } - -In this example, we **delete** a range of 50 entries from time series "HeartRates" on the specified document. - -{CODE TS_region-Operation_Patch-Delete-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} +* In this example, we **delete** a range of 50 entries from time series "HeartRates" on the specified document. + {CODE TS_region-Operation_Patch-Delete-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} --- @@ -116,35 +101,18 @@ In this example, we **delete** a range of 50 entries from time series "HeartRate ### Examples -{NOTE: } - -In this example, we **append** an entry to time series "HeartRates" on ALL documents in the "Users" collection. +* In this example, we **append** an entry to time series "HeartRates" on ALL documents in the "Users" collection. + {CODE TS_region-PatchByQueryOperation-Append-To-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{CODE TS_region-PatchByQueryOperation-Append-To-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} - -{NOTE: } - -In this example, we **delete** the "HeartRates" time series from documents that match the query criteria. - -{CODE TS_region-PatchByQueryOperation-Delete-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} - -{NOTE: } +* In this example, we **delete** the "HeartRates" time series from documents that match the query criteria. + {CODE TS_region-PatchByQueryOperation-Delete-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} * In this example, for each document in the "Users" collection, we patch a document field with data retrieved from its time series entries. The document's time series data itself is Not patched. - -* The document field "NumberOfUniqueTagsInTS" will be updated with the number of unique tags in the user's "HeartRates" time series. - -* To do this, we use the JavaScript [get](../../../../document-extensions/timeseries/client-api/javascript-support#section-3) method to get all the time series entries for each document + The document `NumberOfUniqueTagsInTS` field will be updated with the number of unique tags in the user's "HeartRates" time series. + To do this, we use the JavaScript [get](../../../../document-extensions/timeseries/client-api/javascript-support#section-3) method to get all the time series entries for each document and extract each entry's tag. - -{CODE TS_region-PatchByQueryOperation-Get@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} + {CODE TS_region-PatchByQueryOperation-Get@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} --- diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.js.markdown index 4d4f2ff5c3..30099f9f27 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.js.markdown @@ -50,30 +50,15 @@ ### Examples -{NOTE: } - -In this example, we **append** a single entry to time series "HeartRates" on the specified document. - -{CODE:nodejs patch_1@documentExtensions\timeSeries\client-api\patchOperations.js /} - -{NOTE/} +* In this example, we **append** a single entry to time series "HeartRates" on the specified document. + {CODE:nodejs patch_1@documentExtensions\timeSeries\client-api\patchOperations.js /} -{NOTE: } - -In this example, we **append** 100 entries to time series "HeartRates" on the specified document. -Timestamps and values are drawn from an array and other arguments are provided in the "values" property. - -{CODE:nodejs patch_2@documentExtensions\timeSeries\client-api\patchOperations.js /} +* In this example, we **append** 100 entries to time series "HeartRates" on the specified document. + Timestamps and values are drawn from an array and other arguments are provided in the "values" property. + {CODE:nodejs patch_2@documentExtensions\timeSeries\client-api\patchOperations.js /} -{NOTE/} - -{NOTE: } - -In this example, we **delete** a range of 50 entries from time series "HeartRates" on the specified document. - -{CODE:nodejs patch_3@documentExtensions\timeSeries\client-api\patchOperations.js /} - -{NOTE/} +* In this example, we **delete** a range of 50 entries from time series "HeartRates" on the specified document. + {CODE:nodejs patch_3@documentExtensions\timeSeries\client-api\patchOperations.js /} --- @@ -116,35 +101,18 @@ In this example, we **delete** a range of 50 entries from time series "HeartRate ### Examples -{NOTE: } - -In this example, we **append** an entry to time series "HeartRates" on ALL documents in the "Users" collection. +* In this example, we **append** an entry to time series "HeartRates" on ALL documents in the "Users" collection. + {CODE:nodejs patch_4@documentExtensions\timeSeries\client-api\patchOperations.js /} -{CODE:nodejs patch_4@documentExtensions\timeSeries\client-api\patchOperations.js /} +* In this example, we **delete** the "HeartRates" time series from documents that match the query criteria. + {CODE:nodejs patch_5@documentExtensions\timeSeries\client-api\patchOperations.js /} -{NOTE/} - -{NOTE: } - -In this example, we **delete** the "HeartRates" time series from documents that match the query criteria. - -{CODE:nodejs patch_5@documentExtensions\timeSeries\client-api\patchOperations.js /} - -{NOTE/} - -{NOTE: } - -* In this example, for each document in the "Users" collection, we patch a document field with data retrieved from its time series entries. - The document's time series data itself is Not patched. - -* The document field "numberOfUniqueTagsInTS" will be updated with the number of unique tags in the user's "HeartRates" time series. - -* To do this, we use the JavaScript [get](../../../../document-extensions/timeseries/client-api/javascript-support#section-3) method to get all the time series entries for each document +* In this example, for each document in the "Users" collection, we patch a document field with data retrieved from its time series entries. + The document's time series data itself is Not patched. + The document `numberOfUniqueTagsInTS` field will be updated with the number of unique tags in the user's "HeartRates" time series. + To do this, we use the JavaScript [get](../../../../document-extensions/timeseries/client-api/javascript-support#section-3) method to get all the time series entries for each document and extract each entry's tag. - -{CODE:nodejs patch_6@documentExtensions\timeSeries\client-api\patchOperations.js /} - -{NOTE/} + {CODE:nodejs patch_6@documentExtensions\timeSeries\client-api\patchOperations.js /} --- diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.dotnet.markdown index 9907747592..4e24974ae7 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.dotnet.markdown @@ -5,31 +5,29 @@ {NOTE: } * Use `TimeSeriesFor.Append` for the following actions: - - * __Create a new time series__: + * **Creating a new time series** Appending an entry to a time series that doesn't exist yet will create the time series and add it the new entry. - - * __Create a new time series entry__: + * **Creating a new time series entry** Appending a new entry to an existing time series will add the entry to the series at the specified timestamp. + * **Modifying an existing time series entry** + Use `Append` to update the data of an existing entry with the specified timestamp. - * __Modify an existing time series entry__: - Use _Append_ to update the data of an existing entry with the specified timestamp. +* Each call to `Append` handles a **single** [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). -* Each call to `Append` handles a __single__ [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). - -* To append __multiple__ entries in a single transaction you can: +* To append **multiple** entries in a single transaction you can: * Call `Append` as many times as needed before calling `session.SaveChanges`, as shown in the examples below. * Use patching to update the time series. Learn more in [Patch time series entries](../../../../document-extensions/timeseries/client-api/session/patch). - * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). + * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). + Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). --- * In this page: * [`Append` usage](../../../../document-extensions/timeseries/client-api/session/append#append-usage) * [Examples](../../../../document-extensions/timeseries/client-api/session/append#examples) - * [Append entries with single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-single-value) + * [Append entries with a single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-a-single-value) * [Append entries with multiple values](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values) * [Syntax](../../../../document-extensions/timeseries/client-api/session/append#syntax) @@ -39,7 +37,7 @@ {PANEL: `Append` usage} -__Flow__: +**Flow**: * Open a session. * Create an instance of `TimeSeriesFor` and pass it the following: @@ -50,7 +48,7 @@ __Flow__: * Call `TimeSeriesFor.Append` and pass it the time series entry details. * Call `session.SaveChanges` for the action to take effect on the server. -__Note__: +**Note**: * A `DocumentDoesNotExistException` exception is thrown if the specified document does not exist. @@ -58,37 +56,25 @@ __Note__: {PANEL: Examples} -{NOTE: } - - __Append entries with single value__: - ---- +#### Append entries with a single value: * In this example, entries are appended with a single value. - * Although a loop is used to append multiple entries, all entries are appended in a single transaction when `SaveChanges` is executed. {CODE timeseries_region_TimeSeriesFor-Append-TimeSeries-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - -{NOTE: } - - __Append entries with multiple values__: - --- -* In this example, we append multi-value StockPrice entries. - -* Notice the clarity gained by [naming the values](../../../../document-extensions/timeseries/client-api/named-time-series-values). +#### Append entries with multiple values: - {CODE-TABS} - {CODE-TAB:csharp:Native timeseries_region_Append-Unnamed-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - {CODE-TAB:csharp:Using_named_values timeseries_region_Append-Named-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - {CODE-TABS/} +* In this example, we append multi-value StockPrice entries. +* Notice the clarity gained by [naming the values](../../../../document-extensions/timeseries/client-api/named-time-series-values). -{NOTE/} +{CODE-TABS} +{CODE-TAB:csharp:Native timeseries_region_Append-Unnamed-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +{CODE-TAB:csharp:Using_named_values timeseries_region_Append-Named-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +{CODE-TABS/} {PANEL/} @@ -100,10 +86,10 @@ __Note__: | Parameter | Type | Description | |---------------|-----------------------|-------------------------------| -| __timestamp__ | `DateTime` | Time series entry's timestamp | -| __value__ | `double` | Entry's value | -| __values__ | `IEnumerable` | Entry's values | -| __tag__ | `string` | An optional tag for the entry | +| **timestamp** | `DateTime` | Time series entry's timestamp | +| **value** | `double` | Entry's value | +| **values** | `IEnumerable` | Entry's values | +| **tag** | `string` | An optional tag for the entry | {PANEL/} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.js.markdown index d51d799498..bc65f542a8 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.js.markdown @@ -5,31 +5,29 @@ {NOTE: } * Use `timeSeriesFor.append` for the following actions: - - * __Create a new time series__: + * **Creating a new time series** Appending an entry to a time series that doesn't exist yet will create the time series and add the new entry to it. - - * __Create a new time series entry__: + * **Creating a new time series entry** Appending a new entry to an existing time series will add the entry to the series at the specified timestamp. + * **Modifying an existing time series entry** + Use `append` to update the data of an existing entry with the specified timestamp. - * __Modify an existing time series entry__: - Use _append_ to update the data of an existing entry with the specified timestamp. - -* Each call to `append` handles a __single__ [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). +* Each call to `append` handles a **single** [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). -* To append __multiple__ entries in a single transaction you can: +* To append **multiple** entries in a single transaction you can: * Call `append` as many times as needed before calling `session.saveChanges`, as shown in the examples below. - * Use patching to update the time series. Learn more in [Patch time series entries](../../../../document-extensions/timeseries/client-api/session/patch). - * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). + * Use patching to update the time series. Learn more in [Patch time series entries](../../../../document-extensions/timeseries/client-api/session/patch). + * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). + Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). --- * In this page: * [`append` usage](../../../../document-extensions/timeseries/client-api/session/append#append-usage) * [Examples](../../../../document-extensions/timeseries/client-api/session/append#examples) - * [Append entries with single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-single-value) + * [Append entries with a single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-a-single-value) * [Append entries with multiple values](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values) * [Syntax](../../../../document-extensions/timeseries/client-api/session/append#syntax) @@ -39,7 +37,7 @@ {PANEL: `append` usage} -__Flow__: +**Flow**: * Open a session. * Create an instance of `timeSeriesFor` and pass it the following: @@ -50,7 +48,7 @@ __Flow__: * Call `timeSeriesFor.append` and pass it the time series entry details. * Call `session.saveChanges` for the action to take effect on the server. -__Note__: +**Note**: * A `DocumentDoesNotExistException` exception is thrown if the specified document does not exist. @@ -58,30 +56,20 @@ __Note__: {PANEL: Examples} -{NOTE: } - - __Append entries with single value__: - ---- +#### Append entries with a single value: * In this example, entries are appended with a single value. - * Although a loop is used to append multiple entries, all entries are appended in a single transaction when `saveChanges` is executed. {CODE:nodejs append_1@documentExtensions\timeSeries\client-api\appendTimeSeries.js /} -{NOTE/} - -{NOTE: } - - __Append entries with multiple values__: - --- -* In this example, we append multi-value StockPrice entries. +#### Append entries with multiple values: -* Notice the clarity gained by [naming the values](../../../../document-extensions/timeseries/client-api/named-time-series-values). +* In this example, we append multi-value StockPrice entries. +* Notice the clarity gained by [naming the values](../../../../document-extensions/timeseries/client-api/named-time-series-values). {CODE-TABS} {CODE-TAB:nodejs:Native append_2@documentExtensions\timeSeries\client-api\appendTimeSeries.js /} @@ -89,8 +77,6 @@ __Note__: {CODE-TAB:nodejs:StockPrice_class stockPrice_class@documentExtensions\timeSeries\client-api\appendTimeSeries.js /} {CODE-TABS/} -{NOTE/} - {PANEL/} {PANEL: Syntax} @@ -103,11 +89,11 @@ __Note__: | Parameter | Type | Description | |---------------|----------|--------------------------------| -| __timestamp__ | Date | Time series entry's timestamp | -| __value__ | number | Entry's value | -| __values__ | number[] | Entry's values | -| __tag__ | string | An optional tag for the entry | -| __entry__ | object | object with the entry's values | +| **timestamp** | Date | Time series entry's timestamp | +| **value** | number | Entry's value | +| **values** | number[] | Entry's values | +| **tag** | string | An optional tag for the entry | +| **entry** | object | object with the entry's values | {PANEL/} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown new file mode 100644 index 0000000000..315af9afd1 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown @@ -0,0 +1,109 @@ +# Append & Update Time Series + +--- + +{NOTE: } + +* Use `time_series_for.append` for the following actions: + * **Creating a new time series** + Appending an entry to a time series that doesn't exist yet + will create the time series and add it the new entry. + * **Creating a new time series entry** + Appending a new entry to an existing time series + will add the entry to the series at the specified timestamp. + * **Modifying an existing time series entry** + Use `append` to update the data of an existing entry with the specified timestamp. + +* Each call to `append` handles a **single** + [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). + +* To append **multiple** entries in a single transaction you can: + * Call `append` as many times as needed before calling `session.save_changes`, as shown in the examples below. + * Use patching to update the time series. Learn more in [Patch time series entries](../../../../document-extensions/timeseries/client-api/session/patch). + * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). + Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). + +* In this page: + * [`append` usage](../../../../document-extensions/timeseries/client-api/session/append#append-usage) + * [Examples](../../../../document-extensions/timeseries/client-api/session/append#examples) + * [Append entries with a single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-a-single-value) + * [Append entries with multiple values](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/append#syntax) + +{NOTE/} + +--- + +{PANEL: `append` usage} + +**Flow**: + +* Open a session. +* Create an instance of `time_series_for` and pass it the following: + * Provide an explicit document ID, -or- + pass an [entity tracked by the session](../../../../client-api/session/what-is-a-session-and-how-does-it-work#unit-of-work-pattern), + e.g. a document object returned from [session.query](../../../../client-api/session/querying/how-to-query) + or from [session.load](../../../../client-api/session/loading-entities#load). + * Specify the time series name. +* Call `time_series_for.append` and pass it the time series entry details. +* Call `session.save_changes` for the action to take effect on the server. + +**Note**: + +* A `DocumentDoesNotExistException` exception is thrown if the specified document does not exist. + +{PANEL/} + +{PANEL: Examples} + +#### Append entries with a single value: + +* In this example, entries are appended with a single value. +* Although a loop is used to append multiple entries, + all entries are appended in a single transaction when `save_changes` is executed. + +{CODE:python timeseries_region_TimeSeriesFor-Append-TimeSeries-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +--- + +#### Append entries with multiple values: + +* In this example, we append multi-value StockPrice entries. +* Notice the clarity gained by naming the values. + +{CODE-TABS} +{CODE-TAB:python:Native timeseries_region_Append-Unnamed-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} +{CODE-TAB:python:Using_named_values timeseries_region_Append-Named-Values-2@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:python TimeSeriesFor-Append-definition-double@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{CODE:python TimeSeriesFor-Append-definition-inum@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +| Parameter | Type | Description | +|-----------|------|-------------| +| **timestamp** | `datetime` | Time series entry's timestamp | +| **value** | `float` | Entry's value | +| **values** | `List[float]` | Entry's values | +| **tag** (Optional) | `str` | An optional tag for the entry | + +{PANEL/} + +## Related articles + +**Client API** +[Time Series API Overview](../../../../document-extensions/timeseries/client-api/overview) + +**Studio Articles** +[Studio Time Series Management](../../../../studio/database/document-extensions/time-series) + +**Querying and Indexing** +[Time Series Querying](../../../../document-extensions/timeseries/querying/overview-and-syntax) +[Time Series Indexing](../../../../document-extensions/timeseries/indexing) + +**Policies** +[Time Series Rollup and Retention](../../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.dotnet.markdown index 86aa472d14..20b0fb2b31 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.dotnet.markdown @@ -5,12 +5,9 @@ {NOTE: } * Use `TimeSeriesFor.Delete` for the following actions: - - * __Delete a single time series entry__ - - * __Delete a range of entries__ - - * __Delete the whole time series__: + * **Delete a single time series entry** + * **Delete a range of entries** + * **Delete the whole time series**: To remove the whole time series simply delete all its entries. * In this page: @@ -26,7 +23,7 @@ {PANEL: `Delete` usage} -__Flow__: +**Flow**: * Open a session. * Create an instance of `TimeSeriesFor` and pass it the following: @@ -39,7 +36,7 @@ __Flow__: * Specify a range of timestamps to delete multiple entries. * Call `session.SaveChanges` for the action to take effect on the server. -__Note__: +**Note**: * If the specified document doesn't exist, a `DocumentDoesNotExistException` is thrown. * Attempting to delete nonexistent entries results in a no-op and generates no exception. @@ -51,28 +48,21 @@ __Note__: {PANEL: Examples} -The following examples delete the time series entries that were appended in the [Append](../../../../document-extensions/timeseries/client-api/session/append) article: - -{NOTE: } - - __Delete single entry__: +In the following examples we delete time series entries appended by sample code in the +[Append](../../../../document-extensions/timeseries/client-api/session/append) article. --- -{CODE timeseries_region_Delete-TimeSeriesFor-Single-Time-Point@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +#### Delete single entry: -{NOTE/} +{CODE timeseries_region_Delete-TimeSeriesFor-Single-Time-Point@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE: } +--- - __Delete range of entries__: +#### Delete range of entries: ---- - {CODE timeseries_region_TimeSeriesFor-Delete-Time-Points-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - {PANEL/} {PANEL: Syntax} @@ -81,11 +71,11 @@ The following examples delete the time series entries that were appended in the {CODE TimeSeriesFor-Delete-definition-range-of-timepoints@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -| Parameter | Type | Description | -|-----------|-------------|:------------------------------------------------------------------------------------------------------------------| -| __at__ | `DateTime` | Timestamp of the time series entry to delete. | -| __from__ | `DateTime?` | Delete the range of time series entries starting from this timestamp (inclusive).
Default: `DateTime.MinValue` | -| __to__ | `DateTime?` | Delete the range of time series entries ending at this timestamp (inclusive).
Default: `DateTime.MaxValue` | +| Parameter | Type | Description | +|-----------|-------------|:--------------------------------------------| +| **at** | `DateTime` | Timestamp of a time series entry to delete. | +| **from** | `DateTime?` | Delete the time series entries range that starts at this timestamp (inclusive).
Default: `DateTime.MinValue` | +| **to** | `DateTime?` | Delete the time series entries range that ends at this timestamp (inclusive).
Default: `DateTime.MaxValue` | {PANEL/} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.js.markdown index f9f32c7d59..f1017e086e 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.js.markdown @@ -5,19 +5,16 @@ {NOTE: } * Use `timeSeriesFor.delete` for the following actions: - - * __Delete a single time series entry__ - - * __Delete a range of entries__ - - * __Delete the whole time series__ + * **Delete a single time series entry** + * **Delete a range of entries** + * **Delete the whole time series** * In this page: * [`delete` usage](../../../../document-extensions/timeseries/client-api/session/delete#delete-usage) * [Examples](../../../../document-extensions/timeseries/client-api/session/delete#examples) * [Delete single entry](../../../../document-extensions/timeseries/client-api/session/delete#delete-single-entry) * [Delete range of entries](../../../../document-extensions/timeseries/client-api/session/delete#delete-range-of-entries) - * [Delete time series](../../../../document-extensions/timeseries/client-api/session/delete#delete-time-series) + * [Delete time series](../../../../document-extensions/timeseries/client-api/session/delete#delete-time-series-1) * [Syntax](../../../../document-extensions/timeseries/client-api/session/delete#syntax) {NOTE/} @@ -26,7 +23,7 @@ {PANEL: `Delete` usage} -__Flow__: +**Flow**: * Open a session. * Create an instance of `timeSeriesFor` and pass it the following: @@ -39,7 +36,7 @@ __Flow__: * Specify a range of timestamps to delete multiple entries. * Call `session.saveChanges` for the action to take effect on the server. -__Note__: +**Note**: * If the specified document doesn't exist, a `DocumentDoesNotExistException` is thrown. * Attempting to delete nonexistent entries results in a no-op and generates no exception. @@ -51,37 +48,26 @@ __Note__: {PANEL: Examples} -The following examples delete the time series entries that were appended in the [Append](../../../../document-extensions/timeseries/client-api/session/append) article: - -{NOTE: } - - __Delete single entry__: +In the following examples we delete time series entries appended by sample code in the +[Append](../../../../document-extensions/timeseries/client-api/session/append) article. --- -{CODE:nodejs delete_1@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} - -{NOTE/} - -{NOTE: } +#### Delete single entry: - __Delete range of entries__: +{CODE:nodejs delete_1@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} --- - -{CODE:nodejs delete_2@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} - -{NOTE/} -{NOTE: } +#### Delete range of entries: - __Delete time series__: +{CODE:nodejs delete_2@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} --- -{CODE:nodejs delete_3@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} +#### Delete time series: -{NOTE/} +{CODE:nodejs delete_3@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} {PANEL/} @@ -89,11 +75,11 @@ The following examples delete the time series entries that were appended in the {CODE:nodejs syntax@documentExtensions\timeSeries\client-api\deleteTimeSeries.js /} -| Parameter | Type | Description | -|-----------|--------|:--------------------------------------------------------------------------------------------------------------------------------| -| __at__ | `Date` | Timestamp of the time series entry to delete. | -| __from__ | `Date` | Delete the range of time series entries starting from this timestamp (inclusive).
Pass `null` to use the minimum date value. | -| __to__ | `Date` | Delete the range of time series entries ending at this timestamp (inclusive).
Pass `null` to use the maximum date value. | +| Parameter | Type | Description | +|-----------|--------|:----------------------------------------------| +| **at** | `Date` | Timestamp of the time series entry to delete. | +| **from** | `Date` | Delete the time series entries range that starts at this timestamp (inclusive).
Pass `null` to use the minimum date value. | +| **to** | `Date` | Delete the time series entries range that ends at this timestamp (inclusive).
Pass `null` to use the maximum date value. | {PANEL/} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.python.markdown new file mode 100644 index 0000000000..ab393d8794 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/delete.python.markdown @@ -0,0 +1,80 @@ +# Delete Time Series + +--- + +{NOTE: } + +* Use `time_series_for.delete_at` to delete a time series entry. +* Use `time_series_for.delete` to delete a range of time series entries. +* A time series is removed when all of its entries are deleted. + +* In this page: + * [usage](../../../../document-extensions/timeseries/client-api/session/delete#usage) + * [Example](../../../../document-extensions/timeseries/client-api/session/delete#example) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/delete#syntax) + +{NOTE/} + +--- + +{PANEL: usage} + +**Flow**: + +* Open a session. +* Create an instance of `time_series_for` and pass it the following: + * Provide an explicit document ID, or - + pass an [entity tracked by the session](../../../../client-api/session/what-is-a-session-and-how-does-it-work#unit-of-work-pattern), + e.g. a document object returned from [session.query](../../../../client-api/session/querying/how-to-query) + or from [session.load](../../../../client-api/session/loading-entities#load). + * Specify the time series name. +* Call `time_series_for.delete_at` and provide the **timestamp** of an entry you want to delete, + -or- + Call `time_series_for.delete` and provide the **timestamps range** of the entries you want to delete. +* Call `session.save_changes` for the action to take effect on the server. + +**Note**: + +* If the specified document doesn't exist, a `DocumentDoesNotExistException` will be thrown. +* Attempting to delete nonexistent entries results in a no-op and generates no exception. +* To delete a whole time series simply delete all its entries. + The series is removed when all its entries are deleted. +* Deleting a document deletes all its time series as well. + +{PANEL/} + +{PANEL: Example} + +In the following example we delete a time series entry appended by sample code in the +[Append](../../../../document-extensions/timeseries/client-api/session/append) article. +{CODE:python timeseries_region_Delete-TimeSeriesFor-Single-Time-Point@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:python TimeSeriesFor-Delete-definition-single-timepoint@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{CODE:python TimeSeriesFor-Delete-definition-range-of-timepoints@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +| Parameter | Type | Description | +|-----------|-------------|:-------------------------------------------| +| **at** | `datetime` | Timestamp of a time series entry to delete | +| **datetime_from** (Optional) | `datetime` | Delete the time series entries range that starts at this timestamp (inclusive) | +| **datetime_to** (Optional) | `datetime` | Delete the time series entries range that ends at this timestamp (inclusive) | +{PANEL/} + +## Related articles + +**Client API** +[Time Series API Overview](../../../../document-extensions/timeseries/client-api/overview) + +**Studio Articles** +[Studio Time Series Management](../../../../studio/database/document-extensions/time-series) + +**Querying and Indexing** +[Time Series Querying](../../../../document-extensions/timeseries/querying/overview-and-syntax) +[Time Series Indexing](../../../../document-extensions/timeseries/indexing) + +**Policies** +[Time Series Rollup and Retention](../../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.dotnet.markdown index 7eabcd7bfb..ed59f5b4c8 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.dotnet.markdown @@ -23,6 +23,9 @@ * In this page: * [`Get` usage](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-usage) * [Examples](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#examples) + * [Get all entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-all-entries) + * [Get range of entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-range-of-entries) + * [Get entries with multiple values](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-entries-with-multiple-values) * [Include parent and tagged documents](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#include-parent-and-tagged-documents) * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#syntax) @@ -44,22 +47,24 @@ {PANEL: Examples} -{NOTE: } +#### Get all entries: In this example, we retrieve all entries of the "Heartrate" time series. The ID of the parent document is explicitly specified. {CODE timeseries_region_Get-All-Entries-Using-Document-ID@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} -{NOTE: } +--- + +#### Get range of entries: In this example, we query for a document and get its "Heartrate" time series data. {CODE timeseries_region_Pass-TimeSeriesFor-Get-Query-Results@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} -{NOTE: } +--- + +#### Get entries with multiple values: * Here, we check whether a stock's closing-time price is rising from day to day (over three days). This example is based on the sample entries that were entered in [this example](../../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values). @@ -73,8 +78,6 @@ In this example, we query for a document and get its "Heartrate" time series dat {CODE-TAB:csharp:Named timeseries_region_Get-Named-Values@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TABS/} -{NOTE/} - {PANEL/} {PANEL: Include parent and tagged documents} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.js.markdown index 7ee4221e8f..a71b7a67f1 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.js.markdown @@ -23,9 +23,9 @@ * In this page: * [`get` usage](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-usage) * [Examples](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#examples) - * [Get all entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-all-entries) - * [Get range of entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-range-of-entries) - * [Get entries with multiple values](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-entries-with-multiple-values) + * [Get all entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-all-entries) + * [Get range of entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-range-of-entries) + * [Get entries with multiple values](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-entries-with-multiple-values) * [Include parent and tagged documents](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#include-parent-and-tagged-documents) * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#syntax) @@ -47,35 +47,25 @@ {PANEL: Examples} -{NOTE: } - - __Get all entries__: - ---- +#### Get all entries: In this example, we retrieve all entries of the "Heartrate" time series. The ID of the parent document is explicitly specified. {CODE:nodejs get_Entries_1@documentExtensions\timeSeries\client-api\getEntries.js /} -{NOTE/} -{NOTE: } - - __Get range of entries__: - --- +#### Get range of entries: + In this example, we query for a document and get a range of entries from its "Heartrate" time series. {CODE:nodejs get_Entries_2@documentExtensions\timeSeries\client-api\getEntries.js /} -{NOTE/} -{NOTE: } - - __Get entries with multiple values__: - --- +#### Get entries with multiple values: + * Here, we check if a stock's closing price is rising consecutively over three days. This example is based on the sample entries that were entered in [this example](../../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values). @@ -88,8 +78,6 @@ In this example, we query for a document and get a range of entries from its "He {CODE-TAB:nodejs:Named get_Entries_3_named@documentExtensions\timeSeries\client-api\getEntries.js /} {CODE-TABS/} -{NOTE/} - {PANEL/} {PANEL: Include parent and tagged documents} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.python.markdown new file mode 100644 index 0000000000..b541b2fa90 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.python.markdown @@ -0,0 +1,130 @@ +# Get Time Series Entries +--- + +{NOTE: } + +* Use `time_series_for.get` to retrieve a range of entries from a **single** time series. + To retrieve a range of entries from **multiple** series, + use the [GetMultipleTimeSeriesOperation](../../../../../document-extensions/timeseries/client-api/operations/get#getmultipletimeseriesoperation) operation. + +* The retrieved data can be paged to get the time series entries gradually, one custom-size page at a time. + +* By default, the session will track the retrieved time series data. + See [disable tracking](../../../../../client-api/session/configuration/how-to-disable-tracking) to learn how to disable. + +* When getting the time series entries, + you can also _include_ the series' **parent document** and/or **documents referred to by the entry tag**. + Learn more [below](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#include-parent-and-tagged-documents). + +* Calling `time_series_for.get` will result in a trip to the server unless the series' parent document was loaded + (or queried for) with the time series included beforehand. + Learn more in: [Including time series](../../../../../document-extensions/timeseries/client-api/session/include/overview). + +* In this page: + * [`Get` usage](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-usage) + * [Examples](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#examples) + * [Get all entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-all-entries) + * [Get range of entries](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-range-of-entries) + * [Get entries with multiple values](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#get-entries-with-multiple-values) + * [Include parent and tagged documents](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#include-parent-and-tagged-documents) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#syntax) + +{NOTE/} + +--- + +{PANEL: `Get` usage } + +* Open a session. +* Create an instance of `time_series_for` and pass it the following: + * Provide an explicit document ID, -or- + pass an [entity tracked by the session](../../../../../client-api/session/what-is-a-session-and-how-does-it-work#unit-of-work-pattern), + e.g. a document object returned from [session.query](../../../../../client-api/session/querying/how-to-query) + or from [session.load](../../../../../client-api/session/loading-entities#load). + * Specify the time series name. +* Call `time_series_for.get`. + +{PANEL/} + +{PANEL: Examples} + +#### Get all entries: + +In this example, we retrieve all entries of the "Heartrate" time series. +The ID of the parent document is explicitly specified. + +{CODE:python timeseries_region_Get-All-Entries-Using-Document-ID@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +--- + +#### Get range of entries: + +In this example, we query for a document and get its "Heartrate" time series data. + +{CODE:python timeseries_region_Pass-TimeSeriesFor-Get-Query-Results@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +--- + +#### Get entries with multiple values: + +* Here, we check whether a stock's closing-time price is rising from day to day (over three days). + This example is based on the sample entries that were entered in [this example](../../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values). + +* Since each time series entry contains multiple StockPrice values, + we include a sample that uses [named](../../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values) + time series values to make the code easier to read. + +{CODE:python timeseries_region_Get-Named-Values@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +{PANEL: Include parent and tagged documents} + +* When retrieving time series entries using `time_series_for.get`, + you can include the series parent document and/or documents referred to by the entries + [tags](../../../../../document-extensions/timeseries/overview#tags). + +* The included documents will be cached in the session, and instantly retrieved from memory if loaded by the user. + +* Use the following syntax to include the parent or tagged documents: + +{CODE:python IncludeParentAndTaggedDocuments@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +{PANEL: Syntax} + +{CODE:python TimeSeriesFor-Get-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{CODE:python TimeSeriesFor-Get-Named-Values@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +| Parameter | Type | Description | +|-----------|------|-------------| +| **from_date** (Optional) | `datetime` | Get the range of time series entries starting from this timestamp (inclusive).
Default: `datetime.min` | +| **to_date** (Optional) | `datetime` | Get the range of time series entries ending at this timestamp (inclusive).
Default: `datetime.max` | +| **start** | `int` | Paging first entry.
E.g. 50 means the first page would start at the 50th time series entry.
Default: `0`, for the first time-series entry. | +| **page_size** | `int` | Paging page-size.
E.g. set `page_size` to 10 to retrieve pages of 10 entries.
Default: `int_max`, for all time series entries. | + +**Return Values (Optional)** + +* `List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]]` - an array of time series entry classes. + {CODE:python TimeSeriesEntry-Definition@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +* `TimeSeriesEntry[]` - Time series values that can be referred to by name. + +{PANEL/} + +## Related articles + +**Client API** +[Time Series API Overview](../../../../../document-extensions/timeseries/client-api/overview) + +**Studio Articles** +[Studio Time Series Management](../../../../../studio/database/document-extensions/time-series) + +**Querying and Indexing** +[Time Series Querying](../../../../../document-extensions/timeseries/querying/overview-and-syntax) +[Time Series Indexing](../../../../../document-extensions/timeseries/indexing) + +**Policies** +[Time Series Rollup and Retention](../../../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown new file mode 100644 index 0000000000..8303e4690d --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown @@ -0,0 +1,51 @@ +# Get Time Series Names +--- + +{NOTE: } + +* Use `advanced.get_time_series_for` to get the names of all time series for the specified entity. + +* In this page: + * [`get_time_series_for` usage](../../../../../document-extensions/timeseries/client-api/session/get/get-names#get_time_series_for-usage) + * [Example](../../../../../document-extensions/timeseries/client-api/session/get/get-names#example) + +{NOTE/} + +--- + +{PANEL: `get_time_series_for` usage} + +**Flow**: + +* Open a session. +* Load an entity to the session either using [session.load](../../../../../client-api/session/loading-entities#load) + or by querying for the document via [session.query](../../../../../client-api/session/querying/how-to-query). + In both cases, the resulting entity will be tracked by the session. +* Call `advanced.get_time_series_for`, pass the tracked entity. + +**Note**: + +* If the entity is Not tracked by the session, an `ArgumentException` exception is thrown. + +{PANEL/} + +{PANEL: Example} + +{CODE:python timeseries_region_Retrieve-TimeSeries-Names@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +## Related articles + +**Client API** +[Time Series API Overview](../../../../../document-extensions/timeseries/client-api/overview) + +**Studio Articles** +[Studio Time Series Management](../../../../../studio/database/document-extensions/time-series) + +**Querying and Indexing** +[Time Series Querying](../../../../../document-extensions/timeseries/querying/overview-and-syntax) +[Time Series Indexing](../../../../../document-extensions/timeseries/indexing) + +**Policies** +[Time Series Rollup and Retention](../../../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.dotnet.markdown index fb09a1674d..25d65637fc 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.dotnet.markdown @@ -7,7 +7,7 @@ * Patching multiple time series entries (append or delete entries) can be performed via the _Session_ using [session.Advanced.Defer](../../../../client-api/operations/patching/single-document#session-api-using-defer), as described below. * You can handle a single document at a time. - * The patching action is defined by the provided [JavaScript script](../../../../document-extensions/timeseries/client-api/javascript-support). + * The patching action is defined by the provided [JavaScript](../../../../document-extensions/timeseries/client-api/javascript-support). * Patching time series entries can also be done directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations), where multiple documents can be handled at a time. Learn more in [Patching time series operations](../../../../document-extensions/timeseries/client-api/operations/patch). @@ -39,26 +39,20 @@ {PANEL: Patching examples} -{NOTE: } - - __Append multiple entries__: +#### Append multiple entries: In this example, we append 100 time series entries with random heart rate values to a document. {CODE TS_region-Session_Patch-Append-100-Random-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - -{NOTE: } +--- - __Delete multiple entries__: +#### Delete multiple entries: In this example, we remove a range of 50 time series entries from a document. {CODE TS_region-Session_Patch-Delete-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} - {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.js.markdown index 405208e237..d40d3ddffa 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.js.markdown @@ -7,7 +7,7 @@ * Patching multiple time series entries (append or delete entries) can be performed via the _Session_ using [session.advanced.defer](../../../../client-api/operations/patching/single-document#session-api-using-defer), as described below. * You can handle a single document at a time. - * The patching action is defined by the provided [JavaScript script](../../../../document-extensions/timeseries/client-api/javascript-support). + * The patching action is defined by the provided [JavaScript](../../../../document-extensions/timeseries/client-api/javascript-support). * Patching time series entries can also be done directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations), where multiple documents can be handled at a time. Learn more in [Patching time series operations](../../../../document-extensions/timeseries/client-api/operations/patch). @@ -39,26 +39,20 @@ {PANEL: Patching examples} -{NOTE: } - - __Append multiple entries__: +#### Append multiple entries: In this example, we append 100 time series entries with random heart rate values to a document. {CODE:nodejs patch_1@documentExtensions\timeSeries\client-api\patchTimeSeries.js /} -{NOTE/} - -{NOTE: } +--- - __Delete multiple entries__: +#### Delete multiple entries: In this example, we remove a range of 50 time series entries from a document. {CODE:nodejs patch_2@documentExtensions\timeSeries\client-api\patchTimeSeries.js /} -{NOTE/} - {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.python.markdown new file mode 100644 index 0000000000..a1cded9926 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.python.markdown @@ -0,0 +1,92 @@ +# Patch Time Series Entries + +--- + +{NOTE: } + +* Patching multiple time series entries (append or delete entries) can be performed via the _Session_ + using [session.advanced.defer](../../../../client-api/operations/patching/single-document#session-api-using-defer), as described below. + * You can handle a single document at a time. + * The patching action is defined by the provided [JavaScript](../../../../document-extensions/timeseries/client-api/javascript-support). + +* Patching time series entries can also be done directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations), + where multiple documents can be handled at a time. Learn more in [Patching time series operations](../../../../document-extensions/timeseries/client-api/operations/patch). + +* In this page: + * [Usage](../../../../document-extensions/timeseries/client-api/session/patch#usage) + * [Patching examples](../../../../document-extensions/timeseries/client-api/session/patch#patching-examples) + * [Append multiple entries](../../../../document-extensions/timeseries/client-api/session/patch#append-multiple-entries) + * [Delete multiple entries](../../../../document-extensions/timeseries/client-api/session/patch#delete-multiple-entries) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/patch#syntax) + +{NOTE/} + +--- + +{PANEL: Usage} + +* Open a session +* Construct a `PatchCommandData` instance and pass it the following: + * The document ID that contains the time series + * The document change vector (or `None`) + * A `PatchRequest` instance with a JavaScript that appends or removes time series entries +* Call `session.advanced.defer` and pass it the `PatchCommandData` command. + Note that you can call _Defer_ multiple times prior to calling _SaveChanges_. +* Call `session.save_changes`. + All patch requests added via _Defer_ will be sent to the server for execution when _SaveChanges_ is called. + +{PANEL/} + +{PANEL: Patching examples} + +#### Append multiple entries: + +In this example, we append 100 time series entries with random heart rate values to a document. + +{CODE:python TS_region-Session_Patch-Append-100-Random-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +--- + +#### Delete multiple entries: + +In this example, we remove a range of 50 time series entries from a document. + +{CODE:python TS_region-Session_Patch-Delete-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +{PANEL: Syntax} + +**`PatchCommandData`** + +{CODE:python PatchCommandData-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +Learn more about `PatchCommandData` [here](../../../../client-api/operations/patching/single-document#session-api-using-defer). + +--- + +**`PatchRequest`** + +{CODE:python PatchRequest-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +Learn more about `PatchRequest` [here](../../../../client-api/operations/patching/single-document#session-api-using-defer). + +{PANEL/} + +## Related articles + +**Time Series and JavaScript** +[The Time Series JavaScript API](../../../../document-extensions/timeseries/client-api/javascript-support) + +**Client API** +[Time Series API Overview](../../../../document-extensions/timeseries/client-api/overview) + +**Studio Articles** +[Studio Time Series Management](../../../../studio/database/document-extensions/time-series) + +**Querying and Indexing** +[Time Series Querying](../../../../document-extensions/timeseries/querying/overview-and-syntax) +[Time Series Indexing](../../../../document-extensions/timeseries/indexing) + +**Policies** +[Time Series Rollup and Retention](../../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.dotnet.markdown index b8660dc52e..5a4e3f25c9 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.dotnet.markdown @@ -36,8 +36,6 @@ Learn more about time series queries in the [section dedicated to this subject]( {PANEL: Query} ---- - ### Query usage * Open a session @@ -56,11 +54,10 @@ Learn more about time series queries in the [section dedicated to this subject]( ### Query examples -{NOTE: } -This LINQ query filters users by their age and retrieves their HeartRates time series. -The first occurence of `Where` filters the documents. -The second `Where` filters the time series entries. -{CODE-TABS} +* This LINQ query filters users by their age and retrieves their HeartRates time series. + The first occurence of `Where` filters the documents. + The second `Where` filters the time series entries. + {CODE-TABS} {CODE-TAB:csharp:Query ts_region_LINQ-1-Select-Timeseries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB-BLOCK:sql:RQL} from "Users" as q @@ -68,34 +65,27 @@ where q.Age < 30 select timeseries(from q.HeartRates where (Tag == "watches/fitbit")) {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } -In this example, we select a three-day range from the HeartRates time series. -{CODE-TABS} +* In this example, we select a three-day range from the HeartRates time series. + {CODE-TABS} {CODE-TAB:csharp:Query ts_region_LINQ-3-Range-Selection@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB-BLOCK:sql:RQL} from "Users" as q select timeseries(from q.HeartRates between "2020-05-17T00:00:00.0000000" and "2020-05-17T00:03:00.0000000") {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } -In this example, we retrieve a company's stock trade data. -Note the usage of named values, so we may address trade Volume [by name](../../../../document-extensions/timeseries/client-api/named-time-series-values). -{CODE-TABS} +* In this example, we retrieve a company's stock trade data. + Note the usage of named values, so we may address trade Volume [by name](../../../../document-extensions/timeseries/client-api/named-time-series-values). + {CODE-TABS} {CODE-TAB:csharp:Native timeseries_region_Unnamed-Values-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB:csharp:Named timeseries_region_Named-Values-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TABS/} -{NOTE/} -{NOTE: } -In this example, we group heart-rate data of people above the age of 72 into 1-day groups, -and retrieve each group's average heart rate and number of measurements. -The aggregated results are retrieved as `List`. -{CODE ts_region_LINQ-6-Aggregation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +* In this example, we group heart-rate data of people above the age of 72 into 1-day groups, + and retrieve each group's average heart rate and number of measurements. + The aggregated results are retrieved as `List`. + {CODE ts_region_LINQ-6-Aggregation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} --- @@ -134,8 +124,6 @@ Where(Expression> predicate); {PANEL: DocumentQuery} ---- - ### DocumentQuery usage * Open a session @@ -154,38 +142,28 @@ Where(Expression> predicate); ### DocumentQuery examples -{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/} +* 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: } -A _DocumentQuery_ using `Between()`. -The query returns only entries from the specified time range. -{CODE TS_DocQuery_2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +* A _DocumentQuery_ using `Between()`. + The query returns only entries from the specified time range. + {CODE TS_DocQuery_2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE: } -A _DocumentQuery_ using `FromFirst()`. -The query returns the first three days of the 'HeartRates' time series. -{CODE TS_DocQuery_3@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +* A _DocumentQuery_ using `FromFirst()`. + The query returns the first three days of the 'HeartRates' time series. + {CODE TS_DocQuery_3@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE: } -A _DocumentQuery_ using `FromLast()`. -The query returns the last three days of the 'HeartRates' time series. -{CODE TS_DocQuery_4@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE/} +* A _DocumentQuery_ using `FromLast()`. + The query returns the last three days of the 'HeartRates' time series. + {CODE TS_DocQuery_4@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} -{NOTE: } -A _DocumentQuery_ that loads the related `Monitor` documents that are specified in the time entries tags. -The results are then filtered by their content. -{CODE-TABS} +* A _DocumentQuery_ that loads the related `Monitor` documents that are specified in the time entries tags. + The results are then filtered by their content. + {CODE-TABS} {CODE-TAB:csharp:Query TS_DocQuery_5@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB:csharp:Class TS_DocQuery_class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TABS/} -{NOTE/} --- @@ -249,15 +227,13 @@ public interface ITimePeriodBuilder {PANEL: RawQuery} ---- - ### RawQuery usage * Open a session * Call `session.Advanced.RawQuery`, pass it the raw RQL that will be sent to the server * Results will be in the form: - * `TimeSeriesRawResult` for non-aggregated data, or - - * `TimeSeriesAggregationResult` for aggregated data + * `TimeSeriesRawResult` for non-aggregated data, or - + * `TimeSeriesAggregationResult` for aggregated data * Note: The raw query transmits the provided RQL to the server as is, without checking or altering its content. @@ -265,39 +241,24 @@ public interface ITimePeriodBuilder ### RawQuery examples -{NOTE: } - -In this example, we retrieve all HearRates time series for all users under 30. - -{CODE-TABS} +* In this example, we retrieve all HearRates time series for all users under 30. + {CODE-TABS} {CODE-TAB:csharp:RawQuery ts_region_LINQ-2-RQL-Equivalent@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, a raw RQL query retrieves 24 hours of heart rate data from users under the age of 30. -* The query does not aggregate data, so results are in the form of a `TimeSeriesRawResult` list. -* We define an **offset**, to adjust retrieved results to the client's local time-zone. - -{CODE-TABS} + The query does not aggregate data, so results are in the form of a `TimeSeriesRawResult` list. + We define an **offset**, to adjust retrieved results to the client's local time-zone. + {CODE-TABS} {CODE-TAB:csharp:Declare-Syntax ts_region_Raw-Query-Non-Aggregated-Declare-Syntax@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TAB:csharp:Select-Syntax ts_region_Raw-Query-Non-Aggregated-Select-Syntax@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, the query aggregates 7 days of HeartRates entries into 1-day groups. -* From each group, two values are selected and projected to the client: + From each group, two values are selected and projected to the client: the **min** and **max** hourly HeartRates values. -* The aggregated results are in the form of a `TimeSeriesAggregationResult` list. - -{CODE ts_region_Raw-Query-Aggregated@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} - -{NOTE/} + The aggregated results are in the form of a `TimeSeriesAggregationResult` list. + {CODE ts_region_Raw-Query-Aggregated@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} --- diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.js.markdown index f7f9e28b26..218f322f90 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying.js.markdown @@ -31,8 +31,6 @@ Learn more about time series queries in the [section dedicated to this subject]( {PANEL: Query} ---- - ### Query usage * Open a session @@ -50,11 +48,8 @@ Learn more about time series queries in the [section dedicated to this subject]( ### Query examples -{NOTE: } - -This query filters users by their age and retrieves their HeartRates time series. - -{CODE-TABS} +* This query filters users by their age and retrieves their HeartRates time series. + {CODE-TABS} {CODE-TAB:nodejs:Query query_1@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} from "users" @@ -66,12 +61,8 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } -In this example, we select a 5-minute range from the HeartRates time series. - -{CODE-TABS} +* In this example, we select a 5-minute range from the HeartRates time series. + {CODE-TABS} {CODE-TAB:nodejs:Query query_2@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} from "Users" @@ -82,15 +73,10 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, we retrieve a company's stock trade data. -* Note the usage of named values, so we may address trade Volume [by name](../../../../document-extensions/timeseries/client-api/named-time-series-values). -* This example is based on the sample entries that were entered in [this example](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values). - -{CODE-TABS} + Note the usage of named values, so we may address trade Volume [by name](../../../../document-extensions/timeseries/client-api/named-time-series-values). + This example is based on the sample entries that were entered in [this example](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values). + {CODE-TABS} {CODE-TAB:nodejs:Native query_3@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB:nodejs:Named query_4@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} @@ -105,14 +91,9 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, we group heart-rate data of people above the age of 72 into 1-day groups, -* For each group, we retrieve the number of measurements, the minimum, maximum, and average heart rate. - -{CODE-TABS} + For each group, we retrieve the number of measurements, the minimum, maximum, and average heart rate. + {CODE-TABS} {CODE-TAB:nodejs:Native query_5@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} from "users" @@ -127,8 +108,6 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - --- ### Query syntax @@ -163,8 +142,6 @@ The time series query builder has one method: {PANEL: RawQuery} ---- - ### RawQuery usage * Open a session @@ -179,11 +156,8 @@ The time series query builder has one method: ### RawQuery examples -{NOTE: } - -In this example, we retrieve all HearRates time series for all users under 30. - -{CODE-TABS} +* In this example, we retrieve all HearRates time series for all users under 30. + {CODE-TABS} {CODE-TAB:nodejs:RawQuery query_6@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} from users where age < 30 @@ -193,15 +167,10 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, a raw RQL query retrieves 24 hours of heart rate data from users under 30. -* The query does not aggregate data, so results are in the form of a `TimeSeriesRawResult` list. -* We define an **offset**, to adjust retrieved results to the client's local time-zone. - -{CODE-TABS} + The query does not aggregate data, so results are in the form of a `TimeSeriesRawResult` list. + We define an **offset**, to adjust retrieved results to the client's local time-zone. + {CODE-TABS} {CODE-TAB:nodejs:Declare-Syntax query_7@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB:nodejs:Select-Syntax query_8@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} @@ -232,16 +201,11 @@ select timeseries ( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - * In this example, the query aggregates 7 days of HeartRates entries into 1-day groups. -* From each group, two values are selected and projected to the client: + From each group, two values are selected and projected to the client: the **min** and **max** hourly HeartRates values. -* The aggregated results are in the form of a `TimeSeriesAggregationResult` list. - -{CODE-TABS} + The aggregated results are in the form of a `TimeSeriesAggregationResult` list. + {CODE-TABS} {CODE-TAB:nodejs:RawQuery query_9@documentExtensions\timeSeries\client-api\queryTimeSeries.js /} {CODE-TAB-BLOCK:sql:RQL} from users as u @@ -255,8 +219,6 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - --- ### RawQuery syntax diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown index fea468b857..3a63119709 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown @@ -27,9 +27,7 @@ {PANEL: Time series indexes vs Document indexes} -{NOTE: } - -**Auto-Indexes**: +#### Auto-Indexes: * Time series index: Dynamic time series indexes are Not created in response to queries. @@ -37,10 +35,9 @@ * Document index: [Auto-indexes](../../studio/database/indexes/indexes-overview#indexes-types) are created in response to dynamic queries. -{NOTE/} -{NOTE: } +--- -**Data source**: +#### Data source: * Time series index: @@ -69,10 +66,9 @@ from employee in employees ... {CODE-BLOCK/} -{NOTE/} -{NOTE: } +--- -**Query results**: +#### Query results: * Time series index: When [querying](../../document-extensions/timeseries/querying/using-indexes) a time series index, each result item corresponds to the type defined by the **index-entry** in the index definition, @@ -81,7 +77,6 @@ from employee in employees * Document index: The resulting objects are the document entities (unless results are [projected](../../indexes/querying/projections)). -{NOTE/} {PANEL/} {PANEL: Ways to create a time series index} @@ -104,11 +99,7 @@ There are two main ways to create a time series index: {PANEL: Examples of time series indexes} -{NOTE: } - -#### Map index - index single time series from single collection - ---- +#### Map index - index single time series from single collection: * In this index, we index data from the "StockPrices" time series entries in the "Companies" collection (`TradeVolume`, `Date`). @@ -141,51 +132,38 @@ select distinct CompanyID {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map index - index all time series from single collection - --- +#### Map index - index all time series from single collection: + {CODE-TABS} {CODE-TAB:csharp:Map_index index_4@DocumentExtensions\TimeSeries\Indexing.cs /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map index - index all time series from all collections - --- +#### Map index - index all time series from all collections: + {CODE-TABS} {CODE-TAB:csharp:Map_index index_5@DocumentExtensions\TimeSeries\Indexing.cs /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Multi-Map index - index time series from several collections - --- +#### Multi-Map index - index time series from several collections: + {CODE-TABS} {CODE-TAB:csharp:Multi_Map_index index_6@DocumentExtensions\TimeSeries\Indexing.cs /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map-Reduce index - --- +#### Map-Reduce index: + {CODE-TABS} {CODE-TAB:csharp:Map_Reduce_index index_7@DocumentExtensions\TimeSeries\Indexing.cs /} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.js.markdown index a5e0144fd6..663257d580 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.js.markdown @@ -24,9 +24,7 @@ {PANEL: Time series indexes vs Document indexes} -{NOTE: } - -**Auto-Indexes**: +#### Auto-Indexes: * Time series index: Dynamic time series indexes are Not created in response to queries. @@ -34,10 +32,9 @@ * Document index: [Auto-indexes](../../studio/database/indexes/indexes-overview#indexes-types) are created in response to dynamic queries. -{NOTE/} -{NOTE: } +--- -**Data source**: +#### Data source: * Time series index: @@ -54,10 +51,9 @@ * The index processes fields from your JSON documents. Documents are indexed through the collection they belong to. -{NOTE/} -{NOTE: } +--- -**Query results**: +#### Query results: * Time series index: When [querying](../../document-extensions/timeseries/querying/using-indexes) a time series index, each result item corresponds to the type defined by the **index-entry** in the index definition, @@ -66,7 +62,6 @@ * Document index: The resulting objects are the document entities (unless results are [projected](../../indexes/querying/projections)). -{NOTE/} {PANEL/} {PANEL: Ways to create a time series index} @@ -82,11 +77,7 @@ There are two main ways to create a time series index: {PANEL: Examples of time series indexes} -{NOTE: } - -#### Map index - index single time series from single collection - ---- +#### Map index - index single time series from single collection: * In this index, we index data from the "StockPrices" time series entries in the "Companies" collection (`tradeVolume`, `date`). @@ -114,51 +105,38 @@ select distinct companyID {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map index - index all time series from single collection - --- +#### Map index - index all time series from single collection: + {CODE-TABS} {CODE-TAB:nodejs:Map_index index_2@documentExtensions\timeSeries\indexing.js /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map index - index all time series from all collections - --- +#### Map index - index all time series from all collections: + {CODE-TABS} {CODE-TAB:nodejs:Map_index index_3@documentExtensions\timeSeries\indexing.js /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Multi-Map index - index time series from several collections - --- +#### Multi-Map index - index time series from several collections: + {CODE-TABS} {CODE-TAB:nodejs:Multi_Map_index index_4@documentExtensions\timeSeries\indexing.js /} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Map-Reduce index - --- +#### Map-Reduce index: + {CODE-TABS} {CODE-TAB:nodejs:Map_Reduce_index index_5@documentExtensions\timeSeries\indexing.js /} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.dotnet.markdown index 353f42a606..b43e46b3eb 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.dotnet.markdown @@ -12,7 +12,7 @@ * In this page: * [Grouping and aggregation options](../../../document-extensions/timeseries/querying/aggregation-and-projections#grouping-and-aggregation-options) - * [Examples](../../../document-extensions/timeseries/querying/aggregation-and-projections#Examples) + * [Examples](../../../document-extensions/timeseries/querying/aggregation-and-projections#examples) * [Aggregate entries with single value](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-with-single-value) * [Aggregate entries with multiple values](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-with-multiple-values) * [Aggregate entries without grouping by time frame](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-without-grouping-by-time-frame) @@ -83,11 +83,7 @@ the aggregation calculations will be executed over the entire set of time series {PANEL: Examples} -{NOTE: } - -#### Aggregate entries with single value - ---- +#### Aggregate entries with single value: * Each entry in the "HeartRates" time series within the Employees collection contains a single value. @@ -110,13 +106,10 @@ the aggregation calculations will be executed over the entire set of time series {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Aggregate entries with multiple values - --- +#### Aggregate entries with multiple values: + * Each entry in the "StockPrices" time series within the Companies collection holds five values: Values[0] - **Open** - stock price when trade opens Values[1] - **Close** - stock price when trade ends @@ -162,13 +155,10 @@ where c.Address.Country = 'USA' * 5 `Max` values for each group (the highest Values[0], highest Values[1], etc.) and * 5 `Min` values for each group (the lowest Values[0], lowest Values[1], etc.) -{NOTE/} -{NOTE: } - -#### Aggregate entries without grouping by time frame - --- +#### Aggregate entries without grouping by time frame: + * This example is similar to the one above, except that time series entries are Not grouped by a time frame. * The highest and lowest values are collected from the entire set of time series entries that match the query criteria. @@ -192,13 +182,10 @@ select SP(c) * Since no grouping is done, results wil include the highest and lowest Open, Close, High, Low, and Volume values for ALL entries in the time series that match the query criteria. -{NOTE/} -{NOTE: } - -#### Aggregate entries filtered by referenced document - --- +#### Aggregate entries filtered by referenced document: + * The tag in each entry in the "StockPrices" series contains an Employee document ID. * In this example, we load this [referenced document](../../../document-extensions/timeseries/querying/filtering#filter-by-referenced-document) @@ -223,13 +210,10 @@ select timeseries( * Only entries that reference an employee with title 'Sales Representative' will be grouped by 1 month, and the results will include the highest and lowest values for each group. -{NOTE/} -{NOTE: } - -#### Secondary grouping by tag - --- +#### Secondary grouping by tag: + * In this example, we perform secondary grouping by the entries' tags. * The tag in each entry in the "StockPrices" series contains an Employee document ID. @@ -249,13 +233,10 @@ select timeseries ( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Group by dynamic criteria - --- +#### Group by dynamic criteria: + Starting in version 5.2, the LINQ method `GroupBy()` can take a switch statement or a method as an argument. * In this example, we pass a switch statement to the `GroupBy()` method. @@ -288,13 +269,10 @@ select timeseries ( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Project document data in addition to aggregated data - --- +#### Project document data in addition to aggregated data: + * In addition to projecting the aggregated time series data, you can project data from the parent document that contains the time series. * In this example, projecting the **company name** alongside the query results clearly associates each entry in the result set with a specific company. @@ -327,7 +305,6 @@ c.Name as CompanyName // Project property 'Name' from the company document {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.js.markdown index d307edf7ac..ebfdd54216 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.js.markdown @@ -12,7 +12,7 @@ * In this page: * [Grouping and aggregation options](../../../document-extensions/timeseries/querying/aggregation-and-projections#grouping-and-aggregation-options) - * [Examples](../../../document-extensions/timeseries/querying/aggregation-and-projections#Examples) + * [Examples](../../../document-extensions/timeseries/querying/aggregation-and-projections#examples) * [Aggregate entries with single value](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-with-single-value) * [Aggregate entries with multiple values](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-with-multiple-values) * [Aggregate entries without grouping by time frame](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregate-entries-without-grouping-by-time-frame) @@ -81,12 +81,8 @@ the aggregation calculations will be executed over the entire set of time series {PANEL: Examples} -{NOTE: } - #### Aggregate entries with single value ---- - * Each entry in the "HeartRates" time series within the Employees collection contains a single value. * In this example, for each employee document, we group entries from the "HeartRates" time series @@ -108,13 +104,10 @@ the aggregation calculations will be executed over the entire set of time series {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Aggregate entries with multiple values - --- +#### Aggregate entries with multiple values: + * Each entry in the "StockPrices" time series within the Companies collection holds five values: Values[0] - **Open** - stock price when trade opens Values[1] - **Close** - stock price when trade ends @@ -160,13 +153,10 @@ where c.Address.Country = 'USA' * 5 `Max` values for each group (the highest Values[0], highest Values[1], etc.) and * 5 `Min` values for each group (the lowest Values[0], lowest Values[1], etc.) -{NOTE/} -{NOTE: } - -#### Aggregate entries without grouping by time frame - --- +#### Aggregate entries without grouping by time frame: + * This example is similar to the one above, except that time series entries are Not grouped by a time frame. * The highest and lowest values are collected from the entire set of time series entries that match the query criteria. @@ -190,13 +180,10 @@ select SP(c) * Since no grouping is done, results wil include the highest and lowest Open, Close, High, Low, and Volume values for ALL entries in the time series that match the query criteria. -{NOTE/} -{NOTE: } - -#### Aggregate entries filtered by referenced document - --- +#### Aggregate entries filtered by referenced document: + * The tag in each entry in the "StockPrices" series contains an Employee document ID. * In this example, we load this [referenced document](../../../document-extensions/timeseries/querying/filtering#filter-by-referenced-document) @@ -221,13 +208,10 @@ select timeseries( * Only entries that reference an employee with title 'Sales Representative' will be grouped by 1 month, and the results will include the highest and lowest values for each group. -{NOTE/} -{NOTE: } - -#### Secondary grouping by tag - --- +#### Secondary grouping by tag: + * In this example, we perform secondary grouping by the entries' tags. * The tag in each entry in the "StockPrices" series contains an Employee document ID. @@ -247,13 +231,10 @@ select timeseries ( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - -#### Project document data in addition to aggregated data - --- +#### Project document data in addition to aggregated data: + * In addition to projecting the aggregated time series data, you can project data from the parent document that contains the time series. * In this example, projecting the **company name** alongside the query results clearly associates each entry in the result set with a specific company. @@ -285,7 +266,6 @@ c.Name as CompanyName // Project property 'Name' from the company document {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.dotnet.markdown index f6637c9714..82221a60f4 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.dotnet.markdown @@ -11,11 +11,11 @@ * 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) + * [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) + * [`between` and `and`](../../../document-extensions/timeseries/querying/choosing-query-range#and-) + * [`first` and `last`](../../../document-extensions/timeseries/querying/choosing-query-range#and--1) {NOTE/} @@ -23,17 +23,15 @@ {PANEL: Choose range in a query} -{NOTE: } - -#### Specify range +#### 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. +* 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. +* The provided DateTime values are handled 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. +* In this example, we specify a 10-minute range from which we retrieve UK employees "HeartRates" entries. {CODE-TABS} {CODE-TAB:csharp:Query choose_range_1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} @@ -51,17 +49,15 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } +--- -#### Retrieve first or last entries +#### 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. + A query function can use either `FromFirst` or `FromLast`, but not both. -* In this example, we select only the entries in the last 30 minutes of time series "HeartRates". +* In this example, we select only entries in the last 30 minutes of the "HeartRates" time series. {CODE-TABS} {CODE-TAB:csharp:Query choose_range_4@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} @@ -77,22 +73,16 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Choose range - RQL syntax} -{NOTE: } - -#### `between` and `and` - ---- +#### `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-TABS} {CODE-TAB-BLOCK:sql:RQL_select_syntax} from "Employees" where Address.Country == "UK" @@ -118,12 +108,11 @@ select getHeartRates(e) // Results will include only time series entries within the specified range for employees from UK. {CODE-TAB-BLOCK/} - {CODE-TABS/} +{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} +* RQL queries can be executed from Studio's [query view](../../../studio/database/queries/query-view). + Using Studio, you can apply parameters as follows for a clearer query. + {CODE-BLOCK:sql} $from = "2020-05-17T00:00:00.0000000Z" $to = "2020-05-17T01:00:00.0000000Z" @@ -133,37 +122,33 @@ select timeseries( from HeartRates between $from and $to // using parameters ) - {CODE-BLOCK/} - -{NOTE/} - -{NOTE: } - -#### `first` and `last` +{CODE-BLOCK/} --- +#### `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.: + A query function can use either `first` or `last`, but not both. E.g. - - {CODE-BLOCK: sql} + {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/} - {CODE-BLOCK: sql} + {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/} +{CODE-BLOCK/} * The range is specified using a whole number of one of the following units. @@ -176,7 +161,6 @@ select timeseries( * **years** ( years / year / y ) * Note: **milliseconds** are currently not supported by 'first' and 'last' in a time series query. -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.js.markdown index d37cc53d84..51593c6bab 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.js.markdown @@ -11,11 +11,11 @@ * 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) + * [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) + * [`between` and `and`](../../../document-extensions/timeseries/querying/choosing-query-range#and-) + * [`first` and `last`](../../../document-extensions/timeseries/querying/choosing-query-range#and--1) {NOTE/} @@ -23,19 +23,17 @@ {PANEL: Choose range in a query} -{NOTE: } - -#### Specify range +#### 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. +* 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. +* The provided DateTime values are handled by the server as UTC. + The client does Not perform any conversion to UTC prior to sending the request to the server. -* Note: calling 'offset' will only adjust the timestamps in the returned results to your local time (optional). +* Note: calling 'offset' will only adjust the timestamps in the returned results to your local time (optional). -* In this example, we specify a 10-minute range from which to retrieve "HeartRates" entries for UK employees. +* In this example, we specify a 10-minute range from which we retrieve UK employees "HeartRates" entries. {CODE-TABS} {CODE-TAB:nodejs:Query choose_range_1@documentExtensions\timeSeries\querying\queryRange.js /} @@ -69,17 +67,15 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } +--- -#### Retrieve first or last entries +#### Retrieve first or last entries: * 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. + A query function can use either `first` or `last`, but not both. -* In this example, we select only the entries in the last 30 minutes of time series "HeartRates". +* In this example, we select only entries in the last 30 minutes of the "HeartRates" time series. {CODE-TABS} {CODE-TAB:nodejs:Query choose_range_5@documentExtensions\timeSeries\querying\queryRange.js /} @@ -94,22 +90,16 @@ select timeseries( {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Choose range - RQL syntax} -{NOTE: } - -#### `between` and `and` - ---- +#### `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-TABS} {CODE-TAB-BLOCK:sql:RQL_select_syntax} from "Employees" where Address.Country == "UK" @@ -135,12 +125,11 @@ select getHeartRates(e) // Results will include only time series entries within the specified range for employees from UK. {CODE-TAB-BLOCK/} - {CODE-TABS/} +{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} +* RQL queries can be executed from Studio's [query view](../../../studio/database/queries/query-view). + Using Studio, you can apply parameters as follows for a clearer query. + {CODE-BLOCK:sql} $from = "2020-05-17T00:00:00.0000000Z" $to = "2020-05-17T01:00:00.0000000Z" @@ -150,37 +139,33 @@ select timeseries( from HeartRates between $from and $to // using parameters ) - {CODE-BLOCK/} - -{NOTE/} - -{NOTE: } - -#### `first` and `last` +{CODE-BLOCK/} --- +#### `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} + A query function can use either `first` or `last`, but not both. 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/} - {CODE-BLOCK: sql} + {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/} +{CODE-BLOCK/} * The range is specified using a whole number of one of the following units. @@ -193,7 +178,6 @@ select timeseries( * **years** ( years / year / y ) * Note: **milliseconds** are currently not supported by 'first' and 'last' in a time series query. -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.python.markdown new file mode 100644 index 0000000000..589c4ff412 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.python.markdown @@ -0,0 +1,173 @@ +# 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} + +#### 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 handled 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 we retrieve UK employees "HeartRates" entries. + +{CODE-BLOCK:sql} +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-BLOCK/} + +--- + +#### Retrieve first or last entries: + +* 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. + A query function can use either `first` or `last`, but not both. + +* In this example, we select only entries in the last 30 minutes of the "HeartRates" time series. + +{CODE-BLOCK:sql} +from "Employees" as e +select timeseries( + from e.HeartRates + last 30 min + offset "03:00" +) +{CODE-BLOCK/} + +{PANEL/} + +{PANEL: Choose range - RQL syntax} + +#### `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 executed from Studio's [query view](../../../studio/database/queries/query-view). + Using Studio, you can apply parameters as follows 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/} + +--- + +#### `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. + A query function can use either `first` or `last`, but not both. 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. + +{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) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.dotnet.markdown index 7ab9e76b7f..2accead5b1 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.dotnet.markdown @@ -69,7 +69,7 @@ select timeseries( {CODE-BLOCK/} * **Index queries**: - * Static time series indexes can be created by clients (or using the Studio). + * Static time series indexes can be created by clients (or using Studio). To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes). @@ -254,7 +254,7 @@ This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LIN {PANEL: Use Studio to experiment} -You can use the [Studio](../../../studio/database/document-extensions/time-series) to try the RQL samples provided in this article and test your own queries. +You can use [Studio](../../../studio/database/document-extensions/time-series) to try the RQL samples provided in this article and test your own queries. !["Time Series Query in Studio"](images/time-series-query.png "Time Series Query in Studio") diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.js.markdown index eeba42dd42..89c0ec177b 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.js.markdown @@ -71,7 +71,7 @@ select timeseries ( {CODE-TABS/} * **Index queries**: - * Static time series indexes can be created by clients (or using the Studio). + * Static time series indexes can be created by clients (or using Studio). To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes). @@ -236,7 +236,7 @@ select {PANEL: Use Studio to experiment} -You can use the [Studio](../../../studio/database/document-extensions/time-series) to try the RQL samples provided in this article and test your own queries. +You can use [Studio](../../../studio/database/document-extensions/time-series) to try the RQL samples provided in this article and test your own queries. !["Time Series Query in Studio"](images/time-series-query.png "Time Series Query in Studio") diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.python.markdown new file mode 100644 index 0000000000..cd0d06d056 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.python.markdown @@ -0,0 +1,281 @@ +# Querying Time Series: Overview & Syntax +--- + +{NOTE: } + +* Querying time series entries enables comprehending how a process gradually populates a time series over time and locating documents related to chosen time series entries. + +* Querying time series data is native to RavenDB's queries. + Clients can express time series queries in high-level LINQ expressions or directly in [RQL](../../../client-api/session/querying/what-is-rql). + +* Queries can be executed as dynamic queries or over [time series indexes](../../../document-extensions/timeseries/indexing). + +* In this page: + * [Time series query capabilities](../../../document-extensions/timeseries/querying/overview-and-syntax#time-series-query-capabilities) + * [Server and client queries](../../../document-extensions/timeseries/querying/overview-and-syntax#server-and-client-queries) + * [Dynamic and index queries](../../../document-extensions/timeseries/querying/overview-and-syntax#dynamic-and-index-queries) + * [Scaling query results](../../../document-extensions/timeseries/querying/overview-and-syntax#scaling-query-results) + * [RQL syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#rql-syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#section-1) + * [Combine time series and custom functions](../../../document-extensions/timeseries/querying/overview-and-syntax#combine-time-series-and-custom-functions) + * [Use Studio To experiment](../../../document-extensions/timeseries/querying/overview-and-syntax#use-studio-to-experiment) + +{NOTE/} + +--- + +{PANEL: Time series query capabilities} + +Time series query can - + +* [Choose a range of time series entries](../../../document-extensions/timeseries/querying/choosing-query-range) to query from. +* [Filter](../../../document-extensions/timeseries/querying/filtering) time series entries by their tags, values and timestamps. +* [Aggregate](../../../document-extensions/timeseries/querying/aggregation-and-projections) time series entries into groups by a chosen time resolution, + e.g. gather the prices of a stock that's been collected over the past two months to week-long groups. + Entries can also be aggregated by their tags. +* Select entries by various criteria, e.g. by the min and max values of each aggregated group, + and [project](../../../document-extensions/timeseries/querying/aggregation-and-projections) them to the client. +* Calculate [statistical measures](../../../document-extensions/timeseries/querying/statistics): the percentile, slope, or standard deviation of a time series. + +{PANEL/} + +{PANEL: Server and client queries} + +Time series queries are executed by the server and their results are projected to the client, +so they require very little client computation resources. + +* The server runs time series queries using RQL. +* Clients can phrase time series queries in **raw RQL** or using high level **LINQ expressions**. + High level queries are translated to RQL by the client before sending them to the server for execution. + +{PANEL/} + +{PANEL: Dynamic and index queries} + +* **Dynamic queries**: + * Time series indexes are Not created automatically by the server when making a dynamic query. + * Use dynamic queries when time series you query are not indexed, + or when you prefer that RavenDB would choose an index automatically. See [queries always use an index](../../../client-api/session/querying/how-to-query#queries-always-provide-results-using-an-index). + E.g. - + + {CODE-BLOCK: javascript} +// Query for time series named "HeartRates" in employees hired after 1994 +from Employees as e +where HiredAt > "1994-01-01" +select timeseries( + from HeartRates +) + {CODE-BLOCK/} + +* **Index queries**: + * Static time series indexes can be created by clients (or using Studio). + To learn how to create such indexes, see [indexing time series](document-extensions/timeseries/indexing). + * Examples of querying a static time series index can be found in [querying time series indexes](../../../document-extensions/timeseries/querying/using-indexes). + +{PANEL/} + +{PANEL: Scaling query results} + +* Time series query results can be **scaled**, multiplied by some number. + This doesn't change the values themselves, only the output of the query. + Scaling can serve as a stage in a data processing pipeline, or just for the purposes of displaying the data in a more understandable format. + +* There are several use cases for scaling. + For example, suppose your time series records the changing speeds of different vehicles as they travel through a city, + with some data measured in miles per hour and others in kilometers per hour. Here, scaling can facilitate unit conversion. + +* Another use case involves the compression of time series data. + Numbers with very high precision (i.e., many digits after the decimal point) are less compressible than numbers with low precision. + Therefore, for efficient storage, you might want to change a value like `0.000018` to `18` when storing the data. + Then, when querying the data, you can scale by `0.000001` to restore the original value. + +* Scaling is a part of both RQL and LINQ syntax: + + * In **LINQ**, use `.Scale()`. + * In **RQL**, use `scale ` in a time series query, and input your scaling factor as a double. + +--- + +#### Example: + +{CODE-TABS} +{CODE-TAB-BLOCK:python:LINQ} +var query = session.Query() + .Select(p => RavenQuery.TimeSeries(p, "HeartRates") + .Scale(10) + .ToList()) + .ToList(); + +// The value in the query results is 10 times the value stored on the server +var scaledValue = query[0].Results[0].Values[0]; +{CODE-TAB-BLOCK/} +{CODE-TAB-BLOCK:sql:RQL} +from Users +select timeseries( + from HeartRates + scale 10 +) +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: RQL syntax} + +A typical time series query can start by locating the documents whose time series we want to query. +For example, we can query for employees above 30: + +{CODE-BLOCK: javascript} +from Employees as e +where Birthday < '1994-01-01' +{CODE-BLOCK/} + +Then, you can query their time series entries using either of the following two equivalent syntaxes: + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#section-1) + +--- + +### `select timeseries` + +This syntax allows you to encapsulate your query's time series functionality in a `select timeseries` section. + +{CODE-BLOCK: javascript} +// Query for entries from time series "HeartRates" for employees above 30 +// ====================================================================== + +// This clause locates the documents whose time series we want to query: +from Employees as e +where Birthday < '1994-01-01' + +// Query the time series that belong to the matching documents: +select timeseries ( // The `select` clause defines the time series query. + from HeartRates // The `from` keyword is used to specify the time series name to query. +) +{CODE-BLOCK/} + +--- + +### `declare timeseries` + +This syntax allows you to declare a time series function (using `declare timeseries`) and call it from your query. +It introduces greater flexibility to your queries as you can, for example, pass arguments to the time series function. + +Here is a query written in both syntaxes. +It first queries for users above 30. If they possess a time series named "HeartRates", it retrieves a range of its entries. + +
+ +| With Time Series Function | Without Time Series Function | +|----------------------------|-------------------------------| +| {CODE-BLOCK: javascript} +// declare the time series function: +declare timeseries ts(jogger) { + from jogger.HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z" +} + +from Users as jogger +where Age > 30 +// call the time series function +select ts(jogger) +{CODE-BLOCK/} | {CODE-BLOCK: javascript} +from Users as jogger +where Age > 30 +select timeseries( + from HeartRates + between + "2020-05-27T00:00:00.0000000Z" + and + "2020-06-23T00:00:00.0000000Z") + {CODE-BLOCK/} | + +{PANEL/} + +{PANEL: Combine time series and custom functions} + +* You can declare and use both time series functions and custom functions in a query. + The custom functions can call the time series functions, pass them arguments, and use their results. + +* In the example below, a custom function (`customFunc`) is called by the query `select` clause + to fetch and format a set of time series entries, which are then projected by the query. + The time series function (`tsQuery`) is called to retrieve the matching time series entries. + +* The custom function returns a flat set of values rather than a nested array, to ease the projection of retrieved values. + +* Note the generated RQL, where the custom function is translated to a [custom JavaScript function](../../../client-api/session/querying/what-is-rql#declare). + +{CODE-BLOCK:javascript} +// The time series function: +// ========================= +declare timeseries tsQuery(user) { + from user.HeartRates + where (Values[0] > 100) +} + +// The custom JavaScript function: +// =============================== +declare function customFunc(user) { + var results = []; + + // Call the time series function to retrieve heart rate values for the user + var r = tsQuery(user); + + // Prepare the results + for(var i = 0 ; i < r.Results.length; i ++) { + results.push({ + Timestamp: r.Results[i].Timestamp, + Value: r.Results[i].Values.reduce((a, b) => Raven_Max(a, b)), + Tag: r.Results[i].Tag ?? "none"}) + } + return results; +} + +// Query & project results: +// ======================== +from "Users" as user +select + user.Name, + customFunc(user) as timeSeriesEntries // Call the custom JavaScript function +{CODE-BLOCK/} + +This is the custom `ModifiedTimeSeriesEntry` class that is used in the above LINQ sample: + +{CODE:python DefineCustomFunctions_ModifiedTimeSeriesEntry@DocumentExtensions\TimeSeries\TimeSeriesTests.py /} + +{PANEL/} + +{PANEL: Use Studio to experiment} + +You can use [Studio](../../../studio/database/document-extensions/time-series) to try the RQL samples provided in this article and test your own queries. + +!["Time Series Query in Studio"](images/time-series-query.png "Time Series Query in Studio") + +{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** +[Range Selection](../../../document-extensions/timeseries/querying/choosing-query-range) +[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) +[Statistical Measures](../../../document-extensions/timeseries/querying/statistics) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown index 2ce14fdec5..689a6b1e8f 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown @@ -58,11 +58,7 @@ {PANEL: Querying the index} -{NOTE: } - - **Query all time series entries**: - ---- +#### Query all time series entries: No filtering is applied in this query. Results will include ALL entries from time series "HeartRates". @@ -77,13 +73,10 @@ from index "TsIndex" {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - - **Filter query results**: - --- +#### Filter query results: + In this example, time series entries are filtered by the query. The query predicate is applied to the index-fields. @@ -98,13 +91,10 @@ where EmployeeName == "Robert King" and BPM > 85.0 {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - - **Order query results**: - --- +#### Order query results: + Results can be ordered by any of the index-fields. {CODE-TABS} @@ -119,14 +109,10 @@ order by Date desc {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - - **Project results**: - --- +#### Project results: + * Instead of returning the entire `TsIndex.IndexEntry` object for each result item, you can return only partial fields. @@ -148,7 +134,6 @@ select distinct EmployeeID {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown index 250ef1eac8..1f27972297 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown @@ -57,11 +57,7 @@ {PANEL: Querying the index} -{NOTE: } - - **Query all time series entries**: - ---- +#### Query all time series entries: No filtering is applied in this query. Results will include ALL entries from time series "HeartRates". @@ -74,13 +70,10 @@ from index "TsIndex" {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - - **Filter query results**: - --- +#### Filter query results: + In this example, time series entries are filtered by the query. The query predicate is applied to the index-fields. @@ -93,13 +86,10 @@ where employeeName == "Robert King" and bpm >= 85 {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} -{NOTE: } - - **Order query results**: - --- +#### Order query results: + Results can be ordered by any of the index-fields. {CODE-TABS} @@ -112,14 +102,10 @@ order by date desc {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} - -{NOTE: } - - **Project results**: - --- +#### Project results: + * Instead of returning the entire index entry object for each result item, you can return only partial fields. @@ -138,7 +124,6 @@ select distinct employeeID {CODE-TAB-BLOCK/} {CODE-TABS/} -{NOTE/} {PANEL/} ## Related articles diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.dotnet.markdown index b90186478d..95f89eab47 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.dotnet.markdown @@ -42,7 +42,7 @@ This results in a much more compact time series that still contains useful infor #### Rollup policies: -Rollup time series are created automatically according to rollup policies that can be defined from the Studio or from the client code. +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. * A rollup policy applies to all time series of every document in the given collection. @@ -85,28 +85,20 @@ Because time series entries are limited to 32 values, rollups are limited to the {PANEL: Examples} -{NOTE: } - -#### Create time series policies - ---- +#### Create time series policies: {CODE rollup_and_retention_0@DocumentExtensions\TimeSeries\RollupAndRetention.cs /} -{NOTE/} -{NOTE: } - -#### Retrieve rollup data - --- +#### Retrieve rollup data: + * Retrieving entries from a rollup time series is similar to getting the raw time series data. * Learn more about using `TimeSeriesFor.Get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries). {CODE rollup_and_retention_1@DocumentExtensions\TimeSeries\RollupAndRetention.cs /} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.js.markdown index a6288f8ed2..445dcd10b9 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.js.markdown @@ -42,7 +42,7 @@ This results in a much more compact time series that still contains useful infor #### Rollup policies: -Rollup time series are created automatically according to rollup policies that can be defined from the Studio or from the client code. +Rollup time series are created automatically according to rollup policies that can be defined from the tudio or client code. * A rollup policy applies to all time series of every document in the given collection. @@ -85,28 +85,20 @@ Because time series entries are limited to 32 values, rollups are limited to the {PANEL: Examples} -{NOTE: } - -#### Create time series policies - ---- +#### Create time series policies: {CODE:nodejs rollup_1@documentExtensions\timeSeries\rollupAndRetention.js /} -{NOTE/} -{NOTE: } - -#### Retrieve rollup data - --- +#### Retrieve rollup data: + * Retrieving entries from a rollup time series is similar to getting the raw time series data. * Learn more about using `timeSeriesFor.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries). {CODE:nodejs rollup_2@documentExtensions\timeSeries\rollupAndRetention.js /} -{NOTE/} {PANEL/} {PANEL: Syntax} diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown new file mode 100644 index 0000000000..b22fd14d3e --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown @@ -0,0 +1,135 @@ +# Time Series Rollups and Retention +--- + +{NOTE: } + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you manage your data in two ways: + +* Creating **Rollups**: + Summarizing time series data by aggregating it into the form of a new, lower-resolution time series. + +* Limiting **Retention**: + Controlling the duration for which time series data is kept before deletion. + +* In this page: + * [Time series policies](../../document-extensions/timeseries/rollup-and-retention#time-series-policies) + * [Examples](../../document-extensions/timeseries/rollup-and-retention#examples) + * [Create time series policy](../../document-extensions/timeseries/rollup-and-retention#create-time-series-policies) + * [Retrieve rollup data](../../document-extensions/timeseries/rollup-and-retention#retrieve-rollup-data) + * [Syntax](../../document-extensions/timeseries/rollup-and-retention#syntax) + +{NOTE/} + +--- + +{PANEL: Time series policies} + +#### What are rollups? + +A rollup is a time series that summarizes the data from another time series, +with each rollup entry representing a specific time frame in the original time series. +Each rollup entry contains 6 values that aggregate the data from all the entries in the original time frame: + +* `First` - the value of the first entry in the frame. +* `Last` - the value of the last entry. +* `Min` - the smallest value. +* `Max` - the largest value. +* `Sum` - the sum of all the values in the frame. +* `Count` - the total number of entries in the frame. + +This results in a much more compact time series that still contains useful information about the original time series (also called "raw" time series). + +#### Rollup policies: + +Rollup time series are created automatically according to rollup policies that can be defined from Studio or client code. + +* A rollup policy applies to all time series of every document in the given collection. + +* Each collection can be configured to have multiple policies which are applied sequentially: + * The raw time series is first rolled up using the policy with the shortest aggregation frame. + * Subsequently, the resulting rollup time series is further aggregated using the policy with the next shortest aggregation frame, + and so on. + +[Querying with group-by](../../document-extensions/timeseries/querying/aggregation-and-projections) +will transparently traverse over the rollups to retrieve the relevant results. + +Let's look at an example of rollup data: + +!["Rollup time series entries"](images/rollup-1.png "A rollup time series' entries") + +**1) Name:** +The name of a rollup time series has this format: `@` +It is a combination of the name of the raw time series and the name of the time series policy separated by `@`. +In the image above these are "HeartRates" and "byHour" respectively. +For this reason, neither a time series name nor a policy name can have the character `@` in it. + +**2) Timestamp:** +The aggregation frame always begins at a round number of one of these time units: a second, minute, hour, day, week, month, or year. +So the frame includes all entries starting at a round number of time units, and ending at a round number *minus one millisecond* +(since milliseconds are the minimal resolution in RavenDB time series). +The timestamp for a rollup entry is the beginning of the frame it represents. + +For example, if the aggregation frame is three days, a frame will start and end at a time stamps like: +`2020-01-01 00:00:00` - `2020-01-03 23:59:59.999`. + +**3) Values:** +Each group of six values represents one value from the original entries. +If the raw time series has `n` values per entry, the rollup time series will have `6 * n` per entry: +the first six summarize the first raw value, the next six summarize the next raw value, and so on. +The aggregated values have the names: `"First ()", "Last ()", ...` respectively. + +Because time series entries are limited to 32 values, rollups are limited to the first five values of an original time series entry, or 30 aggregate values. + +{PANEL/} + +{PANEL: Examples} + +#### Create time series policies: + +{CODE:python rollup_and_retention_0@DocumentExtensions\TimeSeries\RollupAndRetention.py /} + +--- + +#### Retrieve rollup data: + +* Retrieving entries from a rollup time series is similar to getting the raw time series data. + +* Learn more about using `time_series_for.get` in [Get time series entries](../../document-extensions/timeseries/client-api/session/get/get-entries). + +{CODE:python rollup_and_retention_1@DocumentExtensions\TimeSeries\RollupAndRetention.py /} + +{PANEL/} + +{PANEL: Syntax} + +* `raw_policy` + * Used to define the retention time of the raw time series. + * Only one such policy per collection can be defined. + * Does not perform aggregation. + +* Rollup policy: + * Used to define the aggregation time frame and retention time for the rollup time series. + * Multiple policies can be defined per collection. + +* `TimeValue` methods: + `of_seconds(int seconds)` + `of_minutes(int minutes)` + `of_hours(int hours)` + `of_days(int days)` + `of_months(int months)` + `of_years(int years)` + +{PANEL/} + +## Related articles +###Studio +- [Time Series Interface in Studio](../../studio/database/document-extensions/time-series) + +###Time Series +- [Time Series Overview](../../document-extensions/timeseries/overview) +- [API Overview](../../document-extensions/timeseries/client-api/overview) + +###Client-API +- [What Are Operations?](../../client-api/operations/what-are-operations) + diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/RollupAndRetention.py b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/RollupAndRetention.py new file mode 100644 index 0000000000..7055e2ac18 --- /dev/null +++ b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/RollupAndRetention.py @@ -0,0 +1,63 @@ +from datetime import datetime + +from ravendb.documents.operations.time_series import ( + RawTimeSeriesPolicy, + TimeSeriesPolicy, + TimeSeriesCollectionConfiguration, + TimeSeriesConfiguration, + ConfigureTimeSeriesOperation, +) +from ravendb.primitives.time_series import TimeValue + +from examples_base import ExampleBase + + +class RollupAndRetention(ExampleBase): + def setUp(self): + super().setUp() + + def test_rollup_and_retention(self): + with self.embedded_server.get_document_store("RollupAndRetention") as store: + with store.open_session() as session: + # region rollup_and_retention_0 + # Policy for the original ("raw") time-series, + # to keep the data for one week + one_week = TimeValue.of_days(7) + raw_retention = RawTimeSeriesPolicy(one_week) + + # Roll-up the data for each day, + # and keep the results for one year + one_day = TimeValue.of_days(1) + one_year = TimeValue.of_years(1) + daily_rollup = TimeSeriesPolicy("DailyRollupForOneYear", one_day, one_year) + + # Enter the above policies into a + # time-series collection configuration + # for the collection 'Sales' + sales_ts_config = TimeSeriesCollectionConfiguration(policies=[daily_rollup], raw_policy=raw_retention) + + # Enter the configuration for the Sales collection + # into a time-series configuration for the whole database + database_ts_config = TimeSeriesConfiguration() + database_ts_config.collections["Sales"] = sales_ts_config + + # Send the time-series configuration to the server + store.maintenance.send(ConfigureTimeSeriesOperation(database_ts_config)) + # endregion + + # region rollup_and_retention_1 + # Create local instance of the time-series "rawSales" + # in the document "sales/1" + raw_ts = session.time_series_for("sales/1", "rawSales") + + # Create local instance of the rollup time-series - first method: + daily_rollup_TS = session.time_series_for("sales/1", "rawSales@DailyRollupForOneYear") + + # Create local instance of the rollup time-series - second method: + # using the rollup policy itself and the raw time-series' name + rollup_time_series_2 = session.time_series_for("sales/1", daily_rollup.get_time_series_name("rawSales")) + + # Retrieve all the data from both time-series + raw_data = raw_ts.get(datetime.min, datetime.max) + rollup_data = daily_rollup_TS.get(datetime.min, datetime.max) + # endregion diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/TimeSeriesTests.py b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/TimeSeriesTests.py new file mode 100644 index 0000000000..9c582877ed --- /dev/null +++ b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/TimeSeriesTests.py @@ -0,0 +1,1414 @@ +import abc +import math +import random +from datetime import datetime, timedelta +from typing import Dict, Tuple, Optional, List, TypeVar, Union, Callable, Type, Any + +from ravendb import ( + PatchCommandData, + PatchRequest, + PatchOperation, + PatchByQueryOperation, + IndexQuery, + IncludeBuilderBase, + IncludeBuilder, + RawDocumentQuery, + CommandData, + PatchResult, + QueryOperationOptions, + DocumentQuery, +) +from ravendb.documents.indexes.time_series import AbstractTimeSeriesIndexCreationTask +from ravendb.documents.operations.definitions import VoidOperation, IOperation, OperationIdResult +from ravendb.documents.operations.time_series import ( + GetTimeSeriesOperation, + GetMultipleTimeSeriesOperation, + TimeSeriesOperation, + TimeSeriesBatchOperation, + TimeSeriesRangeResult, + TimeSeriesDetails, + ConfigureTimeSeriesValueNamesOperation, +) +from ravendb.documents.queries.index_query import Parameters +from ravendb.documents.queries.time_series import TimeSeriesAggregationResult, TimeSeriesRawResult +from ravendb.documents.session.loaders.include import TimeSeriesIncludeBuilder +from ravendb.documents.session.time_series import ( + ITimeSeriesValuesBindable, + TimeSeriesRange, + TimeSeriesEntry, + TypedTimeSeriesEntry, + AbstractTimeSeriesRange, +) +from ravendb.primitives.constants import int_max + +from examples_base import ExampleBase, User, Company, Address, Employee + +_T_TS_Values_Bindable = TypeVar("_T_TS_Values_Bindable") +_T = TypeVar("_T") +_T_Collection = TypeVar("_T_Collection") + + +class TimeSeries(ExampleBase): + def setUp(self): + super().setUp() + + def test_time_series_testing(self): + with self.embedded_server.get_document_store("TimeSeriesTesting") as store: + base_line = datetime.utcnow() + + # Open a session + with store.open_session() as session: + # Use the session to create a document + session.store(User(name="John"), "users/john") + + # Create an instance of TimeSeriesFor + # Pass an explicit document ID to the TimeSeriesFor constructor + # Append a HeartRate of 70 at the first-minute timestamp + session.time_series_for("users/john", "HeartRates").append_single( + base_line + timedelta(minutes=1), 70.0, "watches/fitbit" + ) + session.save_changes() + + # Get time series names + # region timeseries_region_Retrieve-TimeSeries-Names + # Open a session + with store.open_session() as session: + # Load a document entity to the session + user = session.load("users/john") + + # Call GetTimeSeriesFor, pass the entity + ts_names = session.advanced.get_time_series_for(user) + + # Results will include the names of all time series associated with document 'users/john' + # endregion + + with store.open_session() as session: + # Use the session to load a document + user = session.load("users/john") + + # Pass the document object returned from session.load as a param + # Retrieve a single value from the "HeartRates" time series + val = session.time_series_for_entity(user, "HeartRates").get(datetime.min, datetime.max) + + # region timeseries_region_Delete-TimeSeriesFor-Single-Time-Point + # Delete a single entry + with store.open_session() as session: + session.time_series_for("users/john", "HeartRates").delete(base_line + timedelta(minutes=1)) + session.save_changes() + # endregion + + store.time_series.register_type(User, HeartRate) + store.time_series.register_type(User, StockPrice) + # region timeseries_region_Named-Values-Register + store.time_series.register_type(User, RoutePoint) + # endregion + + with store.open_session() as session: + # region timeseries_region_Append-Named-Values-1 + # Append coordinates + session.typed_time_series_for(RoutePoint, "users/john").append_single( + base_line + timedelta(hours=1), RoutePoint(40.712776, -74.005974), "devices/Navigator" + ) + # endregion + + session.typed_time_series_for(RoutePoint, "users/john").append_single( + base_line + timedelta(hours=2), + RoutePoint(latitude=40.712781, longitude=-74.005979), + "devices/Navigator", + ) + session.typed_time_series_for(RoutePoint, "users/john").append_single( + base_line + timedelta(hours=3), + RoutePoint(latitude=40.712789, longitude=-74.005979), + "devices/Navigator", + ) + session.typed_time_series_for(RoutePoint, "users/john").append_single( + base_line + timedelta(hours=4), + RoutePoint(latitude=40.712792, longitude=-74.005979), + "devices/Navigator", + ) + session.save_changes() + + # Get entries + with store.open_session() as session: + # Use the session to load a document + user = session.load("users/john") + + # Pass the document object returned from session.Load as a param + # Retrieve a single value from the "HeartRates" time series + results = session.typed_time_series_for(RoutePoint, "users/john").get() + + # append entries + with store.open_session() as session: + session.store(User(name="John"), key="users/john") + + # Append a HeartRate entry + session.time_series_for("users/john", "HeartRates").append_single( + base_line + timedelta(minutes=1), 70.0, "watches/fitbit" + ) + + session.save_changes() + + # append entries using a registered time series type + with store.open_session() as session: + session.store(User(name="John"), "users/john") + + session.typed_time_series_for(HeartRate, "users/john").append_single( + base_line, HeartRate(80), "watches/anotherFirm" + ) + session.save_changes() + + # append multi-value entries by name + # region timeseries_region_Append-Named-Values-2 + with store.open_session() as session: + session.store(User(name="John"), "users/john") + + session.typed_time_series_for(StockPrice, "users/john").append_single( + base_line + timedelta(days=1), StockPrice(52, 54, 63.5, 51.4, 9824), "companies/kitchenAppliances" + ) + + session.typed_time_series_for(StockPrice, "users/john").append_single( + base_line + timedelta(days=2), StockPrice(54, 55, 61.5, 49.4, 8400), "companies/kitchenAppliances" + ) + + session.typed_time_series_for(StockPrice, "users/john").append_single( + base_line + timedelta(days=3), StockPrice(55, 57, 65.5, 50, 9020), "companies/kitchenAppliances" + ) + + session.save_changes() + # endregion + + # region timeseries_region_Append-Unnamed-Values-2 + with store.open_session() as session: + session.store(User(name="John"), "users/john") + + session.time_series_for("users/john", "StockPrices").append( + base_line + timedelta(days=1), [52, 54, 63.5, 51.4, 9824], "companies/kitchenAppliances" + ) + + session.time_series_for("users/john", "StockPrices").append( + base_line + timedelta(days=2), [54, 55, 61.5, 49.4, 8400], "companies/kitchenAppliances" + ) + + session.time_series_for("users/john", "StockPrices").append( + base_line + timedelta(days=3), [55, 57, 65.5, 50, 9020], "companies/kitchenAppliances" + ) + + session.save_changes() + # endregion + + # append multi-value entries using a registered time series type + with store.open_session() as session: + session.store( + Company(name="kitchenAppliances", address=Address(city="New York")), "companies/kitchenAppliances" + ) + + session.typed_time_series_for(StockPrice, "companies/kitchenAppliances").append( + base_line + timedelta(days=1), [52, 54, 63.5, 51.4, 9824], "companies/kitchenAppliances" + ) + session.typed_time_series_for(StockPrice, "companies/kitchenAppliances").append( + base_line + timedelta(days=2), [54, 55, 61.5, 49.4, 7400], "companies/kitchenAppliances" + ) + session.typed_time_series_for(StockPrice, "companies/kitchenAppliances").append( + base_line + timedelta(days=3), [55, 57, 65.5, 50, 9020], "companies/kitchenAppliances" + ) + + session.save_changes() + + # get entries + with store.open_session() as session: + # Use the session to load a document + user = session.load("users/john") + + # Pass the document object returned from session.Load as a param + # Retrieve a single value from the "HeartRates" time series + val = session.time_series_for_entity(user, "HeartRates").get(datetime.min, datetime.max) + + # region timeseries_region_Get-NO-Names-Values + # Use Get without a named type + # Is the stock's closing-price rising? + going_up = False + + with store.open_session() as session: + val = session.time_series_for("users/john", "StockPrices").get() + + close_price_day_1 = val[0].values[1] + close_price_day_2 = val[1].values[1] + close_price_day_3 = val[2].values[1] + + if close_price_day_2 > close_price_day_1 and close_price_day_3 > close_price_day_2: + going_up = True + # endregion + + # region timeseries_region_Get-Named-Values + going_up = False + + # Use Get with a Named type + with store.open_session() as session: + val = session.typed_time_series_for(StockPrice, "users/john").get() + + close_price_day_1 = val[0].value.close + close_price_day_2 = val[1].value.close + close_price_day_3 = val[2].value.close + if close_price_day_2 > close_price_day_1 and close_price_day_3 > close_price_day_2: + going_up = True + # endregion + + # remove entries using a registered time series type + with store.open_session() as session: + session.time_series_for("users/john", "HeartRates").delete( + base_line + timedelta(days=1), base_line + timedelta(days=2) + ) + session.save_changes() + + # query + # Query for a document with the Name property "John" and append it a time point + with store.open_session() as session: + query = session.query(object_type=User).where_equals("Name", "John") + + result = list(query) + + session.time_series_for_entity(result[0], "HeartRates").append_single( + base_line + timedelta(minutes=1), 72, "watches/fitbit" + ) + + session.save_changes() + + # region timeseries_region_Pass-TimeSeriesFor-Get-Query-Results + # Query for a document with the Name property "John" + # and get its HeartRates time-series values + with store.open_session() as session: + base_line = datetime.utcnow() + + query = session.query(object_type=User).where_equals("Name", "John") + + result = list(query) + + doc_id = session.advanced.get_document_id(result[0]) + + val = session.time_series_for(doc_id, "HeartRates").get(datetime.min, datetime.max) + + session.save_changes() + # endregion + + # Query for a document with the Name property "John" and append it a time point + with store.open_session() as session: + base_line = datetime.utcnow() + query = session.query(object_type=User).where_equals("Name", "John") + result = list(query) + document_id = session.advanced.get_document_id(result[0]) + for cnt in range(10): + session.time_series_for(document_id, "HeartRates").append_single( + base_line + timedelta(minutes=cnt), 72, "watches/fitbit" + ) + + session.save_changes() + + # region timeseries_region_Load-Document-And-Include-TimeSeries + with store.open_session() as session: + base_line = datetime.utcnow() + + # Load a document + user = session.load( + "users/john", + User, + lambda include_builder: + # Call 'include_time_series' to include time series entries, pass: + # * The time series name + # * Start and end timestamps indicating the range of entries to include + include_builder.include_time_series( + "HeartRates", base_line + timedelta(minutes=3), base_line + timedelta(minutes=8) + ), + ) + + # The following call to 'get' will not trigger a server request, + # the entries will be retrieved from the session's cache. + entries = session.time_series_for("users/john", "HeartRates").get() + # endregion + + # region timeseries_region_Query-Document-And-Include-TimeSeries + with store.open_session() as session: + # Query for a document and include a whole time-series + user = ( + session.query(object_type=User) + .where_equals("Name", "John") + .include( + lambda builder: builder + # Call 'IncludeTimeSeries' to include time series entries, pass: + # * The time series name + # * Start and end timestamps indicating the range of entries to include + .include_time_series( + "HeartRates", base_line + timedelta(minutes=3), base_line + timedelta(minutes=8) + ) + ) + ) + # endregion + + # region timeseries_region_Raw-Query-Document-And-Include-TimeSeries + with store.open_session() as session: + base_time = datetime.utcnow() + from_time = base_time + to_time = base_time + timedelta(minutes=5) + + # Define the Raw Query: + query = ( + session.advanced.raw_query("from Users include timeseries('HeartRates', $from, $to)", User) + .add_parameter("from", from_time) + .add_parameter("to", to_time) + ) + + # Execute the query: + # For each document in the query results, + # the time series entries will be 'loaded' to the session along with the document + users = list(query) + + # The following call to 'Get' will Not trigger a server request, + # the entries will be retrieved from the session's cache. + entries = session.time_series_for_entity(users[0], "HeartRates").get(from_time, to_time) + # endregion + + # Open a session + with store.open_session() as session: + # Use the session to create a document + session.store(User(name="John"), "users/john") + + session.time_series_for("users/john", "HeartRates").append( + base_line + timedelta(minutes=1), [65.0, 52.0, 72.0], "watches/fitbit" + ) + session.save_changes() + + with store.open_session() as session: + # Use the session to load a document + user = session.load("users/john") + + # Pass the document object returned from session.load as a param + # Retrieve a single value from the "HeartRates" time series + val = session.time_series_for_entity(user, "HeartRates").get(datetime.min, datetime.max) + + # Get time series HeartRates' time points data + with store.open_session() as session: + # region timeseries_region_Get-All-Entries-Using-Document-ID + # Get all time series entries + val = session.time_series_for("users/john", "HeartRates").get(datetime.min, datetime.max) + # endregion + + # Get time series HeartRate's time points data + with store.open_session() as session: + # region IncludeParentAndTaggedDocuments + # Get all time series entries + entries = session.time_series_for("users/john", "HeartRates").get_with_include( + datetime.min, + datetime.max, + lambda builder: builder + # Include documents referred-to by entry tags + .include_tags() + # Include Parent Document + .include_document(), + ) + # endregion + + # region timeseries_region_TimeSeriesFor-Append-TimeSeries-Range + base_line = datetime.utcnow() + + # Append 10 HeartRate values + with store.open_session() as session: + session.store(User(name="John"), "users/john") + + tsf = session.time_series_for("users/john", "HeartRates") + + for i in range(10): + tsf.append_single(base_line + timedelta(seconds=i), 67.0, "watches/fitbit") + + session.save_changes() + + # endregion + + # region timeseries_region_TimeSeriesFor-Delete-Time-Points_Range + # Delete a range of entries from the time series + with store.open_session() as session: + session.time_series_for("users/john", "HeartRates").delete(base_line, base_line + timedelta(seconds=9)) + session.save_changes() + # endregion + + # Use GetTimeSeriesOperation and GetMultipleTimeSeriesOperation + # Create a document + with store.open_session() as session: + employee_1 = Employee(first_name="John") + session.store(employee_1) + + employee_2 = Employee(first_name="Mia") + session.store(employee_2) + + employee_3 = Employee(first_name="Emil") + session.store(employee_3) + + session.save_changes() + + # get employees Id list + with store.open_session() as session: + employee_id_list = [ + session.advanced.get_document_id(employee) for employee in list(session.query(object_type=Employee)) + ] + + # Append each employee a week (168 hours) of random exercise HeartRate values and a week (168 hours) of random rest HeartRate values + base_time = datetime(year=2020, month=5, day=17) + random_values = random.Random() + + with store.open_session() as session: + for emp_id in employee_id_list: + for tse in range(168): + session.time_series_for(emp_id, "ExerciseHeartRate").append_single( + base_time + timedelta(hours=tse), + 68 + round(19 * random_values.uniform(0.0, 3.0)), + "watches/fitbit", + ) + session.time_series_for(emp_id, "Rest").append_single( + base_time + timedelta(hours=tse), + 52 + round(19 * random_values.uniform(0.0, 3.0)), + "watches/fitbit", + ) + + session.save_changes() + + document_id = "employees/1-A" + + # region timeseries_region_Get-Single-Time-Series + # Get all values of a single time-series + single_time_series_details = store.operations.send( + GetTimeSeriesOperation( + document_id, + "HeartRates", + datetime.min, + datetime.max, + ) + ) + # endregion + + # region timeseries_region_Get-Multiple-Time-Series + multiple_time_series_details = store.operations.send( + GetMultipleTimeSeriesOperation( + document_id, + [ + TimeSeriesRange( + "ExerciseHeartRate", base_time + timedelta(hours=1), base_time + timedelta(hours=10) + ), + TimeSeriesRange( + "RestHeartRate", base_time + timedelta(hours=11), base_time + timedelta(hours=20) + ), + ], + ) + ) + # endregion + + # region timeseries_region_Append-Using-TimeSeriesBatchOperation + base_time = datetime.utcnow() + + # Define the Append operations: + # ============================= + append_op_1 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=1), [79.0], "watches/fitbit" + ) + append_op_2 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=2), [82.0], "watches/fitbit" + ) + append_op_3 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=3), [80.0], "watches/fitbit" + ) + append_op_4 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=4), [78.0], "watches/fitbit" + ) + + # Define 'TimeSeriesOperation' and add the Append operations: + # =========================================================== + time_series_op = TimeSeriesOperation(name="HeartRates") + + time_series_op.append(append_op_1) + time_series_op.append(append_op_2) + time_series_op.append(append_op_3) + time_series_op.append(append_op_4) + + # Define 'TimeSeriesBatchOperation' and execute: + # ============================================== + time_series_batch_op = TimeSeriesBatchOperation("users/john", time_series_op) + store.operations.send(time_series_batch_op) + # endregion + + # region timeseries_region_Delete-Range-Using-TimeSeriesBatchOperation + base_time = datetime.utcnow() + + delete_op = TimeSeriesOperation.DeleteOperation( + datetime_from=base_time + timedelta(minutes=2), datetime_to=base_time + timedelta(minutes=3) + ) + + time_series_op = TimeSeriesOperation("HeartRates") + time_series_op.delete(delete_op) + + time_series_batch_op = TimeSeriesBatchOperation("users/john", time_series_op) + + store.operations.send(time_series_batch_op) + # endregion + + # region timeseries_region-Append-and-Delete-TimeSeriesBatchOperation + base_time = datetime.utcnow() + + # Define some Append operations: + append_op_1 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=1), [79.0], "watches/fitbit" + ) + append_op_2 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=2), [82.0], "watches/fitbit" + ) + append_op_3 = TimeSeriesOperation.AppendOperation( + base_time + timedelta(minutes=3), [80.0], "watches/fitbit" + ) + + # Define a Delete operation: + delete_op = TimeSeriesOperation.DeleteOperation( + base_time + timedelta(minutes=2), base_time + timedelta(minutes=3) + ) + + time_series_op = TimeSeriesOperation("HeartRates") + + # Add the Append & Delete operations to the list of actions + # Note: the Delete action will be executed BEFORE all the Append actions + # even though it is added last + + time_series_op.append(append_op_1) + time_series_op.append(append_op_2) + time_series_op.append(append_op_3) + time_series_op.delete(delete_op) + + time_series_batch_op = TimeSeriesBatchOperation("users/john", time_series_op) + + store.operations.send(time_series_batch_op) + + # Results: + # All 3 entries that were appended will exist and are not deleted. + # This is because the Delete action occurs first, before all Append actions. + # endregion + + # Query for document with the Name property "John" and append it a time point + with store.open_session() as session: + query = session.query(object_type=User).where_equals("Name", "John") + result = list(query) + document_id = session.advanced.get_document_id(result[0]) + + # region timeseries_region_Use-BulkInsert-To-Append-2-Entries + # Use BulkInsert to append 2 time-series entries + with store.bulk_insert() as bulk_insert: + with bulk_insert.time_series_for(document_id, "HeartRates") as time_series_bulk_insert: + time_series_bulk_insert.append_single(base_line + timedelta(minutes=2), 61, "watches/fitbit") + time_series_bulk_insert.append_single(base_line + timedelta(minutes=3), 62, "watches/apple-watch") + # endregion + + # region timeseries_region_Use-BulkInsert-To-Append-100-Entries + # Use BulkInsert to append 100 time-series entries + with store.bulk_insert() as bulk_insert: + with bulk_insert.time_series_for(document_id, "HeartRates") as time_series_bulk_insert: + for minute in range(0, 100): + time_series_bulk_insert.append(base_line + timedelta(minutes=minute), [80], "watches/fitbit") + # endregion + + # Query for a document with the Name property "John" and append it a time point + with store.open_session() as session: + query = session.query(object_type=User).where_equals("Name", "John") + result = list(query) + + document_id = session.advanced.get_document_id(result[0]) + + # region BulkInsert-overload-2-Two-HeartRate-Sets + # Use BulkInsert to append 2 sets of time series entries + with store.bulk_insert() as bulk_insert: + exercise_heart_rate = [89.0, 82.0, 85.0] + resting_heart_rate = [59.0, 63.0, 61.0, 64.0, 65.0] + + with bulk_insert.time_series_for(document_id, "HeartRates") as time_series_bulk_insert: + time_series_bulk_insert.append( + base_line + timedelta(minutes=2), exercise_heart_rate, "watches/fitbit" + ) + time_series_bulk_insert.append( + base_line + timedelta(minutes=3), resting_heart_rate, "watches/apple-watch" + ) + # endregion + + values = [59.0, 63.0, 69.0, 64, 65.0] + + # Use BulkInsert to append 100 multi-values time-series entries + with store.bulk_insert() as bulk_insert: + with bulk_insert.time_series_for(document_id, "HeartRates") as time_series_bulk_insert: + for minute in range(100): + time_series_bulk_insert.append(base_line + timedelta(minutes=minute), values, "watches/fitbit") + + # Patch a time-series to a document whose Name property is "John" + with store.open_session() as session: + query = session.query(object_type=User).where_equals("Name", "John") + result = list(query) + document_id = session.advanced.get_document_id(result[0]) + change_vector = session.advanced.get_change_vector_for(result[0]) + values = [59.0] + tag = "watches/fitbit" + timeseries = "HeartRates" + # session.advanced.defer( + # PatchCommandData( + # document_id, + # change_vector, + # PatchRequest( + # ( + # "timeseries(this, $timeseries)" + # ".append(" + # " $timestamp," + # " $values," + # " $tag" + # ");" + # ), # 'tag' should appear last + # { + # "timeseries": timeseries, + # "timestamp": base_line + timedelta(minutes=1), + # "values": values, + # "tag": tag, + # }, + # ), + # None, + # ) + # ) + # + # session.save_changes() + + # region TS_region-Operation_Patch-Append-Single-TS-Entry + base_line = datetime.utcnow() + + store.operations.send( + PatchOperation( + "users/1-A", + None, + PatchRequest( + "timeseries(this, $timeseries).append($timestamp, $values, $tag);", + { + "timeseries": "HeartRates", + "timestamp": base_line + timedelta(minutes=1), + "values": 59.0, + "tag": "watches/fitbit", + }, + ), + ) + ) + # endregion + # Patching: Append and Remove multiple time-series entries + # Using session.Advanced.Defer + with store.open_session() as session: + # region TS_region-Session_Patch-Append-100-Random-TS-Entries + base_line = datetime.utcnow() + + # Create arrays of timestamps and random values to patch + values = [] + time_stamps = [] + + for i in range(100): + values.append(68 + round(19 * random.uniform(0.0, 1.0))) + time_stamps.append(base_line + timedelta(seconds=i)) + + session.advanced.defer( + PatchCommandData( + "users/1-A", + None, + PatchRequest( + script=( + "var i = 0;" + "for(i = 0; i < $values.length; i++)" + "{" + " timeseries(id(this), $timeseries)" + " .append (" + " new Date($time_stamps[i])," + " $values[i]," + " $tag);" + "}" + ), + values={ + "timeseries": "HeartRates", + "time_stamps": time_stamps, + "values": values, + "tag": "watches/fitbit", + }, + ), + None, + ) + ) + + session.save_changes() + # endregion + + # region TS_region-Session_Patch-Delete-50-TS-Entries + # Delete time-series entries + session.advanced.defer( + PatchCommandData( + "users/1-A", + None, + PatchRequest( + script=("timeseries(this, $timeseries)" ".delete(" " $from," " $to" ");"), + values={ + "timeseries": "HeartRates", + "from": base_line, + "to": base_line + timedelta(seconds=49), + }, + ), + None, + ) + ) + # endregion + # region TS_region-Session_Patch-Append-TS-Entries + + session.advanced.defer( + PatchCommandData( + "users/1-A", + None, + PatchRequest( + ( + "var i = 0;" + "for(i = 0; i < $values.length; i++)" + "{" + " timeseries(id(this), $timeseries)" + " .append (" + " new Date($time_stamps[i])," + " $values[i]," + " $tag);" + "}" + ), + { + "timeseries": "HeartRates", + "time_stamps": time_stamps, + "values": values, + "tag": "watches/fitbit", + }, + ), + None, + ) + ) + + session.save_changes() + # endregion + + # Patch a document 100 time-series entries + with store.open_session() as session: + # region TS_region-Operation_patch-Append-100-TS-Entries + base_line = datetime.utcnow() + + # Create arrays of timestamps and random values to patch + values = [] + time_stamps = [] + + for cnt in range(100): + values.append(68 + round(19 * random.uniform(0.0, 1.0))) + time_stamps.append(base_line + timedelta(seconds=cnt)) + + store.operations.send( + PatchOperation( + "users/1-A", + None, + PatchRequest( + "var i = 0;" + "for (i = 0; i < $values.length; i++)" + "{timeseries(id(this), $timeseries)" + ".append (" + " new Date($time_stamps[i])," + " $values[i]," + " $tag);" + "}", + { + "timeseries": "HeartRates", + "time_stamps": time_stamps, + "values": values, + "tag": "watches/fitbit", + }, + ), + ) + ) + # endregion + + # Query for a document with the Name property "John" and append it a time point + with store.open_session() as session: + query = session.query(object_type=User).where_equals("Name", "John") + result = list(query) + + for cnt in range(120): + document_id = session.advanced.get_document_id(result[0]) + session.time_series_for(document_id, "HeartRates").append_single( + base_line + timedelta(days=cnt), 72.0, "watches/fitbit" + ) + + session.save_changes() + + # todo reeb: skipped the region here (ts_region_LINQ-6-Aggregation) because I lack .Select() and ts aggregations like this + + # Raw Query + with store.open_session() as session: + base_line = datetime.utcnow() + + start = base_line + end = base_line + timedelta(hours=1) + + query = ( + session.advanced.raw_query( + object_type=User, query="from Users include timeseries('HeartRates', $start, $end)" + ) + .add_parameter("start", start) + .add_parameter("end", end) + ) + + # Raw Query with aggregation + aggregated_raw_query = session.advanced.raw_query( + object_type=TimeSeriesAggregationResult, + query="from Users as u where Age < 30 " + "select timeseries(" + " from HeartRates between" + " '2020-05-27T00:00:00.0000000Z'" + " and '2020-06-23T00:00.0000000Z'" + " group by '7 days'" + " select min(), max())", + ) + + aggregated_raw_query_result = list(aggregated_raw_query) + + # region ts_region_Raw-RQL-Select-Syntax-Aggregation-and-Projections-StockPrice + aggregated_raw_query = session.advanced.raw_query( + "from Companies as c where c.Address.Country = 'USA' " + "select timeseries (" + " from StockPrices" + " where Values[4] > 500000" + " group by '7 day'" + " select max(), min()" + ")", + TimeSeriesAggregationResult, + ) + aggregated_raw_query_result = list(aggregated_raw_query) + # endregion + + # region ts_region_Raw-RQL-Declare-Syntax-Aggregation-and-Projections-StockPrice + aggregated_raw_query = session.advanced.raw_query( + object_type=TimeSeriesAggregationResult, + query=""" + declare timeseries SP(c) { + from c.StockPrices + where Values[4] > 500000 + group by '7 day' + select max(), min() + } + from Companies as c + where c.Address.Country = 'USA' + select c.Name, SP(c) + """, + ) + + aggregated_raw_query_result = list(aggregated_raw_query) + # endregion + # region ts_region_Raw-Query-Non-Aggregated-Declare-Syntax + base_time = datetime(2020, 5, 17, 00, 00, 00) # May 17 2020, 00:00:00 + + # Raw query with no aggregation - Declare syntax + query = ( + session.advanced.raw_query( + object_type=TimeSeriesRawResult, + query=""" + declare timeseries getHeartRates(user) + { + from user.HeartRates + between $start and $end + offset '02:00' + } + from Users as u where Age < 30 + select getHeartRates(u) + """, + ) + .add_parameter("start", base_time) + .add_parameter("end", base_time + timedelta(hours=24)) + ) + + results = list(query) + # endregion + + with store.open_session() as session: + # region ts_region_Raw-Query-Aggregated + base_line = datetime(2020, 5, 17, 00, 00, 00) + + # Raw Query with aggregation + query = ( + session.advanced.raw_query( + object_type=TimeSeriesAggregationResult, + query=""" + from Users as u + select timeseries( + from HeartRates + between $start and $end + group by '1 day' + select min(), max() + offset '03:00') + """, + ) + .add_parameter("start", base_line) + .add_parameter("end", base_line + timedelta(days=7)) + ) + + result = list(query) + # endregion + + with store.open_session() as session: + # region ts_region_LINQ-2-RQL-Equivalent + # Raw query with no aggregation - Select syntax + query = session.advanced.raw_query( + object_type=TimeSeriesRawResult, + query=""" + from Users where Age < 30 + select timeseries ( + from HeartRates + ) + """, + ) + + results = list(query) + # endregion + + # region ts_region_Filter-By-load-Tag-Raw-RQL + non_aggregated_raw_query = session.advanced.raw_query( + object_type=TimeSeriesRawResult, + query=""" + from Companies as c where c.Address.Country = 'USA' + select timeseries( + from StockPrices + load Tag as emp + where emp.Title == 'Sales Representative' + ) + """, + ) + + non_aggregated_raw_query_result = list(non_aggregated_raw_query) + # endregion + + # region TS_DocQuery_1 + # Define the query: + query = ( + session.advanced.document_query(object_type=User) + .select_time_series(HeartRate, lambda builder: builder.raw("from HeartRates")) + .of_type(TimeSeriesRawResult) + ) + + # Execute the query + results = list(query) + # endregion + + with store.open_session() as session: + # region TS_DocQuery_2 + query = ( + session.advanced.document_query(object_type=User) + .select_time_series( + HeartRate, + lambda builder: builder.raw("from HeartRates between $from and $to"), + ) + .add_parameter("from", datetime.utcnow()) + .add_parameter("to", datetime.utcnow() + timedelta(days=1)) + ).of_type(TimeSeriesRawResult) + + results = list(query) + # endregion + + # region TS_region-PatchByQueryOperation-Append-To-Multiple-Docs + query = IndexQuery( + query=""" + from Users as u update + { + timeseries(u, $name).append($time, $values, $tag) + } + """ + ) + query.query_parameters = Parameters( + { + "name": "RestHeartRate", + "time": base_line + timedelta(minutes=1), + "values": [59.0], + "tag": "watches/fitbit1", + } + ) + + append_rest_heart_rate_operation = PatchByQueryOperation(query) + + store.operations.send(append_rest_heart_rate_operation) + # endregion + + # region TS_region-PatchByQueryOperation-Delete-From-Multiple-Docs + # Delete time-series from all users + index_query = IndexQuery("from Users as u update { timeseries(u, $name).delete($from, $to) }") + index_query.query_parameters = Parameters( + {"name": "HeartRates", "from": datetime.min, "to": datetime.max} + ) + delete_operation = PatchByQueryOperation(index_query) + store.operations.send(delete_operation) + # endregion + + session.store(User(name="shaya")) + session.save_changes() + + # region TS_region-PatchByQueryOperation-Get + index_query = IndexQuery( + query=""" + declare function foo(doc){ + var entries = timeseries(doc, $name).get($from, $to); + var differentTags = []; + for (var i = 0; i < entries.length; i++) + { + var e = entries[i]; + if (e.Tag !== null) + { + if (!differentTags.includes(e.Tag)) + { + differentTags.push(e.Tag); + } + } + } + doc.NumberOfUniqueTagsInTS = differentTags.length; + return doc; + } + + from Users as u + update + { + put(id(u), foo(u)) + } + """ + ) + index_query.query_parameters = Parameters( + {"name": "ExerciseHeartRate", "from": datetime.min, "to": datetime.max} + ) + + patch_num_of_unique_tags = PatchByQueryOperation(index_query) + + result = store.operations.send_async(patch_num_of_unique_tags).wait_for_completion() + # endregion + + # De + + +class HeartRate(ITimeSeriesValuesBindable): + def __init__(self, heart_rate_measure: float = None): + self.heart_rate_measure = heart_rate_measure + + def get_time_series_mapping(self) -> Dict[int, Tuple[str, Optional[str]]]: + return {0: ("heart_rate_measure", None)} + + +# region Custom-Data-Type-1 +class StockPrice(ITimeSeriesValuesBindable): + def __init__( + self, + open: float = None, + close: float = None, + high: float = None, + low: float = None, + volume: float = None, + ): + self.open = open + self.close = close + self.high = high + self.low = low + self.volume = volume + + def get_time_series_mapping(self) -> Dict[int, Tuple[str, Optional[str]]]: + return { + 0: ("open", None), # { index : (name, tag), ... } + 1: ("close", None), + 2: ("high", None), + 3: ("low", None), + 4: ("volume", None), + } + + +# endregion + + +# region Custom-Data-Type-2 +class RoutePoint(ITimeSeriesValuesBindable): # Inherit 'ITimeSeriesValuesBindable' + def __init__(self, latitude: float = None, longitude: float = None): + self.latitude = latitude + self.longitude = longitude + + def get_time_series_mapping(self) -> Dict[int, Tuple[str, Optional[str]]]: + return { + 0: ("latitude", None), # { index : (name, tag), ... } + 1: ("longitude", None), + } + + +# endregion + + +# region ts_region_Index-TS-Queries-6-IndexDefinition +class SimpleIndex(AbstractTimeSeriesIndexCreationTask): + class Result: + def __init__(self, heart_beat: float = None, date: datetime = None, user: str = None, tag: str = None): + self.heart_beat = heart_beat + self.date = date + self.user = user + self.tag = tag + + def __init__(self): + super().__init__() + self.map = ( + "from ts in timeSeries.Companies.HeartRate " + "from entry in ts.Entries " + "select new { " + " heart_beat = entry.Values[0]," + " date = entry.Timestamp.Date," + " user = ts.DocumentId," + " tag = entry.Tag" + "}" + ) + + # endregion + + # region DefineCustomFunctions_ModifiedTimeSeriesEntry + class ModifiedTimeSeriesEntry: + def __init__(self, timestamp: datetime = None, value: float = None, tag: str = None): + self.timestamp = timestamp + self.value = value + self.tag = tag + + # endregion + + # region TimeSeriesEntry-Definition + class TimeSeriesEntry: + def __init__(self, timestamp: datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + + @property + def value(self): + if len(self.values) == 1: + return self.values[0] + raise ValueError("Entry has more than one value.") + + @value.setter + def value(self, value: int): + if len(self.values) == 1: + self.values[0] = value + return + raise ValueError("Entry has more than one value") + + # endregion + + class Foo: + # region TimeSeriesFor-Append-definition-double + def append_single(self, timestamp: datetime, value: float, tag: Optional[str] = None) -> None: ... + + # endregion + # region TimeSeriesFor-Append-definition-inum + def append(self, timestamp: datetime, values: List[float], tag: Optional[str] = None) -> None: ... + + # endregion + # region TimeSeriesFor-Delete-definition-single-timepoint + def delete_at(self, at: datetime) -> None: ... + + # endregion + # region TimeSeriesFor-Delete-definition-range-of-timepoints + def delete(self, datetime_from: Optional[datetime] = None, datetime_to: Optional[datetime] = None): ... + + # endregion + # region TimeSeriesFor-Get-definition + def get( + self, + from_date: Optional[datetime] = None, + to_date: Optional[datetime] = None, + start: int = 0, + page_size: int = int_max, + ) -> Optional[List[TimeSeriesEntry]]: ... + + # endregion + + # region TimeSeriesFor-Get-Named-Values + # The strongly-typed API is used, to address time series values by name. + def get( + self, + from_date: Optional[datetime] = None, + to_date: Optional[datetime] = None, + start: int = 0, + page_size: int = int_max, + ) -> Optional[List[TypedTimeSeriesEntry[_T_TS_Values_Bindable]]]: ... + + # endregion + # region TimeSeries-Bindable-Abstract-Class-Definition + class ITimeSeriesValuesBindable(abc.ABC): + @abc.abstractmethod + def get_time_series_mapping(self) -> Dict[int, Tuple[str, Optional[str]]]: + # return a dictionary {index of time series value - (name of 'float' field, label)} + # e.g. return {0 : ('heart', 'Heartrate'), 1: ('bp', 'Blood Pressure')} + # for some class that has 'heart' and 'bp' float fields + raise NotImplementedError() + + # endregion + + # region Load-definition + def load( + self, + key_or_keys: Union[List[str], str], + object_type: Optional[Type[_T]] = None, + includes: Callable[[IncludeBuilder], None] = None, + ) -> Union[Dict[str, _T], _T]: ... + + # endregion + + # region IncludeTimeSeries-definition + def include_time_series( + self, + name: str, + from_date: Optional[datetime] = None, + to_date: Optional[datetime] = None, + alias: Optional[str] = "", + ) -> IncludeBuilderBase: ... + + # endregion + # region RawQuery-Definition + def raw_query(self, query: str, object_type: Optional[Type[_T]] = None) -> RawDocumentQuery[_T]: ... + + # endregion + + # region PatchCommandData-definition + class PatchCommandData(CommandData): + def __init__( + self, + key: str, + change_vector: Union[None, str], + patch: PatchRequest, + patch_if_missing: Optional[PatchRequest] = None, + ): ... + + # endregion + + # region PatchRequest-definition + class PatchRequest: + def __init__(self, script: Optional[str] = "", values: Optional[Dict[str, object]] = None): ... + + # endregion + + # region TimeSeriesBatchOperation-definition + class TimeSeriesBatchOperation(VoidOperation): + def __init__(self, document_id: str, operation: TimeSeriesOperation): ... + + # endregion + + # region GetTimeSeriesOperation-Definition + class GetTimeSeriesOperation(IOperation[TimeSeriesRangeResult]): + def __init__( + self, + doc_id: str, + time_series: str, + from_date: datetime = None, + to_date: datetime = None, + start: int = 0, + page_size: int = int_max, + includes: Optional[Callable[[TimeSeriesIncludeBuilder], None]] = None, + ): ... + + # endregion + + # region TimeSeriesRangeResult-class + class TimeSeriesRangeResult: + def __init__( + self, + from_date: datetime, + to_date: datetime, + entries: List[TimeSeriesEntry], + total_results: int = None, + includes: Optional[Dict[str, Any]] = None, + ): ... + + # endregion + + # region GetMultipleTimeSeriesOperation + class GetMultipleTimeSeriesOperation(IOperation[TimeSeriesDetails]): + def __init__( + self, + doc_id: str, + ranges: List[AbstractTimeSeriesRange], + start: Optional[int] = 0, + page_size: Optional[int] = int_max, + includes: Optional[Callable[[TimeSeriesIncludeBuilder], None]] = None, + ): ... + + # endregion + + # region TimeSeriesRange-class + class TimeSeriesRange(AbstractTimeSeriesRange): + def __init__(self, name: str, from_date: Optional[datetime], to_date: Optional[datetime]): ... + + # endregion + + # region TimeSeriesDetails-class + class TimeSeriesDetails: + def __init__(self, key: str, values: Dict[str, List[TimeSeriesRangeResult]]): ... + + # endregion + + # region PatchOperation-Definition + class PatchOperation(IOperation[PatchResult]): + def __init__( + self, + key: str, + change_vector: str, + patch: PatchRequest, + patch_if_missing: Optional[PatchRequest] = None, + skip_patch_if_change_vector_mismatch: Optional[bool] = None, + ): ... + + # endregion + + # region PatchByQueryOperation-Definition + class PatchByQueryOperation(IOperation[OperationIdResult]): + def __init__( + self, query_to_update: Union[IndexQuery, str], options: Optional[QueryOperationOptions] = None + ): ... + + # endregion + + class TimeSeriesBulkInsert: + # region Append-Operation-Definition-1 + # Each appended entry has a single value. + def append_single(self, timestamp: datetime, value: float, tag: Optional[str] = None) -> None: ... + + # endregion + # region Append-Operation-Definition-2 + # Each appended entry has multiple values. + def append(self, timestamp: datetime, values: List[float], tag: str = None) -> None: ... + + # endregion + + class TimeSeriesOperations: + # region Register-Definition-1 + def register_type( + self, + collection_class: Type[_T_Collection], + ts_bindable_object_type: Type[_T_TS_Values_Bindable], + name: Optional[str] = None, + ): ... + + # endregion + # region Register-Definition-2 + def register(self, collection: str, name: str, value_names: List[str]) -> None: ... + + # endregion + + # region Query-definition + + def document_query( + self, + index_name: str = None, + collection_name: str = None, + object_type: Type[_T] = None, + is_map_reduce: bool = False, + ) -> DocumentQuery[_T]: ... + + # endregion + + # Watch class for TS Document Query documentation + # region TS_DocQuery_class + class Monitor: + def __init__(self, accuracy: float = None): + self.accuracy = accuracy + + # endregion From 3ca685c4492b7a923472bea8172a55ffb5c4809c Mon Sep 17 00:00:00 2001 From: reebhub Date: Mon, 5 Aug 2024 03:57:31 +0300 Subject: [PATCH 2/4] added missing markdown and sample files --- .../timeseries/indexing.dotnet.markdown | 3 - .../timeseries/indexing.python.markdown | 162 ++++++++++++ .../querying/filtering.python.markdown | 118 +++++++++ .../querying/using-indexes.dotnet.markdown | 3 +- .../querying/using-indexes.js.markdown | 3 +- .../querying/using-indexes.python.markdown | 173 ++++++++++++ .../rollup-and-retention.python.markdown | 151 ++++++++++- .../TimeSeries/FilterTimeSeriesQuery.py | 125 +++++++++ .../DocumentExtensions/TimeSeries/Indexing.py | 248 ++++++++++++++++++ .../TimeSeries/Querying/QueryingTsIndex.py | 137 ++++++++++ 10 files changed, 1111 insertions(+), 12 deletions(-) create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.python.markdown create mode 100644 Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown create mode 100644 Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/FilterTimeSeriesQuery.py create mode 100644 Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Indexing.py create mode 100644 Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Querying/QueryingTsIndex.py diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown index 3a63119709..3225ce2a31 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.dotnet.markdown @@ -7,9 +7,6 @@ * Indexing allows for fast retrieval of the indexed time series data when querying a time series. -* The API for creating time series indexes is very similar to (and it inherits from) the API for - [creating document indexes](../../indexes/creating-and-deploying). - * In this page: * [Time series indexes vs Document indexes](../../document-extensions/timeseries/indexing#time-series-indexes-vs-document-indexes) * [Ways to create a time series index](../../document-extensions/timeseries/indexing#ways-to-create-a-time-series-index) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown new file mode 100644 index 0000000000..951c6c055f --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown @@ -0,0 +1,162 @@ +# Indexing Time Series +--- + +{NOTE: } + +* [Static](../../studio/database/indexes/indexes-overview#index-types) time series indexes can be created from your client application or from the Studio. + +* Indexing allows for fast retrieval of the indexed time series data when querying a time series. + +* In this page: + * [Time series indexes vs Document indexes](../../document-extensions/timeseries/indexing#time-series-indexes-vs-document-indexes) + * [Ways to create a time series index](../../document-extensions/timeseries/indexing#ways-to-create-a-time-series-index) + * [Examples of time series indexes](../../document-extensions/timeseries/indexing#examples-of-time-series-indexes) + * [Map index - index single time series from single collection](../../document-extensions/timeseries/indexing#map-index---index-single-time-series-from-single-collection) + * [Multi-Map index - index time series from several collections](../../document-extensions/timeseries/indexing#multi-map-index---index-time-series-from-several-collections) + * [Map-Reduce index](../../document-extensions/timeseries/indexing#map-reduce-index) + +{NOTE/} + +--- + +{PANEL: Time series indexes vs Document indexes} + +#### Auto-Indexes: + +* Time series index: + Dynamic time series indexes are Not created in response to queries. + +* Document index: + [Auto-indexes](../../studio/database/indexes/indexes-overview#indexes-types) are created in response to dynamic queries. + +--- + +#### Data source: + +* Time series index: + + * Time series indexes process [segments](../../document-extensions/timeseries/design#segmentation) that contain time series entries. + The entries are indexed through the segment they are stored in, for example, using a LINQ syntax that resembles this one: + + {CODE-BLOCK:sql} +from segment in timeseries +from entry in segment +... + {CODE-BLOCK/} + + * The following items can be indexed per index-entry in a time series index: + * Values & timestamp of a time series entry + * The entry tag + * Content from a document referenced by the tag + * Properties of the containing segment + +* Document index: + + * The index processes fields from your JSON documents. + Documents are indexed through the collection they belong to, for example, using this LINQ syntax: + + {CODE-BLOCK:sql} +from employee in employees +... + {CODE-BLOCK/} + +--- + +#### Query results: + +* Time series index: + When [querying](../../document-extensions/timeseries/querying/using-indexes) a time series index, each result item corresponds to the type defined by the **index-entry** in the index definition, + (unless results are [projected](../../document-extensions/timeseries/querying/using-indexes#project-results)). The documents themselves are not returned. + +* Document index: + The resulting objects are the document entities (unless results are projected). + +{PANEL/} + +{PANEL: Ways to create a time series index} + +There are two main ways to create a time series index: + +1. Create a class that inherits from one of the following abstract index creation task classes: + * `AbstractTimeSeriesIndexCreationTask` + for [map](../../indexes/map-indexes) and [map-reduce](../../indexes/map-reduce-indexes) time series indexes. + * `AbstractMultiMapTimeSeriesIndexCreationTask` + for [multi-map](../../indexes/multi-map-indexes) time series indexes. + * `AbstractJavaScriptTimeSeriesIndexCreationTask` + for static [javascript indexes](../../indexes/javascript-indexes). + +2. Deploy a time series index definition via [PutIndexesOperation](../../client-api/operations/maintenance/indexes/put-indexes): + * Create a `TimeSeriesIndexDefinition` directly. + * Create a strongly typed index definition using `TimeSeriesIndexDefinitionBuilder`. + +{PANEL/} + +{PANEL: Examples of time series indexes} + +#### Map index - index single time series from single collection: + +* In this index, we index data from the "StockPrices" time series entries in the "Companies" collection (`TradeVolume`, `Date`). + +* In addition, we index the containing document id (`DocumentID`), which is obtained from the segment, + and some content from the document referenced by the entry's Tag (`EmployeeName`). + +* Each tab below presents one of the different [ways](../../document-extensions/timeseries/indexing#ways-to-create-a-time-series-index) the index can be defined. + + {CODE-TABS} +{CODE-TAB:python:Map_index index_1@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TAB:python:JS_index index_3@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TAB:python:IndexDefinition index_definition_1@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TAB:python:IndexDefinition_builder index_definition_2@DocumentExtensions\TimeSeries\Indexing.py /} + {CODE-TABS/} + +* Querying this index, you can retrieve the indexed time series data while filtering by any of the index-fields. + + {CODE-TABS} +{CODE-TAB:python:Query_example_1 query_1@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TAB-BLOCK:sql:RQL_1} +from index "StockPriceTimeSeriesFromCompanyCollection" +where "CompanyID" == "Comapnies/91-A" +{CODE-TAB-BLOCK/} +{CODE-TAB:python:Query_example_2 query_2@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TAB-BLOCK:sql:RQL_2} +from index "StockPriceTimeSeriesFromCompanyCollection" +where "TradeVolume" > 150_000_000 +select distinct CompanyID +{CODE-TAB-BLOCK/} + {CODE-TABS/} + +--- + +#### Multi-Map index - index time series from several collections: + +{CODE-TABS} +{CODE-TAB:python:Multi_Map_index index_6@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TABS/} + +--- + +#### Map-Reduce index: + +{CODE-TABS} +{CODE-TAB:python:Map_Reduce_index index_7@DocumentExtensions\TimeSeries\Indexing.py /} +{CODE-TABS/} + +{PANEL/} + +## Related articles + +### Time Series +[Time Series Overview](../../document-extensions/timeseries/overview) +[API Overview](../../document-extensions/timeseries/client-api/overview) + +### Indexes +[What are Indexes](../../indexes/what-are-indexes) +[Creating and Deploying Indexes](../../indexes/creating-and-deploying) +[Map Indexes](../../indexes/map-indexes) +[Multi-Map Indexes](../../indexes/multi-map-indexes) +[Map-Reduce Indexes](../../indexes/map-reduce-indexes) +[JavaScript Indexes](../../indexes/javascript-indexes) +[Indexing Related Documents](../../indexes/indexing-related-documents) + +### Client-API +[Working with Document IDs](../../client-api/document-identifiers/working-with-document-identifiers) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.python.markdown new file mode 100644 index 0000000000..d4e9477d30 --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.python.markdown @@ -0,0 +1,118 @@ +# Filtering Time Series Queries + +--- + +{NOTE: } + +In addition to limiting time series query results by specifying the [range of entries](../../../document-extensions/timeseries/querying/choosing-query-range) to retrieve, +you can filter the time series entries by their **values**, **tag**, or by the contents of a **document referenced in the tag**. + +* In this page: + * [Filter by value](../../../document-extensions/timeseries/querying/filtering#filter-by-value) + * [Filter by tag](../../../document-extensions/timeseries/querying/filtering#filter-by-tag) + * [Filter by referenced document](../../../document-extensions/timeseries/querying/filtering#filter-by-referenced-document) + +{NOTE/} + +--- + +{PANEL: Filter by value} + +* A time series entry can have up to 32 [values](../../../document-extensions/timeseries/overview#values). + +* A time series query can filter entries based on these values. + +{CODE-TABS} +{CODE-TAB:python:RawQuery filter_entries_3@DocumentExtensions\TimeSeries\FilterTimeSeriesQuery.py /} +{CODE-TAB-BLOCK:sql:RQL} +from Employees +select timeseries ( + from HeartRates + between "2020-05-17T00:00:00.0000000" + and "2020-05-17T00:10:00.0000000" + // Use the "where Value" clause to filter entries by the value + where Value > 75 +) +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Filter by tag} + +* A time series entry can have an optional [tag](../../../document-extensions/timeseries/overview#tags). + +* A time series query can filter entries based on this tag. + +{CODE-TABS} +{CODE-TAB:python:RawQuery filter_entries_6@DocumentExtensions\TimeSeries\FilterTimeSeriesQuery.py /} +{CODE-TAB-BLOCK:sql:RQL} +from Employees +select timeseries ( + from HeartRates + between "2020-05-17T00:00:00.0000000" + and "2020-05-17T00:10:00.0000000" + // Use the "where Tag" clause to filter entries by the tag string content + where Tag == "watches/fitbit" +) +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE-TABS} +{CODE-TAB:python:RawQuery filter_entries_9@DocumentExtensions\TimeSeries\FilterTimeSeriesQuery.py /} +{CODE-TAB-BLOCK:sql:RQL} +from Employees +select timeseries ( + from HeartRates + between "2020-05-17T00:00:00.0000000" + and "2020-05-17T00:10:00.0000000" + // Use the "where Tag in" clause to filter by various tag options + where Tag in ("watches/apple", "watches/samsung", "watches/xiaomi") +) +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Filter by referenced document} + +* A time series entry's [tag](../../../document-extensions/timeseries/overview#tags) can contain the **ID of a document**. + +* A time series query can filter entries based on the contents of this referenced document. + The referenced document is loaded, and entries are filtered by its properties. + +{CODE-TABS} +{CODE-TAB:python:RawQuery filter_entries_12@DocumentExtensions\TimeSeries\FilterTimeSeriesQuery.py /} +{CODE-TAB-BLOCK:sql:RQL} +from Companies +where Address.Country == "USA" +select timeseries ( + from StockPrices + // Use 'load Tag' to load the employee document referenced in the tag + load Tag as employeeDoc + // Use 'where ' to filter entries by the properties of the loaded document + where employeeDoc.Title == "Sales Manager" +) +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{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** +[Range Selection](../../../document-extensions/timeseries/querying/choosing-query-range) +[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) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown index 689a6b1e8f..7af8868c0e 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.dotnet.markdown @@ -6,7 +6,8 @@ * **Time series index**: - * STATIC-time-series-indexes can be defined from the [Client API](../../../document-extensions/timeseries/indexing) or using the [Studio](../../../studio/database/indexes/create-map-index). + * STATIC-time-series-indexes can be defined from the [Client API](../../../document-extensions/timeseries/indexing) + or using [Studio](../../../studio/database/indexes/create-map-index). Such an index can be queried in the same way as a regular index that indexes documents. (See [Querying an index](../../../indexes/querying/query-index)). diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown index 1f27972297..56cb419ed9 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.js.markdown @@ -6,7 +6,8 @@ * **Time series index**: - * STATIC-time-series-indexes can be defined from the [Client API](../../../document-extensions/timeseries/indexing) or using the [Studio](../../../studio/database/indexes/create-map-index). + * STATIC-time-series-indexes can be defined from the [Client API](../../../document-extensions/timeseries/indexing) + or using [Studio](../../../studio/database/indexes/create-map-index). Such an index can be queried in the same way as a regular index that indexes documents. (See [Querying an index](../../../indexes/querying/query-index)). diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown new file mode 100644 index 0000000000..ed19f83e9b --- /dev/null +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown @@ -0,0 +1,173 @@ +# Querying Time Series Indexes + +--- + +{NOTE: } + +* **Time series index**: + + * STATIC-time-series-indexes can be defined from the [Client API](../../../document-extensions/timeseries/indexing) + or using [Studio](../../../studio/database/indexes/create-map-index). + Such an index can be queried in the same way as a regular index that indexes documents. + (See [Querying an index](../../../indexes/querying/query-index)). + + * AUTO-time-series-indexes are Not generated automatically by the server when making a time series query. + +* **The contents of the query results**: + + * Unlike a document index, where the source data are your JSON documents, + the source data for a time series index are the time series entries within the documents. + + * When querying a **document index**: + the resulting objects are the document entities (unless results are projected). + + * When querying a **time series index**: + each item in the results is of the type defined by the **index-entry** in the index definition, + (unless results are projected). + The documents themselves are not returned. + +* In this page: + * [Sample index](../../../document-extensions/timeseries/querying/using-indexes#sample-index) + * [Querying the index](../../../document-extensions/timeseries/querying/using-indexes#querying-the-index) + * [Query all time series entries](../../../document-extensions/timeseries/querying/using-indexes#query-all-time-series-entries) + * [Filter query results](../../../document-extensions/timeseries/querying/using-indexes#filter-query-results) + * [Order query results](../../../document-extensions/timeseries/querying/using-indexes#order-query-results) + * [Project results](../../../document-extensions/timeseries/querying/using-indexes#project-results) + * [Syntax](../../../document-extensions/timeseries/querying/using-indexes#syntax) + +{NOTE/} + +--- + +{PANEL: Sample Index} + +* The following is a time series map-index that will be used in the query examples throughout this article. + +* Each **index-entry** consists of: + * Three index-fields obtained from the "HeartRates" time series entries: `BPM`, `Date`, and `Tag`. + * One index-field obtained from the time series [segment](../../../document-extensions/timeseries/indexing#timeseriessegment-object) header: `EmployeeID`. + * One index-field obtained from the loaded employee document: `EmployeeName`. + +* When querying this time series index: + * The resulting items correspond to the time series entries that match the query predicate. + * Each item in the results will be of type `TsIndex.IndexEntry`, which is the index-entry. + Different result types may be returned when the query [projects the results](../../../document-extensions/timeseries/querying/using-indexes#project-results). + +{CODE:python sample_ts_index@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} + +{PANEL/} + +{PANEL: Querying the index} + +#### Query all time series entries: + +No filtering is applied in this query. +Results will include ALL entries from time series "HeartRates". + +{CODE-TABS} +{CODE-TAB:python:Query query_index_1@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB:python:RawQuery query_index_4@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB-BLOCK:sql:RQL} +from index "TsIndex" +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +--- + +#### Filter query results: + +In this example, time series entries are filtered by the query. +The query predicate is applied to the index-fields. + +{CODE-TABS} +{CODE-TAB:python:Query query_index_5@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB:python:RawQuery query_index_8@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB-BLOCK:sql:RQL} +from index "TsIndex" +where EmployeeName == "Robert King" and BPM > 85.0 +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +--- + +#### Order query results: + +Results can be ordered by any of the index-fields. + +{CODE-TABS} +{CODE-TAB:python:Query query_index_9@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB:python:RawQuery query_index_12@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB-BLOCK:sql:RQL} +from index "TsIndex" +where BPM < 58.0 +order by Date desc +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +--- + +#### Project results: + +* Instead of returning the entire `TsIndex.IndexEntry` object for each result item, + you can return only partial fields. + +* In this example, we query for time series entries with a very high BPM value. + We retrieve entries with BPM value > 100 but return only the _EmployeeID_ for each entry. + +{CODE-TABS} +{CODE-TAB:python:Query query_index_13@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB:python:Projection_class employee_details_class@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB:python:RawQuery query_index_16@DocumentExtensions\TimeSeries\Querying\QueryingTsIndex.py /} +{CODE-TAB-BLOCK:sql:RQL} +from index "TsIndex" +where BPM > 100.0 +select distinct EmployeeID +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +* [query](../../../client-api/session/querying/how-to-query#query-overview) + + {CODE-BLOCK: JSON} + def query( + self, source: Optional[Query] = None, object_type: Optional[Type[_T]] = None + ) -> DocumentQuery[_T]: + ... + {CODE-BLOCK/} + +* [document_query](../../../client-api/session/querying/how-to-query#query-overview) + + {CODE-BLOCK: JSON} + def document_query( + self, + index_name: str = None, + collection_name: str = None, + object_type: Type[_T] = None, + is_map_reduce: bool = False, + ) -> DocumentQuery[_T]: + ... + {CODE-BLOCK/} + +{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** +[Range Selection](../../../document-extensions/timeseries/querying/choosing-query-range) +[Filtering](../../../document-extensions/timeseries/querying/filtering) +[Aggregation and Projection](../../../document-extensions/timeseries/querying/aggregation-and-projections) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown index b22fd14d3e..5b540a5f99 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown @@ -103,6 +103,8 @@ Because time series entries are limited to 32 values, rollups are limited to the {PANEL: Syntax} +### The time series policies + * `raw_policy` * Used to define the retention time of the raw time series. * Only one such policy per collection can be defined. @@ -112,13 +114,148 @@ Because time series entries are limited to 32 values, rollups are limited to the * Used to define the aggregation time frame and retention time for the rollup time series. * Multiple policies can be defined per collection. -* `TimeValue` methods: - `of_seconds(int seconds)` - `of_minutes(int minutes)` - `of_hours(int hours)` - `of_days(int days)` - `of_months(int months)` - `of_years(int years)` +{CODE-BLOCK: python} +class RawTimeSeriesPolicy(TimeSeriesPolicy): + def __init__(self, retention_time: TimeValue = TimeValue.MAX_VALUE()): + ... + +class TimeSeriesPolicy: + def __init__( + self, + name: Optional[str] = None, + aggregation_time: Optional[TimeValue] = None, + retention_time: TimeValue = TimeValue.MAX_VALUE(), + ): + ... +{CODE-BLOCK/} + +| Property | Type | Description | +|----------------------|------|-------------| +| **name** (Optional) | `str` | This string is used to create the name of the rollup time series.
`name` is added to the raw time series name - with `@` as a separator,
e.g.: `@` | +| **retention_time** | `TimeValue` | Time series entries older than this time value (see `TimeValue` below) are automatically deleted. | +| **aggregation_time** (Optional) | `TimeValue` |The time series data being rolled up is divided into parts of this length of time, rounded to nearest time units. Each part is aggregated into an entry of the rollup time series. | + +{CODE-BLOCK: python} +class TimeValue: + def __init__(self, value: int, unit: TimeValueUnit): + self.value = value + self.unit = unit + + @classmethod + def of_seconds(cls, seconds: int) -> TimeValue: + return cls(seconds, TimeValueUnit.SECOND) + + @classmethod + def of_minutes(cls, minutes: int) -> TimeValue: + return cls(minutes * 60, TimeValueUnit.SECOND) + + @classmethod + def of_hours(cls, hours: int) -> TimeValue: + return cls(hours * 3600, TimeValueUnit.SECOND) + + @classmethod + def of_days(cls, days: int) -> TimeValue: + return cls(days * cls.SECONDS_PER_DAY, TimeValueUnit.SECOND) + + @classmethod + def of_months(cls, months: int) -> TimeValue: + return cls(months, TimeValueUnit.MONTH) + + @classmethod + def of_years(cls, years: int) -> TimeValue: + return cls(12 * years, TimeValueUnit.MONTH) +{CODE-BLOCK/} + +Each of the above `TimeValue` methods returns a `TimeValue` object representing a whole number of the specified time units. +These methods are used to define the aggregation and retention spans om time series policies. + +--- + +### The time series configuration object + +{CODE-BLOCK: python} +class TimeSeriesConfiguration: + def __init__(self): + self.collections: Dict[str, TimeSeriesCollectionConfiguration] = {} + self.policy_check_frequency: Optional[datetime.timedelta] = None + self.named_values: Optional[Dict[str, Dict[str, List[str]]]] = None + +class TimeSeriesCollectionConfiguration: + def __init__( + self, + disabled: Optional[bool] = False, + policies: Optional[List[TimeSeriesPolicy]] = None, + raw_policy: Optional[RawTimeSeriesPolicy] = RawTimeSeriesPolicy.DEFAULT_POLICY(), + ): + self.disabled = disabled + self.policies = policies + self.raw_policy = raw_policy +{CODE-BLOCK/} + +| Property | Type | Description | +|-----------------|------|-------------| +| **collections** | `Dict` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | +| **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | + +--- + +### The time series configuration operation + +{CODE-BLOCK: python} +class ConfigureTimeSeriesOperation(MaintenanceOperation[ConfigureTimeSeriesOperationResult]) +{CODE-BLOCK/} + +Learn more about operations in: [What are operations](../../client-api/operations/what-are-operations). + +--- + +### Time series entries + +Time series entries are of one of the following classes: + +{CODE-BLOCK: python} +class TimeSeriesEntry: + def __init__( + self, timestamp: datetime.datetime = None, tag: str = None, values: List[int] = None, rollup: bool = None + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.rollup = rollup + +class TypedTimeSeriesEntry(Generic[_T_TSBindable]): + def __init__( + self, + timestamp: datetime.datetime = None, + tag: str = None, + values: List[int] = None, + is_rollup: bool = None, + value: _T_TSBindable = None, + ): + self.timestamp = timestamp + self.tag = tag + self.values = values + self.is_rollup = is_rollup + self.value = value + + +class TypedTimeSeriesRollupEntry(Generic[_T_Values]): + def __init__(self, object_type: Type[_T_Values], timestamp: datetime.datetime): + self._object_type = object_type + self.tag: Optional[str] = None + self.rollup = True + self.timestamp = timestamp + + self._first: Optional[_T_Values] = None + self._last: Optional[_T_Values] = None + self._max: Optional[_T_Values] = None + self._min: Optional[_T_Values] = None + self._sum: Optional[_T_Values] = None + self._count: Optional[_T_Values] = None + self._average: Optional[_T_Values] = None +{CODE-BLOCK/} {PANEL/} diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/FilterTimeSeriesQuery.py b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/FilterTimeSeriesQuery.py new file mode 100644 index 0000000000..0897ce75cc --- /dev/null +++ b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/FilterTimeSeriesQuery.py @@ -0,0 +1,125 @@ +from datetime import datetime, timedelta + +from ravendb.documents.queries.time_series import TimeSeriesRawResult + +from examples_base import ExampleBase, Company, Employee + + +class FilterTimeSeriesQuery(ExampleBase): + def setUp(self): + super().setUp() + + def test_filter(self): + with self.embedded_server.get_document_store("FilterTS") as store: + with store.open_session() as session: + self.add_companies(session) + self.add_employees(session) + + base_time = datetime(2020, 5, 17, 0, 0, 0, 0) + session.time_series_for("employees/1-A", "HeartRates").append_single( + base_time + timedelta(minutes=1), 76.0, "watches/fitbit" + ) + + session.time_series_for("companies/3", "StockPrices").append_single( + base_time + timedelta(minutes=1), 76.0, "employees/stonksguy" + ) + + session.store(Employee(title="Sales Manager"), "employees/stonksguy") + + session.save_changes() + # region filter_entries_3 + # For example, in the "HeartRates" time series, + # retrieve only entries where the value exceeds 75 BPM + base_time = datetime(2020, 5, 17, 0, 0, 0, 0) + from_dt = base_time + to_dt = base_time + timedelta(minutes=10) + + query_string = """ + from Employees + select timeseries ( + from HeartRates + between $from and $to + // Use the 'where Value' clause to filter by the value + where Value > 75 + )""" + + query = ( + session.advanced.raw_query(query_string, TimeSeriesRawResult) + .add_parameter("from", from_dt) + .add_parameter("to", to_dt) + ) + + results = list(query) + # endregion + + # region filter_entries_6 + # Retrieve only entries where the tag string content is "watches/fitbit" + base_time = datetime(2020, 5, 17, 0, 0, 0, 0) + from_dt = base_time + to_dt = base_time + timedelta(minutes=10) + + query_string = """ + from Employees + select timeseries ( + from HeartRates + between $from and $to + // Use the 'where Tag' clause to filter entries by the tag string content + where Tag == 'watches/fitbit' + )""" + + query = ( + session.advanced.raw_query(query_string, TimeSeriesRawResult) + .add_parameter("from", from_dt) + .add_parameter("to", to_dt) + ) + + results = list(query) + # endregion + + # region filter_entries_9 + # retrieve only entries where the tag string content is one of several options + + base_time = datetime(2020, 5, 17, 0, 0, 0, 0) + from_dt = base_time + to_dt = base_time + timedelta(minutes=10) + + optional_tags = ["watches/apple", "watches/samsung", "watches/xiaomi"] + + query_string = """ + from Employees + select timeseries ( + from HeartRates + between $from and $to + // Use the 'where Tag in' clause to filter by various tag options + where Tag in ($optionalTags) + )""" + + query = ( + session.advanced.raw_query(query_string, TimeSeriesRawResult) + .add_parameter("from", from_dt) + .add_parameter("to", to_dt) + .add_parameter("optionalTags", optional_tags) + ) + + results = list(query) + # endregion + + # region filter_entries_12 + # retrieve entries that reference a document that has "Sales Manager" in its 'Title' property + + query_string = """ + from Companies + where Address.Country == 'USA' + select timeseries ( + from StockPrices + // Use 'load Tag' to load the employee document referenced in the tag + load Tag as employeeDoc + // Use 'where ' to filter entries by the properties of the loaded document + where employeeDoc.Title == 'Sales Manager' + )""" + + query = session.advanced.raw_query(query_string, Company) + + results = list(query) + # endregion + pass diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Indexing.py b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Indexing.py new file mode 100644 index 0000000000..646b844bf0 --- /dev/null +++ b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Indexing.py @@ -0,0 +1,248 @@ +from datetime import datetime + +from ravendb import PutIndexesOperation +from ravendb.documents.indexes.time_series import ( + TimeSeriesIndexDefinition, + TimeSeriesIndexDefinitionBuilder, + AbstractTimeSeriesIndexCreationTask, + AbstractMultiMapTimeSeriesIndexCreationTask, + AbstractJavaScriptTimeSeriesIndexCreationTask, +) + +from examples_base import ExampleBase + + +# region index_1 +class StockPriceTimeSeriesFromCompanyCollection(AbstractTimeSeriesIndexCreationTask): + # The index-entry: + # ================ + class IndexEntry: + def __init__( + self, trade_volume: float = None, date: datetime = None, company_id: str = None, employee_name: str = None + ): + # The index-fields: + # ================= + self.trade_volume = trade_volume + self.date = date + self.company_id = company_id + self.employee_name = employee_name + + def __init__(self): + super().__init__() + self.map = """ + from segment in timeSeries.Companies.StockPrices + from entry in segment.Entries + + let employee = LoadDocument(entry.Tag, "Employees") + + select new + { + trade_volume = entry.Values[4], + date = entry.Timestamp.Date, + company_id = segment.DocumentId, + employee_name = employee.FirstName + " " + employee.LastName + } + """ + + +# endregion +# region index_3 +class StockPriceTimeSeriesFromCompanyCollection_JS(AbstractJavaScriptTimeSeriesIndexCreationTask): + def __init__(self): + super().__init__() + self.maps = { + """ + timeSeries.map('Companies', 'StockPrices', function (segment) { + + return segment.Entries.map(entry => { + let employee = load(entry.Tag, 'Employees'); + + return { + trade_volume: entry.Values[4], + date: new Date(entry.Timestamp.getFullYear(), + entry.Timestamp.getMonth(), + entry.Timestamp.getDate()), + company_id: segment.DocumentId, + employee_name: employee.FirstName + ' ' + employee.LastName + }; + }); + }) + """ + } + + +# endregion + +# region index_6 +class Vechicles_ByLocation(AbstractMultiMapTimeSeriesIndexCreationTask): + class IndexEntry: + def __init__( + self, latitude: float = None, longitude: float = None, date: datetime = None, document_id: str = None + ): + self.latitude = latitude + self.longitude = longitude + self.date = date + self.document_id = document_id + + def __init__(self): + super().__init__() + self._add_map( + """ + from segment in timeSeries.Planes.GPS_Coordinates + from entry in segment.Entries + select new + { + latitude = entry.Values[0], + longitude = entry.Values[1], + date = entry.Timestamp.Date, + document_id = segment.DocumentId + } + """ + ) + self._add_map( + """ + from segment in timeSeries.Ships.GPS_Coordinates + from entry in segment.Entries + select new + { + latitude = entry.Values[0], + longitude = entry.Values[1], + date = entry.Timestamp.Date, + document_id = segment.DocumentId + } + """ + ) + + +# endregion + + +# region index_7 +class TradeVolume_PerDay_ByCountry(AbstractTimeSeriesIndexCreationTask): + class Result: + def __init__(self, total_trade_volume: float = None, date: datetime = None, country: str = None): + self.total_trade_volume = total_trade_volume + self.date = date + self.country = country + + def __init__(self): + super().__init__() + # Define the Map part: + self.map = """ + from segment in timeSeries.Companies.StockPrices + from entry in segment.Entries + + let company = LoadDocument(segment.DocumentId, 'Companies') + + select new + { + date = entry.Timestamp.Date, + country = company.Address.Country, + total_trade_volume = entry.Values[4], + } + """ + + # Define the Reduce part: + self._reduce = """ + from r in results + group r by new {r.date, r.country} + into g + select new + { + date = g.Key.date, + country = g.Key.country, + total_trade_volume = g.Sum(x => x.total_trade_volume) + } + """ + + +# endregion + + +class Indexing(ExampleBase): + def setUp(self): + super().setUp() + + def test_indexing(self): + with self.embedded_server.get_document_store("IndexingTimeSeriesData") as store: + # region index_definition_1 + # Define the 'index definition' + index_definition = TimeSeriesIndexDefinition( + name="StockPriceTimeSeriesFromCompanyCollection", + maps={ + """ + from segment in timeSeries.Companies.StockPrices + from entry in segment.Entries + + let employee = LoadDocument(entry.Tag, "Employees") + + select new + { + trade_volume = entry.Values[4], + date = entry.Timestamp.Date, + company_id = segment.DocumentId, + employee_name = employee.FirstName + ' ' + employee.LastName + } + """ + }, + ) + + # Deploy the index to the server via 'PutIndexesOperation' + store.maintenance.send(PutIndexesOperation(index_definition)) + # endregion + + # region index_definition_2 + # Create the index builder + ts_index_def_builder = TimeSeriesIndexDefinitionBuilder("StockPriceTimeSeriesFromCompanyCollection") + + ts_index_def_builder.map = """ + from segment in timeSeries.Companies.StockPrices + from entry in segment.Entries + select new + { + trade_volume = entry.Values[4], + date = entry.Timestamp.Date, + company_id = segment.DocumentId, + } + """ + # Build the index definition + index_definition_from_builder = ts_index_def_builder.to_index_definition(store.conventions) + + # Deploy the index to the server via 'PutIndexesOperation' + store.maintenance.send(PutIndexesOperation(index_definition_from_builder)) + # endregion + + # region query_1 + with store.open_session() as session: + # Retrieve time series data for the specified company: + # ==================================================== + results = list( + session.query_index_type( + StockPriceTimeSeriesFromCompanyCollection, StockPriceTimeSeriesFromCompanyCollection.IndexEntry + ).where_equals("company_id", "Companies/91-A") + ) + + # Results will include data from all 'StockPrices' entries in document 'Companies/91-A' + # endregion + + # region query_2 + with store.open_session() as session: + # Find what companies had a very high trade volume: + # ================================================= + results = list( + session.query_index_type( + StockPriceTimeSeriesFromCompanyCollection, StockPriceTimeSeriesFromCompanyCollection.IndexEntry + ) + .where_greater_than_or_equal("trade_volume", 150_000_000) + .select_fields(OnlyCompanyName, "company_id") + .distinct() + ) + + # Results will contain company "Companies/65-A" + # since it is the only company with time series entries having such high trade volume. + # endregion + + +class OnlyCompanyName: + def __init__(self, company_id: str = None): + self.name = company_id diff --git a/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Querying/QueryingTsIndex.py b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Querying/QueryingTsIndex.py new file mode 100644 index 0000000000..53cca77970 --- /dev/null +++ b/Documentation/5.4/Samples/python/DocumentExtensions/TimeSeries/Querying/QueryingTsIndex.py @@ -0,0 +1,137 @@ +from datetime import datetime + +from ravendb.documents.indexes.time_series import AbstractTimeSeriesIndexCreationTask + +from examples_base import ExampleBase + + +class QueryingTsIndex(ExampleBase): + def setUp(self): + super().setUp() + + # region sample_ts_index + class TsIndex(AbstractTimeSeriesIndexCreationTask): + # The index-entry: + # =============== + class IndexEntry: + def __init__( + self, + bpm: float = None, + date: datetime = None, + tag: str = None, + employee_id: str = None, + employee_name: str = None, + ): + # The index-fields: + # ================= + self.bpm = bpm + self.date = date + self.tag = tag + self.employee_id = employee_id + self.employee_name = employee_name + + def __init__(self): + super().__init__() + self.map = """ + from ts in timeSeries.Employees.HeartRates + from entry in ts.Entries + let employee = LoadDocument(ts.DocumentId, "Employees") + select new + { + bpm = entry.Values[0], + date = entry.Timestamp.Date, + tag = entry.Tag, + employee_id = ts.DocumentId, + employee_name = employee.FirstName + ' ' + employee.LastName + } + """ + + # endregion + + # region employee_details_class + # This class is used when projecting index-fields via DocumentQuery + class EmployeeDetails: + def __init__(self, employee_name: str = None, employee_id: str = None): + self.employee_name = employee_name + self.employee_id = employee_id + + # endregion + + def test_querying_ts_index(self): + with self.embedded_server.get_document_store("TSIndexQuerying") as store: + self.TsIndex().execute(store) + # region query_index_1 + with store.open_session() as session: + results = list(session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry)) + + # Access results: + entry_result = results[0] + employee_name = entry_result.employee_name + bmp = entry_result.bpm + # endregion + # region query_index_4 + with store.open_session() as session: + results = list(session.advanced.raw_query("from index 'TsIndex'", self.TsIndex.IndexEntry)) + # endregion + + # region query_index_5 + with store.open_session() as session: + results = list( + session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry) + .where_equals("employee_name", "Robert King") + .and_also() + .where_greater_than("bpm", 85) + ) + # endregion + + # region query_index_8 + with store.open_session() as session: + results = list( + session.advanced.raw_query( + "from index 'TsIndex' where employee_name == 'Robert King' and bpm > 85.0", + self.TsIndex.IndexEntry, + ) + ) + # endregion + + # region query_index_9 + with store.open_session() as session: + results = list( + session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry) + .where_less_than("bpm", 58) + .order_by_descending("date") + ) + # endregion + + # region query_index_12 + + with store.open_session() as session: + results = list( + session.advanced.raw_query( + "from index 'TsIndex' where bpm < 58.0 order by date desc", + self.TsIndex.IndexEntry, + ) + ) + # endregion + + # region query_index_13 + + with store.open_session() as session: + results = list( + session.query_index_type(self.TsIndex, self.TsIndex.IndexEntry) + .where_greater_than("bpm", 100) + .select_fields(self.EmployeeDetails, "employee_id") + .distinct() + ) + # endregion + + # region query_index_16 + + with store.open_session() as session: + results = list( + session.advanced.raw_query( + "from index 'TsIndex' where bpm > 100.0 select distinct employee_id", + self.TsIndex.IndexEntry, + ) + ) + # endregion From e390222686a52ce0b697bd6c4aedb6f4eab86c68 Mon Sep 17 00:00:00 2001 From: reebhub Date: Tue, 13 Aug 2024 16:14:27 +0300 Subject: [PATCH 3/4] fixed by review comments --- .../querying/how-to-query.python.markdown | 2 +- .../client-api/session/append.python.markdown | 18 ++++++++++-------- .../querying/using-indexes.python.markdown | 4 +--- .../rollup-and-retention.python.markdown | 2 +- 4 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/how-to-query.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/how-to-query.python.markdown index 529e31b9ba..fc2cf7813c 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/how-to-query.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/how-to-query.python.markdown @@ -6,7 +6,7 @@ * Queries in RavenDB can be written with either of the following: * Using a rich API via session's `query` method - * Using a low-level API via session's `document_query` method + * Using the [document_query](../../../client-api/session/querying/document-query/query-vs-document-query) method * Using **RQL** - - when querying via session's `raw_query` method - when querying through Studio's [Query view](../../../studio/database/queries/query-view) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown index 315af9afd1..89ffab1b19 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.python.markdown @@ -4,7 +4,7 @@ {NOTE: } -* Use `time_series_for.append` for the following actions: +* Use `time_series_for.append_single` or `time_series_for.append` for the following actions: * **Creating a new time series** Appending an entry to a time series that doesn't exist yet will create the time series and add it the new entry. @@ -12,19 +12,21 @@ Appending a new entry to an existing time series will add the entry to the series at the specified timestamp. * **Modifying an existing time series entry** - Use `append` to update the data of an existing entry with the specified timestamp. + Use `append_single` or `append` to update the data of an existing entry with the specified timestamp. -* Each call to `append` handles a **single** - [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). +* Each call to `append_single` handles a **single** time series value at + a **single** [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). + Each call to `append` can handle **multiple** time series values at + a **single** [time series entry](../../../../document-extensions/timeseries/design#time-series-entries). * To append **multiple** entries in a single transaction you can: - * Call `append` as many times as needed before calling `session.save_changes`, as shown in the examples below. + * Call `append_single` or `append` as many times as needed before calling `session.save_changes`, as shown in the examples below. * Use patching to update the time series. Learn more in [Patch time series entries](../../../../document-extensions/timeseries/client-api/session/patch). * Append entries directly on the _Store_ via [Operations](../../../../client-api/operations/what-are-operations). Learn more in [Append time series operations](../../../../document-extensions/timeseries/client-api/operations/append-and-delete). * In this page: - * [`append` usage](../../../../document-extensions/timeseries/client-api/session/append#append-usage) + * [Usage](../../../../document-extensions/timeseries/client-api/session/append#usage) * [Examples](../../../../document-extensions/timeseries/client-api/session/append#examples) * [Append entries with a single value](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-a-single-value) * [Append entries with multiple values](../../../../document-extensions/timeseries/client-api/session/append#append-entries-with-multiple-values) @@ -34,7 +36,7 @@ --- -{PANEL: `append` usage} +{PANEL: Usage} **Flow**: @@ -45,7 +47,7 @@ e.g. a document object returned from [session.query](../../../../client-api/session/querying/how-to-query) or from [session.load](../../../../client-api/session/loading-entities#load). * Specify the time series name. -* Call `time_series_for.append` and pass it the time series entry details. +* Call `time_series_for.append_single` or `time_series_for.append` and pass it the time series entry details. * Call `session.save_changes` for the action to take effect on the server. **Note**: diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown index ed19f83e9b..25834b6b34 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/querying/using-indexes.python.markdown @@ -130,7 +130,6 @@ select distinct EmployeeID {PANEL: Syntax} * [query](../../../client-api/session/querying/how-to-query#query-overview) - {CODE-BLOCK: JSON} def query( self, source: Optional[Query] = None, object_type: Optional[Type[_T]] = None @@ -138,8 +137,7 @@ select distinct EmployeeID ... {CODE-BLOCK/} -* [document_query](../../../client-api/session/querying/how-to-query#query-overview) - +* [document_query](../../../client-api/session/querying/document-query/query-vs-document-query) {CODE-BLOCK: JSON} def document_query( self, diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown index 5b540a5f99..1dd7d7cccc 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.python.markdown @@ -194,7 +194,7 @@ class TimeSeriesCollectionConfiguration: | Property | Type | Description | |-----------------|------|-------------| -| **collections** | `Dict` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | +| **collections** | `Dict[str, TimeSeriesCollectionConfiguration]` | Populate this `Dictionary` with the collection names and their corresponding `TimeSeriesCollectionConfiguration` objects. | | **disabled** (Optional) | `bool` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | | **policies** (Optional) | `List[TimeSeriesPolicy]` | Populate this `List` with your rollup policies. | | **raw_policy** (Optional) | `RawTimeSeriesPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series. | From de8f1551eb8f8573324a030d66f93b7bd020abcb Mon Sep 17 00:00:00 2001 From: reebhub Date: Wed, 21 Aug 2024 12:25:04 +0300 Subject: [PATCH 4/4] added syntax sections for the indexing and get-names TS pages --- .../session/get/get-names.python.markdown | 18 +++ .../timeseries/indexing.python.markdown | 126 ++++++++++++++++++ 2 files changed, 144 insertions(+) diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown index 8303e4690d..d478c61e7a 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.python.markdown @@ -8,6 +8,7 @@ * In this page: * [`get_time_series_for` usage](../../../../../document-extensions/timeseries/client-api/session/get/get-names#get_time_series_for-usage) * [Example](../../../../../document-extensions/timeseries/client-api/session/get/get-names#example) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-names#syntax) {NOTE/} @@ -35,6 +36,23 @@ {PANEL/} +{PANEL: Syntax} + +{CODE-BLOCK:python} +def get_time_series_for(self, entity: object) -> List[str]: + ... +{CODE-BLOCK/} + +| Parameter | Type | Description | +|--------------|-------|-----------------------------------------------------| +| **entity** | `object` | The entity whose time series names you want to get | + +| Return value | | +|----------------|---------------------------------------------------------------------------------------------------| +| `List[str]` | A list of names of all the time series associated with the entity, sorted alphabetically by the name | + +{PANEL/} + ## Related articles **Client API** diff --git a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown index 951c6c055f..176c700398 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown +++ b/Documentation/5.4/Raven.Documentation.Pages/document-extensions/timeseries/indexing.python.markdown @@ -14,6 +14,7 @@ * [Map index - index single time series from single collection](../../document-extensions/timeseries/indexing#map-index---index-single-time-series-from-single-collection) * [Multi-Map index - index time series from several collections](../../document-extensions/timeseries/indexing#multi-map-index---index-time-series-from-several-collections) * [Map-Reduce index](../../document-extensions/timeseries/indexing#map-reduce-index) + * [Syntax](../../document-extensions/timeseries/indexing#syntax) {NOTE/} @@ -143,6 +144,131 @@ select distinct CompanyID {PANEL/} +{PANEL: Syntax} + +--- + +### `AbstractJavaScriptTimeSeriesIndexCreationTask` + +{CODE-BLOCK:python} +class AbstractJavaScriptTimeSeriesIndexCreationTask(AbstractIndexCreationTaskBase[TimeSeriesIndexDefinition]): + def __init__( + self, + conventions: DocumentConventions = None, + priority: IndexPriority = None, + lock_mode: IndexLockMode = None, + deployment_mode: IndexDeploymentMode = None, + state: IndexState = None, + ): + super().__init__(conventions, priority, lock_mode, deployment_mode, state) + self._definition = TimeSeriesIndexDefinition() + + @property + def maps(self) -> Set[str]: + return self._definition.maps + + @maps.setter + def maps(self, maps: Set[str]): + self._definition.maps = maps + + @property + def reduce(self) -> str: + return self._definition.reduce + + @reduce.setter + def reduce(self, reduce: str): + self._definition.reduce = reduce +{CODE-BLOCK/} + +Learn more about JavaScript indexes in [JavaScript Indexes](../../indexes/javascript-indexes). + +--- + +### `TimeSeriesIndexDefinition` + +{CODE-BLOCK:python} +class TimeSeriesIndexDefinition(IndexDefinition): + @property + def source_type(self) -> IndexSourceType: + return IndexSourceType.TIME_SERIES +{CODE-BLOCK/} + +While `TimeSeriesIndexDefinition` is currently functionally equivalent to the regular +[`IndexDefinition`](../../indexes/creating-and-deploying#using-maintenance-operations) +class from which it inherits, it is recommended to use `TimeSeriesIndexDefinition` when +creating a time series index definition in case additional functionality is added in +future versions of RavenDB. + +--- + +### `TimeSeriesIndexDefinitionBuilder` + +{CODE-BLOCK:python} +class TimeSeriesIndexDefinitionBuilder(AbstractIndexDefinitionBuilder[TimeSeriesIndexDefinition]): + def __init__(self, index_name: Optional[str] = None): + super().__init__(index_name) + self.map: Optional[str] = None +{CODE-BLOCK/} + +--- + +### `TimeSeriesSegment` + +* Segment properties include the entries data and aggregated values that RavenDB automatically updates in the segment's header. + +* The following segment properties can be indexed: + + {CODE-BLOCK:python} +public sealed class TimeSeriesSegment +{ + // The ID of the document this time series belongs to + public string DocumentId { get; set; } + + // The name of the time series this segment belongs to + public string Name { get; set; } + + // The smallest values from all entries in the segment + // The first array item is the Min of all first values, etc. + public double[] Min { get; set; } + + // The largest values from all entries in the segment + // The first array item is the Max of all first values, etc. + public double[] Max { get; set; } + + // The sum of all values from all entries in the segment + // The first array item is the Sum of all first values, etc. + public double[] Sum { get; set; } + + // The number of entries in the segment + public int Count { get; set; } + + // The timestamp of the first entry in the segment + public DateTime Start { get; set; } + + // The timestamp of the last entry in the segment + public DateTime End { get; set; } + + // The segment's entries themselves + public TimeSeriesEntry[] Entries { get; set; } +} + {CODE-BLOCK/} + +* These are the properties of a `TimeSeriesEntry` which can be indexed: + + {CODE-BLOCK:python} +public class TimeSeriesEntry +{ + public DateTime Timestamp; + public string Tag; + public double[] Values; + + // This is exactly equivalent to Values[0] + public double Value; +} + {CODE-BLOCK/} + +{PANEL/} + ## Related articles ### Time Series