diff --git a/Documentation/5.0/Raven.Documentation.Pages/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/.docs.json index a091a1be82..484c05d3b1 100644 --- a/Documentation/5.0/Raven.Documentation.Pages/.docs.json +++ b/Documentation/5.0/Raven.Documentation.Pages/.docs.json @@ -39,6 +39,11 @@ "Name": "Users Issues", "Mappings": [] }, + { + "Path": "/document-extensions", + "Name": "Document Extensions", + "Mappings": [] + }, { "Path": "/cloud", "Name": "Cloud", diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/.docs.json new file mode 100644 index 0000000000..35d6d96819 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/.docs.json @@ -0,0 +1,7 @@ +[ + { + "Path": "/timeseries", + "Name": "Time Series", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/.docs.json new file mode 100644 index 0000000000..bd6ecf89e4 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/.docs.json @@ -0,0 +1,42 @@ +[ + { + "Path": "overview.markdown", + "Name": "Overview", + "DiscussionId": "2bc22ef1-450e-4ae9-aa6f-56b0b47977d9", + "Mappings": [] + }, + { + "Path": "/client-api", + "Name": "Client API", + "Mappings": [] + }, + { + "Path": "/querying", + "Name": "Querying", + "Mappings": [] + }, + { + "Path": "indexing.markdown", + "Name": "Indexing Time Series", + "DiscussionId": "f23052eb-3c53-4984-a2cd-03a0ff9835d3", + "Mappings": [] + }, + { + "Path": "rollup-and-retention.markdown", + "Name": "Rollup and Retention", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "time-series-and-other-features.markdown", + "Name": "Time Series and Other Features", + "DiscussionId": "902e7192-9e86-4b98-9f8a-0df0b6c731f9", + "Mappings": [] + }, + { + "Path": "design.markdown", + "Name": "Design", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/.docs.json new file mode 100644 index 0000000000..8e2d6767f4 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/.docs.json @@ -0,0 +1,30 @@ +[ + { + "Path": "overview.markdown", + "Name": "Overview", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "/session", + "Name": "Session", + "Mappings": [] + }, + { + "Path": "/operations", + "Name": "Operations", + "Mappings": [] + }, + { + "Path": "javascript-support.markdown", + "Name": "JavaScript Support", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "strongly-typed-api.markdown", + "Name": "Strongly Typed API", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.png b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.png new file mode 100644 index 0000000000..3071baba86 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.snag b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.snag new file mode 100644 index 0000000000..c388d6d2aa Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/images/time-series-view-coordinates.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.markdown new file mode 100644 index 0000000000..e2783d4b7f --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/javascript-support.markdown @@ -0,0 +1,126 @@ +# Time Series: JavaScript Support + +{NOTE: } + +With the introduction of time series, RavenDB's support for the execution +of [JavaScript-based operations](../../../server/kb/JavaScript-engine) +over [single](../../../client-api/operations/patching/single-document#patching-how-to-perform-single-document-patch-operations) +and [multiple](../../../client-api/operations/patching/set-based) +documents has been extended to allow manipulations involving time series. + +* Methods that gain time series functionality this way are: + * [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch) - + `session` patching method + * [PatchOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchoperation) - + `store` patching operation + * [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) - + `store` patch-by-query operation + +* In this page: + * [JavaScript API methods](../../../document-extensions/timeseries/client-api/javascript-support#javascript-api-methods) + * [timeseries - Choose a Time Series](../../../document-extensions/timeseries/client-api/javascript-support#section) + * [timeseries.append - Append Untagged Entry](../../../document-extensions/timeseries/client-api/javascript-support#section-1) + * [timeseries.append - Append Tagged Entry](../../../document-extensions/timeseries/client-api/javascript-support#section-2) + * [timeseries.remove - Remove Entries Range](../../../document-extensions/timeseries/client-api/javascript-support#section-3) + * [timeseries.get - Get Entries Range](../../../document-extensions/timeseries/client-api/javascript-support#section-4) + * [Usage Samples](../../../document-extensions/timeseries/client-api/javascript-support#usage-samples) + +{NOTE/} + +--- + +{PANEL: JavaScript API methods} + +The JavaScript time series API includes these methods: + +--- + +#### `timeseries (doc, name)` + +Choose a time series by the ID of its owner document and by the series name. + + | Parameter | Type | Explanation + |:---:|:---:|:---:| + | doc | `string` | Document ID + | name | `string` | Time Series Name + +--- + +#### `timeseries.append (timestamp, values)` + +Use this method to append time series entries to a document. + +| Parameter | Type | Explanation +|:---:|:---:|:---:| +| timestamp | `DateTime` | Timestamp +| values | `double[]` | Values + +--- + +#### `timeseries.append (timestamp, values, tag)` + +Use this method to append to a document time series entries with tags. + +| Parameter | Type | Explanation +|:---:|:---:|:---:| +| timestamp | `DateTime` | Timestamp +| values | `double[]` | Values +| tag | `string` | Tag + +--- + +#### `timeseries.remove (from, to)` + +Use this method to remove a range of entries from a document. + +| Parameter | Type | Explanation +|:---:|:---:|:---:| +| from | `DateTime` | Range Start +| to | `DateTime` | Range End + +--- + +#### `timeseries.get (from, to)` + +Use this method to retrieve a range of time series entries. + +| Parameter | Type | Explanation +|:---:|:---:|:---:| +| from | `DateTime` | Range Start +| to | `DateTime` | Range End + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample, we pass [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch) + a script that appends a document 100 time series entries. + {CODE TS_region-Session_Patch-Append-100-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + +* In this sample, we pass [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) + a script that runs a document query and removes the HeartRate time series from + matching documents. + {CODE TS_region-PatchByQueryOperation-Remove-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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) + +**Patching Time Series** +[Patching in a Session](../../../document-extensions/timeseries/client-api/session/patch) +[Patching Operation](../../../document-extensions/timeseries/client-api/operations/patch#patchoperation) +[Patch By Query Operation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) + +**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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/.docs.json new file mode 100644 index 0000000000..6f75dabd80 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/.docs.json @@ -0,0 +1,26 @@ +[ + { + "Path": "append-and-remove.markdown", + "Name": "Append & Remove", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "get.markdown", + "Name": "Get", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "patch.markdown", + "Name": "Patch", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "/bulk-insert", + "Name": "Bulk Insert", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-remove.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-remove.markdown new file mode 100644 index 0000000000..50f5eabcea --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/append-and-remove.markdown @@ -0,0 +1,159 @@ +# Operations: Append & Remove Time Series + +--- + +{NOTE: } + +To **Append** and **Remove** multiple time series entries, use `TimeSeriesBatchOperation`. + +* In this page: + * [`TimeSeriesBatchOperation`](../../../../document-extensions/timeseries/client-api/operations/append-and-remove#timeseriesbatchoperation) + * [Syntax](../../../../document-extensions/timeseries/client-api/operations/append-and-remove#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/operations/append-and-remove#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/operations/append-and-remove#usage-samples) +{NOTE/} + +--- + +{PANEL: `TimeSeriesBatchOperation`} + +`TimeSeriesBatchOperation` executes a list of time series entries **Append** +and **Remove** actions. +The list is prepared beforehand in a `TimeSeriesOperation` instance using +**TimeSeriesOperation.Append** and **TimeSeriesOperation.Remove**, and is +passed to `TimeSeriesBatchOperation` as an argument. + +{PANEL/} + +{PANEL: Syntax} + +* `TimeSeriesBatchOperation` + **This is the operation you need to execute to append and remove + time series entries.** + + * **Definition** + {CODE TimeSeriesBatchOperation-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `documentId` | `string` | ID of the document to append TS data to | + | `operation` | `TimeSeriesOperation` | Operation configuration class:
Which Append/Remove actions to perform | + +* `TimeSeriesOperation` + **This is the configuration class provided to `TimeSeriesBatchOperation` + as an argument, with a list of time series entries Append and Remove actions.** + + {CODE-BLOCK:JSON} + public class TimeSeriesOperation + { + public string Name; + public void Append(AppendOperation appendOperation) + public void Remove(RemoveOperation removeOperation) + + //.. + } + {CODE-BLOCK/} + + | Property | Type | Description | + |:-------------|:-------------|:-------------| + | `Name` | `string` | Time Series name | + | `Append` | `method` | Add an Append action to the list | + | `Remove` | `method` | Add a Remove action to the list | + + +--- + + * To add a time series entry Append action, call `TimeSeriesOperation.Append`. + {CODE-BLOCK:JSON} + public void Append(AppendOperation appendOperation) + {CODE-BLOCK/} + {CODE-BLOCK:JSON} + public class AppendOperation + { + public DateTime Timestamp; + public double[] Values; + public string Tag; + + //.. + } + {CODE-BLOCK/} + + | Property | Type | Description | + |:-------------|:-------------|:-------------| + | `Timestamp` | `DateTime` | The TS entry will be appended at this timestamp | + | `Values` | `double[]` | Entry values | + | `Tag` | `string` | Entry tag (optional) | + +--- + + * To add a time series entry Remove action, call `TimeSeriesOperation.Remove`. + {CODE-BLOCK:JSON} + public void Remove(RemoveOperation removeOperation) + {CODE-BLOCK/} + {CODE-BLOCK:JSON} + public class RemoveOperation + { + public DateTime? From, To; + + //.. + } + {CODE-BLOCK/} + + | Property | Type | Description | + |:-------------|:-------------|:-------------| + | `From` | `DateTime` | Range start
Entries will be removed starting at this timestamp | + | `To` | `DateTime` | Range end
Entries will be removed up to this timestamp | + +{PANEL/} + + +{PANEL: Usage Flow} + +* Create an instance of `TimeSeriesOperation` + * Add it the **time series name**. + +* Prepare the Append and Remove sequence. + * Call `TimeSeriesOperation.Append` to add an Append action + * Call `TimeSeriesOperation.Remove` to add a Remove action + + {INFO: } + NOTE: Remove actions will be executed **before** Append actions. + {INFO/} + +* Create a `TimeSeriesBatchOperation` instance. + Pass it the **document ID** and your **`TimeSeriesOperation` instance** + +* Call `store.Operations.Send` with your `TimeSeriesBatchOperation` + instance to execute the operation. + +{PANEL/} + + +{PANEL: Usage Samples} + +* In this sample, we use `TimeSeriesBatchOperation` to append + a time series two entries. + {CODE timeseries_region_Append-Using-TimeSeriesBatchOperation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we remove two ranges of entries from a time series. + {CODE timeseries_region_Remove-Range-Using-TimeSeriesBatchOperation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/.docs.json new file mode 100644 index 0000000000..4ce0661972 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/.docs.json @@ -0,0 +1,8 @@ +[ + { + "Path": "append-in-bulk.markdown", + "Name": "Append In Bulk", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk.markdown new file mode 100644 index 0000000000..22fadf11db --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk.markdown @@ -0,0 +1,93 @@ +# Operations: Append in Bulk + +--- + +{NOTE: } + +* `store.BulkInsert` is RavenDB's high-performance data insertion operation. + Its `TimeSeriesFor` interface resembles [session.TimeSeriesFor](../../../../../document-extensions/timeseries/client-api/session/append) + in its ability to append multiple time series entries in a single transaction, + while omitting the liabilities of the `session` interface to gain much higher speed. + +* In this page: + * [`BulkInsert.TimeSeriesFor.Append`](../../../../../document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk#bulkinsert.timeseriesfor.append) + * [Syntax](../../../../../document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk#usage-flow) + * [Usage Samples](../../../../../document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk#usage-samples) + +{NOTE/} + +{PANEL: `BulkInsert.TimeSeriesFor.Append`} + +Create a `BulkInsert` instance, pass its `TimeSeriesFor` method the document's ID +and time series name, and then call `TimeSeriesFor.Append` as many times as you need +to. All the Append operations you perform this way will be executed in +a single transaction. + +{PANEL/} + +{PANEL: Syntax} + +* `BulkInsert.TimeSeriesFor` + {CODE BulkInsert.TimeSeriesFor-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `id` | `string` | Document ID | + | `name` | `string` | Time Series Name | + +--- + +* There are two `TimeSeriesFor.Append` overloads: + {CODE Append-Operation-Definition-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE Append-Operation-Definition-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `timestamp` | `DateTime` | TS-entry's timestamp | + | `value` | `double` | A single value | + | `values` | `ICollection` | Multiple values | + | `tag` | `string` | TS-entry's tag (optional) | + +{PANEL/} + +{PANEL: Usage Flow} + +* Create a `store.BulkInsert` instance. +* Pass the instance's `TimeSeriesFor` - + * Document ID + * Time series name +* Call `TimeSeriesFor.Append` as many times as you like. Pass it - + * The entry's Timestamp + * The entry's Value or Values + * The entry's Tag (optional) + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample, we append a time series two entries in a single transaction. + {CODE timeseries_region_Use-BulkInsert-To-Append-2-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we append a time series a hundred entries in a single transaction. + {CODE timeseries_region_Use-BulkInsert-To-Append-100-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we append a time series two saets of values in a single transaction. + {CODE BulkInsert-overload-2-Two-HeartRate-Sets@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/get.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/get.markdown new file mode 100644 index 0000000000..94f4b2fc50 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/get.markdown @@ -0,0 +1,145 @@ +# Operations: How to Get Time Series + +--- + +{NOTE: } + +Get a single time series' entries using `GetTimeSeriesOperation`. +Get multiple time series' entries using `GetMultipleTimeSeriesOperation`. + +* In this page: + * [`GetTimeSeriesOperation`](../../../../document-extensions/timeseries/client-api/operations/get#gettimeseriesoperation) + * [Syntax](../../../../document-extensions/timeseries/client-api/operations/get#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/operations/get#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/operations/get#usage-sample) + * [`GetMultipleTimeSeriesOperation`](../../../../document-extensions/timeseries/client-api/operations/get#getmultipletimeseriesoperation) + * [Syntax](../../../../document-extensions/timeseries/client-api/operations/get#syntax-1) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/operations/get#usage-flow-1) + * [Usage Sample](../../../../document-extensions/timeseries/client-api/operations/get#usage-sample-1) + +{NOTE/} + +--- + +{PANEL: `GetTimeSeriesOperation`} + +Use `GetTimeSeriesOperation` to retrieve entries from a single +time series. + +--- + +### Syntax + +* **Definition** + {CODE GetTimeSeriesOperation-Definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `docId` | `string` | Document ID | + | `timeseries` | `string` | Time series name | + | `from` | `DateTime` | Range start | + | `to` | `DateTime` | Range end | + | `start` | `int` | Start of first Page | + | `pageSize` | `int` | Size of each page | + +* **Return Value**: **`TimeSeriesRangeResult`** + {CODE TimeSeriesRangeResult-class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * Requesting a time series that doesn't existing will return `null`. + * Requesting an entries range that doesn't exist will return a `TimeSeriesRangeResult` object with an + empty `Entries` property. + +* **Exceptions** + Exceptions are not generated. + +--- + +### Usage Flow + +* Pass `GetTimeSeriesOperation` - + Document ID, Time Series Name, Range Start, Range End. +* Call `store.Operations.Send` to execute the operation. +* Entries are returned into a `dictionary of `TimeSeriesRangeResult` classes. + +--- + +### Usage Sample + +* In this sample, we retrieve all the entries of a time series. + {CODE timeseries_region_Get-Single-Time-Series@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: `GetMultipleTimeSeriesOperation`} + +Use `GetMultipleTimeSeriesOperation` to retrieve data from +multiple time series. + +--- + +### Syntax + +* **Definition** + {CODE GetMultipleTimeSeriesOperation-Definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `docId` | `string` | Document ID | + | `ranges` | `IEnumerable` | Ranges of Time Series Entries | + | `start` | `int` | Start of first Page | + | `pageSize` | `int` | Size of each page | + + Pass `GetMultipleTimeSeriesOperation` a **TimeSeriesRange** instance + For each entries range you want it to retrieve. + {CODE TimeSeriesRange-class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Return Value**: **`TimeSeriesRangeResult`** + {CODE TimeSeriesDetails-class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE TimeSeriesRangeResult-class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * When a time series or an entries range that do not exist are requested, + the return value for the erronous range is a `TimeSeriesRangeResult` + object with an empty `Entries` property. + +* **Exceptions** + Exceptions are not generated. + +--- + +### Usage Flow + +* Pass `GetMultipleTimeSeriesOperation` - + * The time series parent-Document ID + * A **TimeSeriesRange** instance for each entries range you want + it to retrieve. +* Populate each TimeSeriesRange instance with a **time Series name**, + a **range start** timestamp (`From`), and a **range end** timestamp (`To`). +* Call `store.Operations.Send` to execute the operation. + +--- + +### Usage Sample + +* In this sample, we retrieve chosen entries from two time series. + {CODE timeseries_region_Get-Multiple-Time-Series@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.markdown new file mode 100644 index 0000000000..8bf7c4f5fc --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/operations/patch.markdown @@ -0,0 +1,173 @@ +# Operations: Patch Time Series + +--- + +{NOTE: } + +* Time series data can be patched - + * to a single document located by its ID, using [PatchOperation](../../../../client-api/operations/patching/single-document#patching-how-to-perform-single-document-patch-operations). + * to multiple documents located by a query, using [PatchByQueryOperation](../../../../client-api/operations/patching/set-based). +* Both patching operations can be used to Append, Get and Remove time series entries. + +* In this page: + * [Patching Operations](../../../../document-extensions/timeseries/client-api/operations/patch#patching-operations) + * [`PatchOperation`](../../../../document-extensions/timeseries/client-api/operations/patch#patchoperation) + * [Syntax](../../../../document-extensions/timeseries/client-api/operations/patch#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/operations/patch#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/operations/patch#usage-samples) + * [`PatchByQueryOperation`](../../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) + * [Syntax](../../../../document-extensions/timeseries/client-api/operations/patch#syntax-1) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/operations/patch#usage-flow-1) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/operations/patch#usage-samples-1) + +{NOTE/} + +--- + +{PANEL: Patching Operations} + +{INFO: } + +* To patch time series data, use `PatchOperation` or `PatchByQueryOperation`. +* `PatchOperation` is RavenDB's operation for single-document patching, and + `PatchByQueryOperation` is used for set-based document operations. + You can use both to patch time series data, by + [customizing the JavaScript](../../../../document-extensions/timeseries/client-api/javascript-support) + they are using. + +{INFO/} + +* Use `PatchOperation` to **load a document by its ID and patch it time series entries**. + + Here, for example, we use `PatchOperation` to patch a document a single time series entry. + {CODE TS_region-Operation_Patch-Append-Single-TS-Entry@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* Use `PatchByQueryOperation` to **run a document query and patch time series entries to matching documents**. + + Here, we use `PatchByQueryOperation` to append a time series entry to all + documents of the User collection. + {CODE TS_region-PatchByQueryOperation-Append-To-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: `PatchOperation`} + +--- + +#### Syntax + +* **`PatchOperation`** + * **Definition** + {CODE PatchOperation-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `id` | `string` | Patched document ID | + | `changeVector` | `string` | Change vector, to verify that the document hasn't been modified.
Can be `null`. | + | `patch` | `PatchRequest` | The patching JavaScript | + | `patchIfMissing` | `PatchRequest` | Patching JavaScript to be used if the document isn't found | + | `skipPatchIfChangeVectorMismatch` | `bool` | If true, do not patch if the document has been modified
default: **false** | + +* **`PatchRequest`** + * **Definition** + {CODE PatchRequest-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `Script` | `string` | Patching script | + | `Values` | `Dictionary` | Values that the patching script can use | + +--- + +#### Usage Flow + +* Create an instance of `PatchOperation` and pass its constructor - + * the document ID + * the change vector (or `null`) + * a new `PatchRequest` instance +* Use the `PatchRequest` instance to pass `PatchOperation` + a JavaScript that appends or removes time series entries. +* Call `store.Operations.Send` to execute the operation. + +--- + +#### Usage Samples + +* In this sample, we provide `PatchOperation`with a script that appends + 100 time series entries to a document. + Timestamps and values are drawn from an array, and other + arguments are provided in the "Values" section. + {CODE TS_region-Operation_Patch-Append-100-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we use `PatchOperation` to remove a range of 50 time series + entries from a document. + {CODE TS_region-Operation_Patch-Remove-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: `PatchByQueryOperation`} + +--- + +#### Syntax + +* **`store.Operations.Send` Definition** + {CODE Store-Operations-send-Definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **`PatchByQueryOperation` Definition** + {CODE PatchByQueryOperation-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `queryToUpdate` | `IndexQuery` | The query, including the JavaScript | + | `QueryOperationOptions` | `options` | Additional options
Default: `null` | + +* **Return Value**: `Operation` + +--- + +#### Usage Flow + +* Create a `PatchByQueryOperation` operation. +* Pass `PatchByQueryOperation` a new `IndexQuery` instance. +* Add the `IndexQuery` instance a JavaScript that specifies + the query you want to run. +* Call `store.Operations.Send` to execute the operation. + +--- + +#### Usage Samples + +* In this sample, we run a document query and remove the HeartRate time series + from documents we find. + {CODE TS_region-PatchByQueryOperation-Remove-From-Multiple-Docs@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we patch each User document a "NumberOfUniqueTagsInTS" field with + the number of different tags in the user's "ExcersizeHeartRate" time series. + To do this, we use the JavaScript `get` method to get each time series' entries (the + range we choose includes them all), and check each entry's tag. + {CODE TS_region-PatchByQueryOperation-Get@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/overview.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/overview.markdown new file mode 100644 index 0000000000..27cb7ed3a0 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/overview.markdown @@ -0,0 +1,123 @@ +# Time Series: Client API Overview +--- + +{NOTE: } + +The Time Series client API includes a set of [session](../../../client-api/session/what-is-a-session-and-how-does-it-work) +methods and [store](../../../client-api/what-is-a-document-store) +[operations](../../../client-api/operations/what-are-operations). +You can use the API to **append** (create and update), **get**, +**remove**, **include**, **patch** and **query** time series data. + +* In this page: + * [Creating and Removing Time Series](../../../document-extensions/timeseries/client-api/overview#creating-and-removing-time-series) + * [`session` Methods -vs- `document-store` Operations](../../../document-extensions/timeseries/client-api/overview#session-methods--vs--document-store-operations) + * [Available Time Series `session` methods](../../../document-extensions/timeseries/client-api/overview#available-time-series-session-methods) + * [Available Time Series `store` Operations](../../../document-extensions/timeseries/client-api/overview#available-time-series-store-operations) + +{NOTE/} + +--- + +{PANEL: Creating and Removing Time Series} + +A time series is constructed of time series **entries**, which can +be created and removed using the API. +There is no need to explicitly create or delete a time series. + +* A time series is created when the first entry is appended to it. +* A time series is deleted when all entries are removed from it. + +{PANEL/} + +{PANEL: `session` Methods -vs- `document-store` Operations} + +Some time series functions are available through both `session` methods +and `document-store` operations: +You can **append**, **remove**, **get** and **patch** time series data +through both interfaces. + +--- + +There are also functionalities unique to each interface. + +* **Time series functionalities unique to the `session`interface**: + * `session` methods provide a **transactional guarantee**. + Use them when you want to guarantee that your actions would + be processed in a [single ACID transaction](../../../client-api/faq/transaction-support). + You can, for instance, gather multiple session actions + (e.g. the update of a time series and the modification + of a document) and execute them in a single transaction + by calling `session.SaveChanges`, to ensure that they + would all be completed or all be reverted. + * You can use `session` methods to `include` time series while + loading documents. + Included time series data is held by the client's session, + and can be handed to the user instantly when requested + without issuing an additional request to the server +* **Time series functionalities unique to the `store`interface**: + * Getting the data of **multiple time series** in a single operation. + * Managing time series **rollup and retention policies**. + * Patching time series data to **multiple documents** located by a query. +{PANEL/} + +{PANEL: Available Time Series `session` methods} + +* [TimeSeriesFor.Append](../../../document-extensions/timeseries/client-api/session/append) + Use this method to **Append entries to a time series** + (creating the series if it didn't previously exist). +* [TimeSeriesFor.Remove](../../../document-extensions/timeseries/client-api/session/remove) + Use this method to **Remove a range of entries from a time series** + (removing the series completely if all entries have been removed). + * [TimeSeriesFor.Get](../../../document-extensions/timeseries/client-api/session/get/get-entries) + Use this method to **Retrieve raw time series entries** + for all entries or for a chosen entries range. +* [Advanced.GetTimeSeriesFor](../../../document-extensions/timeseries/client-api/session/get/get-names) + Use this method to **Retrieve time series Names**. + Series names are fetched by `GetTimeSeriesFor` directly from their parent documents' + metadata, requiring no additional server roundtrips. +* [session.Advanced.Defer](../../../document-extensions/timeseries/client-api/session/patch) + Use this method to **patch time series data to a document**. +* **To include time series data** - + * [Use IncludeTimeSeries while loading a document via session.Load](../../../document-extensions/timeseries/client-api/session/include/with-session-load) + * [Use IncludeTimeSeries while retrieving a document via session.Query](../../../document-extensions/timeseries/client-api/session/include/with-session-query) + * [Use RQL while running a raw query](../../../document-extensions/timeseries/client-api/session/include/with-raw-queries) +{PANEL/} + +{PANEL: Available Time Series `store` Operations} + +* [TimeSeriesBatchOperation](../../../document-extensions/timeseries/client-api/operations/append-and-remove) + Use this operation to **append and remove time series data**. + You can bundle a series of Append and/or Remove operations in a list and + execute them in a single call. +* [GetTimeSeriesOperation](../../../document-extensions/timeseries/client-api/operations/get#gettimeseriesoperation) + Use this operation to Get entries from a single time series. +* [GetMultipleTimeSeriesOperation](../../../document-extensions/timeseries/client-api/operations/get#getmultipletimeseriesoperation) + Use this operation to Get entries from multiple time series. +* [ConfigureTimeSeriesOperation](../../../document-extensions/timeseries/rollup-and-retention) + Use this operation to **manage time series roll-up and retention policies**. +* [PatchOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchoperation) + Use this operation to append/remove time series data to/from a single document. +* [PatchByQueryOperation](../../../document-extensions/timeseries/client-api/operations/patch#patchbyqueryoperation) + Use this operation to run a query and append/remove time series data to/from + matching documents. + by a query**. +* [BulkInsert.TimeSeriesFor.Append](../../../document-extensions/timeseries/client-api/operations/bulk-insert/append-in-bulk) + Use this operation to append time series entries in bulk. + +{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) + +**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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/.docs.json new file mode 100644 index 0000000000..ee0462281b --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/.docs.json @@ -0,0 +1,38 @@ +[ + { + "Path": "append.markdown", + "Name": "Append", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "remove.markdown", + "Name": "Remove", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "/get", + "Name": "Get", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "/include", + "Name": "Include", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "patch.markdown", + "Name": "Patch", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "querying-overview.markdown", + "Name": "Querying Overview", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.markdown new file mode 100644 index 0000000000..2f51317414 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/append.markdown @@ -0,0 +1,102 @@ +# Session: Appending & Updating Time Series + +--- + +{NOTE: } + +* Create and update time series and their entries using `TimeSeriesFor.Append`. + +* You can append a single [time series entry](../../../../document-extensions/timeseries/design#time-series-entries) at a time. + Note, however, that you can `Append` as many times as you need to before calling + `session.SaveChanges`, to append multiple entries in a single transaction. + +* In this page: + * [`TimeSeriesFor.Append`](../../../../document-extensions/timeseries/client-api/session/append#timeseriesfor.append) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/append#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/session/append#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/session/append#usage-samples) +{NOTE/} + + + +--- + +{PANEL: `TimeSeriesFor.Append`} + +* `TimeSeriesFor.Append` is used for the creation of time series and + time series entries, and for the modification of entries values. + * **Creating a Time Series** + Append an entry to a time series that doesn't exist yet, + to create the time series and add it the new entry. + * **Creating a Time Series Entry** + Append an existing time series a new entry, + to add the entry to this series at the specified timestamp. + * **Modifying Entry Values** + Append a time series an entry it already has, + to update the existing entry with the new data. + +{PANEL/} + +{PANEL: Syntax} + +* There are two `TimeSeriesFor.Append` methods: + * Append an entry with a single value. + {CODE TimeSeriesFor-Append-definition-double@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * Append an entry with multiple values. + {CODE TimeSeriesFor-Append-definition-inum@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `timestamp` | DateTime | Time series entry's timestamp | + | `value` | double | Entry's value | + | `values` | IEnumerable | Entry's values | + | `tag` | string | Entry's tag
The tag is optional. | + +* **Exceptions** + If the document doesn't exist, a `DocumentDoesNotExistException` exception is thrown. + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session. +* Create an instance of `TimeSeriesFor`. + * Either pass `TimeSeriesFor` an explicit document ID, + -or- + Pass it an [entity tracked by the session](../../../../client-api/session/loading-entities), 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). + * Pass `TimeSeriesFor` the time series name. +* Call `TimeSeriesFor.Append`. +* Call `session.SaveChanges` for the action to take effect on the server. + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample we use the [first overload](../../../../document-extensions/timeseries/client-api/session/append#overload-1) + to append an entry with a single value. + Though We run a loop to append multiple entries, all entries are appended in a single + transaction when `SaveChanges` is called. + {CODE timeseries_region_TimeSeriesFor-Append-TimeSeries-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample we use the [second overload](../../../../document-extensions/timeseries/client-api/session/append#overload-2) + to append a time series entry with three values. + {CODE timeseries_region_Append-With-IEnumerable@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/.docs.json new file mode 100644 index 0000000000..de588864c4 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/.docs.json @@ -0,0 +1,14 @@ +[ + { + "Path": "get-entries.markdown", + "Name": "Get Entries", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "get-names.markdown", + "Name": "Get Names", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.markdown new file mode 100644 index 0000000000..f3e3e3baa6 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-entries.markdown @@ -0,0 +1,108 @@ +# Session: Get Time Series Entries + +--- + +{NOTE: } + +To get a range of time series entries, use one of the `TimeSeriesFor.Get` methods. + +{INFO: } + +* [Include](../../../../../document-extensions/timeseries/client-api/session/include/overview) + time series data while [loading](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load) + or [querying](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query) + documents, to keep the data locally in the client's session and refrain from unnecessary additional trips to the server. +* When caching is enabled, time series data is kept in the session cache as well. + +{INFO/} + +* In this page: + * [`TimeSeriesFor.Get`](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#timeseriesfor.get) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#usage-flow) + * [Usage Samples](../../../../../document-extensions/timeseries/client-api/session/get/get-entries#usage-samples) + +{NOTE/} + +--- + +{PANEL: `TimeSeriesFor.Get`} + +`TimeSeriesFor.Get` retrieves a range of entries from a single time series. + +* To retrieve multiple series' data, use the + [GetMultipleTimeSeriesOperation](../../../../../document-extensions/timeseries/client-api/operations/get/get-multiple-TS-data) + document-store operation. +* Retrieved data can be sliced to **pages** to get time series entries + gradually, one custom-size page at a time. + +{PANEL/} + +{PANEL: Syntax} + +* There are two `TimeSeriesFor.Get` methods: + {CODE TimeSeriesFor-Get-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE TimeSeriesFor-Get-Strongly-Typed@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `from` | `DateTime?` | Range Start | + | `to` | `DateTime?` | Range End | + | `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. | + | `pagesize` | `int` | Paging page-size.
E.g. set `pagesize` to 10 to retrieve pages of 10 entries.
Default: int.MaxValue, for all time series entries. | + +* **Return Values** + * **`TimeSeriesEntry[]`** - an array of time series entry classes. + {CODE TimeSeriesEntry-Definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * **`TimeSeriesEntry[]`** + The [strongly-typed API](../../../../../document-extensions/timeseries/client-api/strongly-typed-api) + can be used to address retrieved values by name. + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session. +* Create an instance of `TimeSeriesFor`. + * Either pass `TimeSeriesFor` an explicit document ID, + -or- + Pass it an [entity tracked by the session](../../../../../client-api/session/loading-entities), + 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). + * Pass `TimeSeriesFor` the time series name. +* Call `TimeSeriesFor.Get`. + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample we retrieve all the entries of a time series, + using its parent-document's ID explicitly. + {CODE timeseries_region_Get-All-Entries-Using-Document-ID@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample we query for a document and get its "Heartrate" time series data. + {CODE timeseries_region_Pass-TimeSeriesFor-Get-Query-Results@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* Here we retrieve entries and use the strongly typed API to check their values + by name (as previously defined by the StockPrice structure). + We check whether a stock's closing-time price is rising over three trade days. + {CODE timeseries_region_Get-Strongly-Typed@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE Custom-Data-Type-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.markdown new file mode 100644 index 0000000000..920fa06d2c --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/get/get-names.markdown @@ -0,0 +1,76 @@ +# Session: Get Time Series Names + +--- + +{NOTE: } + +Get the names of a document's time series using +`Advanced.GetTimeSeriesFor`. + +* In this page: + * [`Advanced.GetTimeSeriesFor`](../../../../../document-extensions/timeseries/client-api/session/get/get-names#advanced.gettimeseriesfor) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/get/get-names#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/session/get/get-names#usage-flow) + * [Usage Sample](../../../../../document-extensions/timeseries/client-api/session/get/get-names#usage-sample) + +{NOTE/} + +--- + +{PANEL: `Advanced.GetTimeSeriesFor`} + +Use this method to get all the names of a document's time series. + +{PANEL/} + +{PANEL: Syntax} + +* **Definition** + {CODE GetTimeSeriesFor-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Description | + |:-------------|:-------------| + | `instance` | The document whose time series names you want to get | + +* **Return Value** + + **`List`** + An array of the loaded document's time series names. + +* **Exceptions** + If the instance is not tracked by the session, an `ArgumentException` exception is thrown. + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session. +* Load a document. +* Pass `Advanced.GetTimeSeriesFor` the loaded document. + +{PANEL/} + +{PANEL: Usage Sample} + +In this sample we load a user document and use `Advanced.GetTimeSeriesFor` +to get a list of its time series' names. +{CODE timeseries_region_Retrieve-TimeSeries-Names@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/.docs.json new file mode 100644 index 0000000000..fa86efa015 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/.docs.json @@ -0,0 +1,26 @@ +[ + { + "Path": "overview.markdown", + "Name": "Overview", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "with-session-load.markdown", + "Name": "With Load", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "with-session-query.markdown", + "Name": "With Query", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "with-raw-queries.markdown", + "Name": "With Raw Queries", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/overview.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/overview.markdown new file mode 100644 index 0000000000..4b9070849f --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/overview.markdown @@ -0,0 +1,33 @@ +# Session: Include Time Series + +--- + +{NOTE: } + +You can [Include](../../../../../client-api/session/loading-entities#load-with-includes) +documents' time series data while retrieving the documents. +The included data is held by the client's session, so it can +be handed to the user instantly when requested without issuing +an additional request to the server. + +* Time series data can be included while - + * [Loading a Document Using `session.Load`](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load) + * [Loading a Document By Query Via `session.Query`](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query) + * [Loading a Document By a Raw RQL Query Via `session.Advanced.RawQuery`](../../../../../document-extensions/timeseries/client-api/session/include/with-raw-queries) + +{NOTE/} + +## 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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-raw-queries.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-raw-queries.markdown new file mode 100644 index 0000000000..34716fa715 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-raw-queries.markdown @@ -0,0 +1,77 @@ +# Session: Include Time Series With Raw Queries + +--- + +{NOTE: } + +You can include time series data while running a raw RQL query +via `session.Advanced.RawQuery`. + +* [Include Time Series Data with `Advanced.RawQuery`](../../../../../document-extensions/timeseries/client-api/session/include/with-raw-queries#include-time-series-data-with-advanced.rawquery) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/include/with-raw-queries#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/session/include/with-raw-queries#usage-flow) + * [Usage Samples](../../../../../document-extensions/timeseries/client-api/session/include/with-raw-queries#usage-sample) + +{NOTE/} + +--- + +{PANEL: Include Time Series Data with `Advanced.RawQuery`} + +To include time series data while querying via `Advanced.RawQuery`, +use the `include timeseries` expression in your RQL query. + +{PANEL/} + +{PANEL: Syntax} + +* **`Advanced.RawQuery`** + * **Definition** + {CODE RawQuery-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `query` | string | Raw RQL Query | + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session +* Call `session.Advanced.RawQuery` + Use `include timeseries` in your query +* Pass `include timeseries` its arguments: + * **Time series name** + * **Range start** + * **Range end** + +{PANEL/} + +{PANEL: Usage Sample} + +In this sample, we use a raw query to retrieve a document +and include entries from the document's "Heartrate" time series. + +{CODE timeseries_region_Raw-Query-Document-And-Include-TimeSeries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +The entries we Get after the query, are retrieved +**from the session's cache**. + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-load.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-load.markdown new file mode 100644 index 0000000000..906647c963 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-load.markdown @@ -0,0 +1,90 @@ +# Session: Include Time Series With `Load` + +--- + +{NOTE: } + +You can include a time series or a part of it while loading a document +via `session.Load`. + +* [`session.Load` and `IncludeTimeSeries`](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load#session.load-and-includetimeseries) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load#usage-flow) + * [Usage Samples](../../../../../document-extensions/timeseries/client-api/session/include/with-session-load#usage-sample) + + +{NOTE/} + +--- + +{PANEL: `session.Load` and `IncludeTimeSeries`} + +To include time series data while retrieving documents via `session.Load`, +pass `session.Load` the `IncludeTimeSeries` method of the `IIncludeBuilder` +interface as an argument. + +{PANEL/} + +{PANEL: Syntax} + +* **`session.Load`** + * **Definition** + {CODE Load-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `id` | `string` | Document ID | + | `includes` | `Action>` | Include Object | + +* **`IncludeTimeSeries`** + * **Definition** + {CODE IncludeTimeSeries-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `name` | `string` | Time series Name | + | `from` | `DateTime?` | Time series range start
when null, `from` will default to `DateTime.MinValue`. | + | `to` | `DateTime?` | Time series range end

when null, `to` will default to `DateTime.MaxValue`. | + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session +* Call `session.Load` and pass it - + * The **Document ID** + * The **`IncludeTimeSeries`** method with its argumrnts: + **Time series name** + **Range start** + **Range end** + +{PANEL/} + +{PANEL: Usage Sample} + +In this sample, we load a document using `session.Load` and include +a selected range of entries from a time series named "Heartrate". +{CODE timeseries_region_Load-Document-And-Include-TimeSeries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +The entries we Get after including the time series, are retrieved +**from the session's cache**. + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-query.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-query.markdown new file mode 100644 index 0000000000..ee684e20e6 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/include/with-session-query.markdown @@ -0,0 +1,78 @@ +# Include Time Series With `Query` + +--- + +{NOTE: } + +You can include time series data while retrieving a document via `session.Query`. + +* [`session.Query` and `IncludeTimeSeries`](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query#session.query-and-includetimeseries) + * [Syntax](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query#syntax) + * [Usage Flow](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query#usage-flow) + * [Usage Samples](../../../../../document-extensions/timeseries/client-api/session/include/with-session-query#usage-samples) + +{NOTE/} + +--- + +{PANEL: `session.Query` and `IncludeTimeSeries`} + +To include time series data via `session.Query`, use `session.Query` +with the `Include` LINQ expression and pass it the `IncludeTimeSeries` +method of the `IQueryIncludeBuilder` interface as an argument. + +{PANEL/} + +{PANEL: Syntax} + +* **`IncludeTimeSeries`** + * **Definition** + {CODE IncludeTimeSeries-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `name` | `string` | Time series Name | + | `from` | `DateTime?` | Time series range start | + | `to` | `DateTime?` | Time series range end | + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session +* Call `session.Query`with the `Include` Linq expression + Pass it the `IncludeTimeSeries` method as an argument +* Pass `IncludeTimeSeries` its arguments: + * **Time series name** + * **Range start** + * **Range end** + +{PANEL/} + +{PANEL: Usage Samples} + +In this sample, we retrieve a document using `session.Query` and +**include** entries from the time series "Heartrate". +{CODE timeseries_region_Query-Document-And-Include-TimeSeries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +The entries we Get after including the time series, are retrieved +**from the session's cache**. + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.markdown new file mode 100644 index 0000000000..2f185963cf --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/patch.markdown @@ -0,0 +1,87 @@ +# Session: Patch Time Series Data + +--- + +{NOTE: } + +* To patch time series data to a document, use `session.Advanced.Defer`. + * You can pass `Defer` a script to Append, Get, and Remove time series entries. + * You can handle a single document at a time. + +* [Patching Using `session.Advanced.Defer`](../../../../document-extensions/timeseries/client-api/session/patch#patching-using-session.advanced.defer) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/patch#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/session/patch#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/session/patch#usage-samples) + +{NOTE/} + +--- + +{PANEL: Patching Using `session.Advanced.Defer`} + +{INFO: } + +* [Defer](../../../../client-api/operations/patching/single-document#non-typed-session-api) + is used for patching in general, not necessarily for time series data patching. +* To patch time series data, you need to [customize the JavaScript](../../../../document-extensions/timeseries/client-api/javascript-support) + that `Defer` uses. +* Learn more about time series JavaScript [here](../../../../document-extensions/timeseries/client-api/javascript-support). + +{INFO/} + +{PANEL/} + +{PANEL: Syntax} + +* **`PatchCommandData`** + * **Definition** + {CODE PatchCommandData-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + Learn more about `PatchCommandData` [here](../../../../client-api/operations/patching/single-document#non-typed-session-api). + +* **`PatchRequest`** + * **Definition** + {CODE PatchRequest-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + Learn more about `PatchRequest` [here](../../../../client-api/operations/patching/single-document#non-typed-session-api). + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session +* Call `session.Advanced.Defer` and pass it a `PatchCommandData` instance. +* Pass the `PatchCommandData` constructor method - + * the document ID + * the change vector (or `null`) + * a `PatchRequest` instance with a JavaScript that appends or removes time series entries. +* Call `session.SaveChanges()` to perform the patch. + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample, we pass `Defer`a script that appends a document 100 time series + entries with random heartrate values. + {CODE TS_region-Session_Patch-Append-100-Random-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample, we remove a range of 50 time series entries from a document. + {CODE TS_region-Session_Patch-Remove-50-TS-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying-overview.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying-overview.markdown new file mode 100644 index 0000000000..a4399caef4 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/querying-overview.markdown @@ -0,0 +1,170 @@ +# Session: Time Series Querying Overview +--- + +{NOTE: } + +* **LINQ Queries** + To query time series using LINQ expressions, use `session.Query`. + RavenDB will translate a LINQ query to RQL before transmitting + it to the server for execution. +* **RQL Queries** + Clients can express time series queries in RQL and send them to the server + for execution using the `session.Advanced.RawQuery` method. + +{INFO: } +Learn more about time series queries in the [section dedicated to this subject](../../../../document-extensions/timeseries/querying/queries-overview). +{INFO/} + +* In this page: + * [Time Series LINQ Queries](../../../../document-extensions/timeseries/client-api/session/querying-overview#time-series-linq-queries) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/querying-overview#syntax) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/session/querying-overview#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/session/querying-overview#usage-samples) + * [Client Raw RQL Queries](../../../../document-extensions/timeseries/client-api/session/querying-overview#client-raw-rql-queries) + * [RQL Queries Syntax](../../../../document-extensions/timeseries/client-api/session/querying-overview#rql-queries-syntax) + * [RQL Queries Usage Flow](../../../../document-extensions/timeseries/client-api/session/querying-overview#rql-queries-usage-flow) + * [RQL Queries Usage Samples](../../../../document-extensions/timeseries/client-api/session/querying-overview#rql-queries-usage-samples) + +{NOTE/} + +--- + +{PANEL: Time Series LINQ Queries} + +To build a time series LINQ query, run a document query using `session.Query` +and extend it using LINQ expressions. +Here is a simple LINQ query that chooses users by their age and retrieves their +HeartRate time series, and the RQL equivalent for this query. + +{CODE-TABS} +{CODE-TAB:csharp:LINQ ts_region_LINQ-1-Select-Timeseries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +{CODE-TAB:csharp:RQL ts_region_LINQ-2-RQL-Equivalent@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} +{CODE-TABS/} + +{PANEL/} + +{PANEL: Syntax} + +`session.Query` Definition: +{CODE Query-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +Learn more about `session.Query` [here](../../../../client-api/session/querying/how-to-query#session.query). + +**Return Value**: + +* **`IRavenQueryable`** for aggregated data. + When the query + [aggregates time series entries](../../../../document-extensions/timeseries/querying/aggregation-and-projections), + the results are returned in an aggregated array. +* **`IRavenQueryable`** for non-aggregated data. + When the query **doesn't aggregate** time series entries, + the results are returned in a list of time series results. + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session +* Call `session.Query`. + - Run a document query to locate documents whose time series you want to query. + - Extend the query using LINQ expressions to find and project time series data. + Start with `Select` to choose a time series. +* Retrieve the results using - + `TimeSeriesAggregationResult` for aggregated data + -or- + `TimeSeriesRawResult` for non-aggregated data +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample, we select a three-days range from the HeartRate time series. + {CODE ts_region_LINQ-3-Range-Selection@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* The first occurance of `Where` in the following example, filters documents. + The second occurance of `Where` filters entries. + {CODE ts_region_LINQ-4-Where@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In the following sample, we group heart-rate data of people above the age of 72 + into 1-day groups, and retrieve each group's average heartrate and number of measurements. + The aggregated results are retrieved into an `IRavenQueryable` array. + {CODE ts_region_LINQ-6-Aggregation@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: Client Raw RQL Queries} + +To send a raw RQL query to the server, use `session.Advanced.RawQuery`. +`RawQuery` transmits queries to the server without checking or altering +their contents, time series contents or otherwise + +{PANEL/} + +{PANEL: RQL Queries Syntax} + +* **`session.Advanced.RawQuery`** + * **Definition** + {CODE RawQuery-definition@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `query` | string | Raw RQL Query | + + * **Return Value**: + * **`IRawDocumentQuery`** for aggregated data. + When the query + [aggregates time series entries](../../../../document-extensions/timeseries/querying/aggregation-and-projections), + the results are returned in an aggregated array. + * **`IRawDocumentQuery`** for non-aggregated data. + When the query **doesn't aggregate** time series entries, + the results are returned in a list of time series results. + +{PANEL/} + +{PANEL: RQL Queries Usage Flow} + +* Open a session +* Call `session.Advanced.RawQuery` + Pass it your query +* Retrieve the results into + `TimeSeriesAggregationResult` for aggregated data + -or- + `TimeSeriesRawResult` for non-aggregated data +{PANEL/} + +{PANEL: RQL Queries Usage Samples} + +* In this sample, a raw RQL query retrieves 24 hours of HeartRate data from users under the age of 30. + The query does not aggregate data, so we retrieve its results using 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/} + +--- + +* In this sample, the query aggregates 7 days of HeartRate entries into 1-day groups. + From each group, two values are selected and projected to the client: the **min** + and **max** hourly HeartRate values. + The aggregated results are retrieved using a `TimeSeriesAggregationResult` array. + {CODE ts_region_Raw-Query-Aggregated@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/remove.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/remove.markdown new file mode 100644 index 0000000000..ebbd233b75 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/session/remove.markdown @@ -0,0 +1,96 @@ +# Session: Remove Time Series Data + +--- + +{NOTE: } + +Remove time series data using `TimeSeriesFor.Remove`. + +* You can remove a **single time series entry** or a **range of entries**. + +* In this page: + * [`TimeSeriesFor.Remove`](../../../../document-extensions/timeseries/client-api/session/remove#timeseriesfor.remove) + * [Syntax](../../../../document-extensions/timeseries/client-api/session/remove#syntx) + * [Usage Flow](../../../../document-extensions/timeseries/client-api/session/remove#usage-flow) + * [Usage Samples](../../../../document-extensions/timeseries/client-api/session/remove#usage-samples) +{NOTE/} + +--- + +{PANEL: `TimeSeriesFor.Remove`} + +`TimeSeriesFor.Remove` is used for the removal of time series and +time series entries. + +* There is no need to explicitly remove a time series; + the series is removed when all its entries are removed. +* Attempting to remove nonexistent entries results in a no-op, + generating no exception. + + +{PANEL/} + +{PANEL: Syntx} + +* There are two `TimeSeriesFor.Remove` methods: + * Remove a single time series entry. + {CODE TimeSeriesFor-Remove-definition-single-timepoint@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + * Remove a range of time series entries. + {CODE TimeSeriesFor-Remove-definition-range-of-timepoints@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `at` | `DateTime` | Timestamp of the time series entry you want to remove | + | `from` | `DateTime` | Remove the range of time series entries starting at this timestamp | + | `to` | `DateTime` | Remove the range of time series entries ending at this timestamp | + +* **Return Value** + No return value. + +* **Exceptions** + * `DocumentDoesNotExistException` is thrown If the document doesn't exist. + * Attempting to remove nonexistent entries results in a no-op and does not generate an exception. + +{PANEL/} + +{PANEL: Usage Flow} + +* Open a session. +* Create an instance of `TimeSeriesFor`. + * Either pass `TimeSeriesFor` an explicit document ID, + -or- + Pass it an [entity tracked by the session](../../../../client-api/session/loading-entities), + 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). + * Pass `TimeSeriesFor` the time series name. +* Call `TimeSeriesFor.Remove`. +* Call `session.SaveChanges` for the action to take effect on the server. + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample we remove a single entry from a time series. + {CODE timeseries_region_Remove-TimeSeriesFor-Single-Time-Point@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* In this sample we remove a range of entries from a time series. + {CODE timeseries_region_TimeSeriesFor-Remove-Time-Points-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/strongly-typed-api.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/strongly-typed-api.markdown new file mode 100644 index 0000000000..3c94dfa8c6 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/client-api/strongly-typed-api.markdown @@ -0,0 +1,112 @@ +# Strongly-Typed API + +{NOTE: } + +* Use the strongly-typed API to define time series types that can be used + by the time series methods (e.g. Append and Get) to address and manage + time series values by name. +* Register your time series types with the database record, so the Studio + would be able to present your time series values by their names. + +* In this page: + * [The Strongly-Typed API](../../../document-extensions/timeseries/client-api/strongly-typed-api#the-strongly-typed-api) + * [Defining a Time Series Type](../../../document-extensions/timeseries/client-api/strongly-typed-api#defining-a-time-series-type) + * [Registering a Time Series Type](../../../document-extensions/timeseries/client-api/strongly-typed-api#registering-a-time-series-type) + * [Usage Samples](../../../document-extensions/timeseries/client-api/strongly-typed-api#usage-samples) + +{NOTE/} + +--- + +{PANEL: The Strongly-Typed API} + +Many time series are populated with multiple values with each measurement. +Each GPS measurement, for example, would be appended to a route-tracking +time series with two values at least: the latitude and the longitude. + +Using the strongly-typed API to define time series types, and addressing +values by name, can create a clearer code and ease its management. + +* Name time series values in model classes that can be used as time series types. +* Call time series methods with your custom types, to address and manage values by name. + +{PANEL/} + +{PANEL: Defining a Time Series Type} + +To define a class that can be used as a time series type, mark the class +properties (values) with consecutive TimeSeriesValue indexes: TimeSeriesValue[0], +TimeSeriesValue[1], etc. + +E.g, - +{CODE Custom-Data-Type-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +The class can then be used by time series methods like Append. +{CODE timeseries_region_Append-Strongly-Typed-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: Registering a Time Series Type} + +Registering a custom time series type to the database record acquaints +it to the Studio, so when you view and manage time series values via the Studio +they would be presented by name. + +To register a time series type, call `store.TimeSeries.RegisterAsync`. + +* `store.TimeSeries.RegisterAsync` definition + {CODE RegisterAsync-Definitions@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* Parameters + + | Parameter | Type | Explanation + | --- | --- | --- | + | `TCollection` | Collection type | The time-series' collection + | `collection` | `string` | collection (when `TCollection` is not provided) + | `TTimeSeriesEntry` | Time series type | The custom time-series type + | `name` | `string ` | Time series name + | `valueNames` | `string[]` | Names (name per value) + +--- + +Here, for example, we register the `RoutePoint` type we've defined earlier. +{CODE timeseries_region_Strongly-Typed-Register@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +And this is the Studio Time Series view after appending a few RoutePoint coordinates. +!["Studio Time Series View"](images/time-series-view-coordinates.png "Studio Time Series View") + + +{PANEL/} + +{PANEL: Usage Samples} + +* In this sample we define a StockPrice type, and then use it while + appending StockPrice entries. + {CODE Custom-Data-Type-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE timeseries_region_Append-Strongly-Typed-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* And in this sample we Get StockPrice values by name to check whether a stock's closing-time + price over a three-day period indicates that the price is ascending. + {CODE timeseries_region_Get-Strongly-Typed@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* We use the custom StockPrice type in this query so we'd be able to + address retrieved values by name. + {CODE timeseries_region_Strongly-Typed-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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) + +**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.0/Raven.Documentation.Pages/document-extensions/timeseries/design.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/design.markdown new file mode 100644 index 0000000000..710182fb6f --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/design.markdown @@ -0,0 +1,201 @@ +# Design: Time Series + +--- + +{NOTE: } + +* Time series are sequences of numerical values, associated with timestamps + and sorted chronologically. + +* RavenDB Time Series are stored and managed as document extensions, gaining + much greater speed and efficiency than they would have had as JSON-formatted + data within a document. + +* In this page: + * [Time Series Structure](../../document-extensions/timeseries/design#time-series-structure) + * [Document Extension](../../document-extensions/timeseries/design#document-extension) + * [Time Series Entries](../../document-extensions/timeseries/design#time-series-entries) + * [The `HasTimeSeries` Flag](../../document-extensions/timeseries/design#the--flag) + * [Segmentation](../../document-extensions/timeseries/design#segmentation) + * [Compression](../../document-extensions/timeseries/design#compression) + * [Updating Time Series](../../document-extensions/timeseries/design#updating-time-series) + * [Document Change](../../document-extensions/timeseries/design#document-change) + * [Success](../../document-extensions/timeseries/design#success) + * [No Conflicts](../../document-extensions/timeseries/design#no-conflicts) + * [Transactions](../../document-extensions/timeseries/design#transactions) + +{NOTE/} + +--- + +{PANEL: Time Series Structure} + +--- + +#### Document Extension + +Each time series belongs to, or _extends_, one particular document. The +document and the time series reference each other through: + +* A **reference to the time series** in the document's metadata. + The time series' **name** is kept in the document's metadata. + The time series' **data** is stored in a separate location. +* A **reference to the document** in the time series data. + +--- + +#### Time Series Entries + +Each time series entry is composed of: + +* `TimeSeriesEntry` + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `Timestamp` | DateTime (UTC) | The time of the event or data represented by the entry. Time is measured up to millisecond resolution. | + | `Tag` | string | An optional tag for an entry. Can be any string up to 255 bytes. Possible uses for the tag: descriptions or metadata for individual entries; storing a document id, which can then be referenced when querying a time series. This is the only component of the entry that is not numerical. | + | `Values` | double[] | An array of up to 32 `double` values | + +{NOTE: } +Doubles with higher precision - i.e. more digits after the decimal point, +are much less compressible. +In other words, `1.672` takes up more space than `1672`. +{NOTE/} + +--- + +#### The `HasTimeSeries` Flag + +* When a document has one or more time series, RavenDB automatically adds + a `HasTimeSeries` flag in the document's metadata under `@flags`: + +{CODE-BLOCK: JSON} +{ + "Name": "Paul", + "@metadata": { + "@collection": "Users", + "@timeseries": [ + "my time series" + ] + "@flags": "HasTimeSeries" + } +} +{CODE-BLOCK/} + +* When all time series are removed from a document, RavenDB +automatically removes the flag. + +--- + +#### Segmentation + +At the server storage level, time series data is divided into **segments**. + +* Segments contain a number of consecutive entries from the same +time series. +* Segments have a maximum size of 2 KB. +* The 2 KB limit means that a segment can only contain up to 32k entries, +so a time series with more than 32k entries will always be stored in +multiple segments. +* In practice, segments usually contain far fewer than 32k entries, +the amount depends on the size of the entries (after compression). + * As an example - in the [Northwind sample dataset](../../studio/database/tasks/create-sample-data), + the _Companies_ documents all have a time series called _StockPrice_. + These time series are stored in segments that have ~10-20 entries each. +* The maximum gap between the first and last entries in a segment is +is ~24.86 days (`int.MaxValue` milliseconds). So if an entry is 24.86 days +or later than the first entry in the current segment, it will become the +first entry in a new segment. A consquence of this is that in a sparse time +series segments can be significantly smaller than 2 KB. + +Segments also store the aggregate values that summarize the data they +contain, such as the averages of entry values. For this reason, it's +often useful to reference individual segments in indexes and queries. +Read more about how to use segments [here](../../document-extensions/timeseries/indexing#object) + +--- + +#### Compression + +Time series data is stored using a format called [Gorilla compression](https://www.vldb.org/pvldb/vol8/p1816-teller.pdf). +On top of the Gorilla compression, the time series segments are compressed +using the [LZ4 algorithm](https://lz4.github.io/lz4/). + +{PANEL/} + +{PANEL: Updating Time Series} + +--- + +#### Document Change + +* **Name Change** + **Creating** or **removing** a time series adds or removes its name + from the metadata of the document it extends. + This modification counts as document-change event, and so it triggers + processes such as revisions. +* **Data Updates** + Modifying time series data does **not** invoke a document-change event, + as long as it doesn't create a new time series or remove an existing one. + +--- + +#### Success + +Updating a time series is designed to succeed without causing a concurrency conflict. +As long as the document it extends exists, updating a time series will always succeed. + +--- + +#### No Conflicts + +Time series actions do not cause conflicts. + +**Time series updated concurrently by multiple cluster nodes**: + +* When a time series' data is replicated by multiple nodes, the data +from all nodes is merged into a single series. +* When multiple nodes append **different values** at the same timestamp: + * If the nodes try to append a **different number of values** for the same + timestamp, the **bigger amount of values** is applied. + * If the nodes to append the same number of values, the first values from + each node are compared. The append whose first value sorts higher + [_lexicographically_](https://mathworld.wolfram.com/LexicographicOrder.html) + (not numerically) is applied. + For example, lexicographic order would sort numbers like this: + `1 < 10 < 100 < 2 < 21 < 22 < 3` + * If an existing value at a certain timestamp is deleted by one node + and updated by another node, the deletion is applied. + +**Time series update By multiple clients of the same node**: + +* When a time series' value at a certain timestamp is appended by +multiple clients more or less simultaneously, RavenDB uses the last-write +strategy. +* When an existing value at a certain timestamp is deleted by a client +and updated by another client, RavenDB still uses the last-write +strategy. + +--- + +#### Transactions + +When a session transaction that includes a time series modification +fails for any reason, the time series modification is reverted. + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/images/TSSnapshot.png b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/TSSnapshot.png new file mode 100644 index 0000000000..d02259442a Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/TSSnapshot.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.PNG b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.PNG new file mode 100644 index 0000000000..22e34099fe Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.PNG differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.snag b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.snag new file mode 100644 index 0000000000..4b903af031 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/images/rollup-1.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/indexing.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/indexing.markdown new file mode 100644 index 0000000000..b26198509d --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/indexing.markdown @@ -0,0 +1,196 @@ +# Indexing: Time Series + +--- + +{NOTE: } + +Time series indexes index time series [segments](../../document-extensions/timeseries/design#segmentation), +as opposed to document fields. +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). + +{INFO: } +Unlike document indexes, time series indexes currently support only LINQ syntax. +JavaScript syntax is not supported. + +RavenDB does not create [dynamic](../../studio/database/indexes/indexes-overview#indexes-types) +time series indexes in response to queries, but can be created as +[static](../../studio/database/indexes/indexes-overview#indexes-types) indexes from a +client application or from the Studio. +{INFO/} + +* In this page: + * [Syntax](../../document-extensions/timeseries/indexing#syntax) + * [`AbstractTimeSeriesIndexCreationTask`](../../document-extentions/timeseries/indexing#section) + * [`AbstractMultiMapMultiMapIndexCreationTask`](../../document-extensions/timeseries/indexing#section-1) + * [`TimeSeriesIndexDefinition`](../../document-extensions/timeseries/indexing#section-2) + * [`TimeSeriesSegment` Object](../../document-extensions/timeseries/indexing#object) + * [Samples](../../document-extensions/timeseries/indexing#samples) + +{NOTE/} + +--- + +{PANEL: Syntax } + +The are two main ways to create a time series index: + +1. Create a class that inherits from + * [`AbstractTimeSeriesIndexCreationTask`](../../document-extensions/timeseries/indexing#section) for [map](../../indexes/map-indexes) and + [map-reduce](../../indexes/map-reduce-indexes) time series indexes. + * [`AbstractMultiMapMultiMapIndexCreationTask`](../../document-extensions/timeseries/indexing#section-1) for [multi-map](../../indexes/multi-map-indexes) time series indexes. + +2. Create a [`TimeSeriesIndexDefinition`](../../document-extensions/timeseries/indexing#section-2). + +--- + +### `AbstractTimeSeriesIndexCreationTask` + +{CODE-BLOCK: csharp} +public abstract class AbstractTimeSeriesIndexCreationTask : + AbstractIndexCreationTaskBase +{ + protected void AddMap(string timeSeries, + Expression, + IEnumerable>> map); + + protected void AddMapForAll(Expression, + IEnumerable>> map); +} + +// Index only time series that belong to documents +// of a specified type +public class AbstractTimeSeriesIndexCreationTask { } + +// Specify both a document type and a reduce type +public class AbstractTimeSeriesIndexCreationTask { } +{CODE-BLOCK/} + +| Method | Parameters | Description | +| - | - | - | +| `AddMap()` | `string timeseries`, `Expression map` | Sets a map function for all time series in the database with specified name (the first parameter) | +| `AddMapForAll()` | `Expression map` | Sets a map function for all time series in the database | + +See the example [below](../../document-extensions/timeseries/indexing#section-3). + +--- + +### `AbstractMultiMapTimeSeriesIndexCreationTask` + +{CODE-BLOCK: csharp} +public abstract class AbstractMultiMapTimeSeriesIndexCreationTask +{ + protected void AddMap(string timeSeries, + Expression, + IEnumerable>> map); + + protected void AddMapForAll( + Expression, + IEnumerable>> map); +} + +// Specify a type for the reduce result +public abstract class AbstractMultiMapTimeSeriesIndexCreationTask { } +{CODE-BLOCK/} + +| Method | Parameters | Description | +| - | - | - | +| `AddMap()` | `string timeseries`, `Expression map` | Sets a map function for all time series with the specified name (the first parameter) that belong to documents with the type `TSource` | +| `AddMapForAll()` | `Expression map` | Sets a map function for all time series that belong to documents with either the type `TBase` _or_ any type that inherits from `TBase` | + +See the example [below](../../document-extensions/timeseries/indexing#section-4). + +--- + +### `TimeSeriesIndexDefinition` + +{CODE-BLOCK: csharp} +public class TimeSeriesIndexDefinition : IndexDefinition +{CODE-BLOCK/} + +For now, `TimeSeriesIndexDefinition` is functionally equivalent to the +[normal `IndexDefinition`](../../indexes/creating-and-deploying#using-maintenance-operations). +Using it for time series indexes is recommended - it exists in case additional functionality is +added in future versions of RavenDB. + +See the example [below](../../document-extensions/timeseries/indexing#samples). + +--- + +### `TimeSeriesSegment` object + +When indexing time series entries, they are accessed through a subdivision of the time series +called a _segment_. In general the LINQ syntax looks somethintg like this: + +{CODE-BLOCK: sql} +from segment in timeseries +from entry in segment +{CODE-BLOCK/} + +Segments are useful because they can be referenced within time series indexes to access the entries in +the segment, as well as some aggregated values that summarize the data in the segment: + +| Property | Type | Description | +| - | - | - | +| DocumentId | string | The [ID](../../client-api/document-identifiers/working-with-document-identifiers) of the document this time series belongs to | +| Name | string | The name of the time series this segment belongs to | +| Min | double[] | The smallest values from all entries in the segment. The places in this array correspond to the | +| Max | double[] | The largest values from all entries in the segment | +| Sum | double[] | The sums of values from all entries in the segment. The first `Sum` is the sum of all first values, and so on. | +| Count | int | The number of entries in this segment | +| Start | DateTime | The timestamp of the first entry in the segment | +| End | DateTime | The timestamp of the last entry in the segment | +| Entries | `TimeSeriesEntry[]` | The segment's entries themselves | + +These are the properties of a `TimeSeriesEntry`, which are exposed in the LINQ syntax: + +{CODE-BLOCK: csharp} +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/} + +{PANEL: Samples} +
+Creating a time series index using `TimeSeriesIndexDefinition`: +{CODE indexes_IndexDefinition@DocumentExtensions\TimeSeries\Indexing.cs /} + +#### `AbstractTimeSeriesIndexCreationTask` +{CODE indexes_CreationTask@DocumentExtensions\TimeSeries\Indexing.cs /} + +#### `AbstractMultiMapTimeSeriesIndexCreationTask` +{CODE indexes_MultiMapCreationTask@DocumentExtensions\TimeSeries\Indexing.cs /} + +#### Map-Reduce Time Series Index +{CODE indexes_MapReduce@DocumentExtensions\TimeSeries\Indexing.cs /} + +Yet another way to create a time series index is to create a +`TimeSeriesIndexDefinitionBuilder`, and use it to create a +`TimeSeriesIndexDefinition`. +{CODE indexes_IndexDefinitionBuilder@DocumentExtensions\TimeSeries\Indexing.cs /} +{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) +[Creating and Deploying Indexes](../../indexes/creating-and-deploying) +[Multi-Map Indexes](../../indexes/multi-map-indexes) +[Map-Reduce Indexes](../../indexes/map-reduce-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.0/Raven.Documentation.Pages/document-extensions/timeseries/overview.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/overview.markdown new file mode 100644 index 0000000000..27fe162386 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/overview.markdown @@ -0,0 +1,266 @@ +# Time Series Overview +--- + +{NOTE: } + +* A huge number of systems, including an expanding variety of IoT devices, + produce continuous streams of values that can be collected and used for + various needs. **Time series** are vectors of data points that are designated + to collect values over time, store them consecutively, and manage them + with high efficiency and performance. + +* RavenDB Time series can be managed and utilized using a thorough set of + [API methods](../../document-extensions/timeseries/client-api/overview), + the [Studio](../../studio/database/document-extensions/time-series), + and [various RavenDB features](../../document-extensions/timeseries/timeseries-and-other-features/time series-and-other-features-overview#time series-and-other-features---overview). + +* Time series data is **compressed** to lower storage usage and transaction time. + +* In this page: + * [Overview](../../document-extensions/timeseries/overview#overview) + * [RavenDB's Time Series Implementation](../../document-extensions/timeseries/overview#ravendbs-time-series-implementation) + * [Distrubuted Time Series](../../document-extensions/timeseries/overview#distrubuted-time-series) + * [Time Series as Document Extensions](../../document-extensions/timeseries/overview#time-series-as-document-extensions) + * [Time Series Features](../../document-extensions/timeseries/overview#time-series-features) + * [Time Series Data](../../document-extensions/timeseries/overview#time-series-data) + * [Separate Name and Data Storage](../../document-extensions/timeseries/overview#separate-name-and-data-storage) + * [Time Series Segments](../../document-extensions/timeseries/overview#time-series-segments) + * [Transactions Performance](../../document-extensions/timeseries/overview#transactions-performance) + * [Common-Queries Performance](../../document-extensions/timeseries/overview#common-queries-performance) + * [Time Series Entries](../../document-extensions/timeseries/overview#time-series-entries) + * [Timestamps](../../document-extensions/timeseries/overview#timestamps) + * [Values](../../document-extensions/timeseries/overview#values) + * [Tags](../../document-extensions/timeseries/overview#tags) + +{NOTE/} + +--- + +{PANEL: Overview} + +Time series can be **aggregated** and **queried** to illustrate process +behavior, predict future developments, track noticeable value changes, +and create other helpful statistics. + +Here are a few examples for value streams that can be easily and effectively +handled by time series. + +* _A sequence of heartrate values can be collected from a smart + wrist-watch_, and be used to build a person's training program. +* _Weather-stations' measurements_ collected over a chosen time period + can be compared to equivalent past periods to predict the weather. +* _Bandwidth usage reports of a home cable modem monitor_ can be used + to build a better charging plan. +* _Coordinates sent by delivery trucks' GPS trackers_ can be collected + and analyzed to secure the vehicles and improve the service. +* _Daily changes in stock prices_ can be used to build investment plans. + +## RavenDB's Time Series Implementation + +Time series functionality is fully integrated into RavenDB's +distributed environment and document model. + +--- + +#### Distrubuted Time Series + +Distributed clients and nodes can modify time series concurrently; the +modifications are merged by the cluster [without conflict](../../document-extensions/timeseries/design#no-conflicts). + +--- + +#### Time Series as Document Extensions + +RavenDB’s Time Series, like its +[distributed counters](../../client-api/session/counters/overview), +[attachments](../../client-api/session/attachments/what-are-attachments) +and [document revisions](../../client-api/session/revisions/what-are-revisions), +are **document extensions**. + +* A time series always extends a single specific document. + The context and source of the time series can be kept clear this way, + and time series management can use the comfort and strength of the + document interface. + A barometer's specifications document, for example, can be the parent + document for a time series that is populated with measurements taken + by a barometer of this specification. + +* Like the other document extensions, time series can take part in fully + transactional operations. + +--- + +#### Time Series Features + +Notable time series features include - + +* **Highly-Efficient Storage Management** + Time series data is [compressed](../../document-extensions/timeseries/design#compression) + and [segmented](../../document-extensions/timeseries/overview#time-series-segments) + to minimize storage usage and transmission time. +* **A Thorough Set of API Methods** + The [time series API](../../document-extensions/timeseries/client-api/overview)** + includes a variety of `session methods` and `store operations`. +* **Full GUI Support** + Time series can be viewed and managed using the [Studio](../../studio/database/document-extensions/time-series). +* **Time Series Querying and Aggregation** + * [High-performance common queries](../../document-extensions/timeseries/overview#common-queries-performance) + The results of a set of common queries are prepared in advance in time series segments' + headers, so the response to querying for a series **minimum value**, for example, is + returned nearly instantly. + * [LINQ and raw RQL queries](../../document-extensions/timeseries/querying/overview-and-syntax) + Flexible queries and aggregations can be executed using LINQ expressions and raw RQL + over time series **timestamps**, **tags** and **values**. +* **Time Series Indexing** + Time series can be [indexed](../../document-extensions/timeseries/indexing). +* [Rollup and Retention Policies](../../document-extensions/timeseries/rollup-and-retention) + * **Rollup Policies** + You can set time series rollup policies to aggregate large series into + smaller sets by your definitions. + * **Retention Policies** + You can set time series retention policies to automatically remove + time series entries that have reached their expiration date/time. +* [Including Time Series](../../document-extensions/timeseries/client-api/session/include/overview) + You can include (pre-fetch) time series data while loading documents. + Included data is held by the client's sesion, and is delivered to the + user with no additional server calls. +* **Patching** + You can patch time series data to your documents. + (visit the [API documentation](../../document-extensions/timeseries/client-api/overview) to learn more). + +{PANEL/} + +{PANEL: Time Series Data} + +Time series **names** are kept in their parent documents' metadata, while their +**data** is kept [separately](../../document-extensions/timeseries/overview#separate-name-and-data-storage). +Time series data is **compressed** and composed of consecutive +[segments](../../document-extensions/timeseries/overview#time-series-segments) and +[entries](../../document-extensions/timeseries/overview#time-series-entries). + +{PANEL/} + +{PANEL: Separate Name and Data Storage} + +The separation of names and data prevents time series value updates from +invoking document-change events, keeping documents' availability and performance +whatever size their time series grow to be and however frequent their value-updates +are. + +{PANEL/} + +{PANEL: Time Series Segments} + +Time series are composed of consecutive **segments**. +When a time series is created, its values are held in a single segment. +As the number of values grow (or when a certain amount of time has passed +since the last entry appendage), segments are added to the series. + +{INFO: } +Segments are managed automatically by RavenDB, clients do not need to do +anything in this regard. +{INFO/} + +--- + +#### Transactions Performance + +Time series segmentation heightens performance and minimizes transaction +and query time, since only the relevant segments of even a very long series +would be retrieved and queried, and only relevant segments would be updated. + +--- + +#### Common Queries Performance +Segmentation also helps provide results for common queries extremely +fast, since results for such queries as `Min`, `Max`, `Average` and +others are automatically stored and updated in segment headers, and +are always available for instant retrieval. + +{PANEL/} + +{PANEL: Time Series Entries} + +Each time series segment is composed of consecutive **time series entries**. +Each entry is composed of a **timestamp**, 1 to 32 **values**, and an **optional tag**. + + +--- + +#### Timestamps + +{INFO: } +A single `DateTime` timestamp marks each entry in a millisecond precision. +{INFO/} + +Timestamps, and therefore time series entries, are always ordered **by time**, +from the oldest timestamp to the newest. +E.g. in a heartrate time series, timestamps would indicate the time in which each +heartrate measurement has been taken. + +--- + +#### Values + +{INFO: } +Up to 32 `double` **values** can be appended per-entry. +{INFO/} + +We allow storing as many as 32 values per entry, since appending multiple +values may be a requirement for some time series. Here are a few examples. + +* A heart-rate time series + An entry with a single value (the heart-rate measurement taken by + a smart wrist-watch) is added to the time series every minute. + +* A truck-route time series + An entry with 2 values (the latitude and longitude reported by + a GPS device) is added to the time series every minute. + +* A stock-price time series + An entry with 5 values (stock price when the trade starts and + ends, its highest and lowest prices during the day, and its daily + trade volume) is added to the time series every day. + +--- + +#### Tags + +{INFO: } +A single **optional** `string` tag can be added per entry. +{INFO/} + +Tags are designated to provide information regarding their entries. +A tag can be a **short descriptive text**. +A tag can also be a **reference to a document** by the document's ID. + +Using tags as references to documents, **is the preferabble way to use them**. +Here is why. + +* The short (ID-long) reference, e.g. "watches/fitbit", refers us + to a text that is as long and as structured as we'd like it to be. +* While time series entries are queried, the query can load the + documents their tags refer to and filter the results by the + documents' contents. + E.g., the query can - + **1.** load time series entries whose tags refer to device-specification documents. + **2.** retrieve and examine the specification document referred to by each entry. + **3.** project to the client only values measured by Japanese devices. + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/.docs.json new file mode 100644 index 0000000000..285a4a65de --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/.docs.json @@ -0,0 +1,32 @@ +[ + { + "Path": "overview-and-syntax.markdown", + "Name": "Overview and Syntax", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "choosing-query-range.markdown", + "Name": "Choosing Query Range", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "filtering.markdown", + "Name": "Filtering", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "aggregation-and-projections.markdown", + "Name": "Aggregation and Projections", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + }, + { + "Path": "indexed-queries.markdown", + "Name": "Indexed Queries", + "DiscussionId": "b399492f-c034-4406-810c-58ecd8c59115", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.markdown new file mode 100644 index 0000000000..338659e18b --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/aggregation-and-projections.markdown @@ -0,0 +1,191 @@ +# Querying: Aggregaring and Projecting Time Series + +--- + +{NOTE: } + +* **Aggregation** + Queries can easily create powerful statistics by aggregating time series + into groups by chosen time frames like an hour or a week, and retrieving + values from each group by criteria like `Min` for the lowest value, + `Count` for the number of values in the group, etc. + +* **Projection** by criteria + Queries can explicitly select the criteria by which values would be retrieved + and projected to the client. + When a query does **not** select specific criteria, RavenDB will consider it + an implicit selection of **all** criteria and project to the client the values + from each group, that match each criteria. + + {INFO: Projecting values from Aggregated and Non-Aggregated result-sets} + + * When values are selected from a time series (or a range of time series + entries) that **has** been aggregated, they are selected per-group. + * When values are selected from a series or a range that **hasn't** + been aggregated, they are selected from the entire result-set. + + {INFO/} + + + + +* In this page: + * [Aggregation and Projection](../../../document-extensions/timeseries/querying/aggregation-and-projections#aggregation-and-projections) + * [Client Usage Samples](../../../document-extensions/timeseries/querying/aggregation-and-projections#client-usage-samples) + +{NOTE/} + +--- + +{PANEL: Aggregation and Projection} + +In an RQL query, use the `group by` expression to aggregate +time series (or ranges of time series entries) in groups by +a chosen resolution, and the `select` keyword to choose and +project entries by a chosen criteria. + +{INFO: You can aggregate entries by these time units:} + +* **Milliseconds** +* **Seconds** +* **Minutes** +* **Hours** +* **Days** +* **Months** +* **Quarters** +* **Years** + +{INFO/} + +{INFO: You can `select` values for projection by these criteria:} + +* **Min()** - the lowest value +* **Max()** - the highest value +* **Sum()** - sum of all values +* **Average()** - average value +* **First()** - values of the first series entry +* **Last()** - values of the last series entry +* **Count()** - overall number of values in series entries + +{INFO/} + +* In this sample, we group entries of users' HeartRate time series + and project the lowest and highest values of each group. + Each HeartRate entry holds a single value. + {CODE-BLOCK: JSON} +from Users as u where Age < 30 + select timeseries( + from HeartRate between + '2020-05-17T00:00:00.0000000Z' + and '2020-05-23T00:00:00.0000000Z' + where Tag == 'watches/fitbit' + group by '1 days' + select min(), max() + ) + {CODE-BLOCK/} + * **group by '1 days'** + We group each user's HeartRate time series entries in consequtive 1-day groups. + * **select min(), max()** + We select the lowest and highest values of each group and project them to the client. + +* In this sample, we group entries of companies' StockPrice time series + in consequtive 7-day groups and project the highest and lowest values + of each group. + Each StockPrice entry holds five values, the query returns the `Max` + and `Min` values of each: + Values[0] - **Open** - stock price when the trade opens + Values[1] - **Close** - stock price when the trade ends + Values[2] - **High** - highest stock price during trade time + Values[3] - **Low** - lowest stock price during trade time + Values[4] - **Volume** - overall trade volume + {CODE-BLOCK: JSON} +declare timeseries SP(c) +{ + from c.StockPrice + 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) + {CODE-BLOCK/} + * **where Values[4] > 500000** + Query stock price behavior when the trade volume is high. + * **group by '7 day'** + Group each company's StockPrice entries in consequtive 7-day groups. + * **select max(), min()** + Select the highest (`Max`) and lowest (`Min`) + values of each group and project them to the client. + Since each entry holds 5 values, the query will project + 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.). + * **select c.Name, SP(c)** + Project the company's name along with the time series query + results to make the results easier to read and understand. + +* This sample is similar to the one above it, except that time series + entries are **not aggregated**, so the highest and lowest values are + collected not from each group but from the entire result-set. + {CODE-BLOCK: JSON} +declare timeseries SP(c) +{ + from c.StockPrice + where Values[4] > 500000 + select max(), min() +} +from Companies as c +where c.Address.Country = 'USA' +select c.Name, SP(c) + {CODE-BLOCK/} + * **select max(), min()** + Since there is no aggregation, the entire result-set is queried + and the results include only the all-time highest and lowest Open, + Close, High, Low and Volume values. + +{PANEL/} + +{PANEL: Client Usage Samples} + +{INFO: } +You can run queries from your client using raw RQL and LINQ. + +* Learn how to run a LINQ time series query [here](../../../document-extensions/timeseries/client-api/session/query/linq-queries). +* Learn how to run a raw RQL time series query [here](../../../document-extensions/timeseries/client-api/session/query/rql-queries). + +{INFO/} + +To aggregate time series entries, use `GroupBy()` in a LINQ query +or `group by` in a raw RQL query. +To select time series values for projection, use `Select()` in a LINQ query +or `select` in a raw RQL query. + +* Here we express the query we've discussed above using + LINQ and both RQL syntaxes. + {CODE-TABS} + {CODE-TAB:csharp:LINQ ts_region_LINQ-aggregation-and-projections-StockPrice@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE-TAB:csharp:Raw-RQL-Select-Syntax ts_region_Raw-RQL-Select-Syntax-aggregation-and-projections-StockPrice@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE-TAB:csharp:Raw-RQL-Declare-Syntax ts_region_Raw-RQL-Declare-Syntax-aggregation-and-projections-StockPrice@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {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) +[Filtering](../../../document-extensions/timeseries/querying/filtering) +[Indexed Time Series Queries](../../../document-extensions/timeseries/querying/indexed-queries) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.markdown new file mode 100644 index 0000000000..d0e41ed0e5 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/choosing-query-range.markdown @@ -0,0 +1,124 @@ +# Querying: Choosing Time Series Range + +--- + +{NOTE: } + +* Queries can be performed over whole time series or over a chosen range + of time series entries, e.g. only entries collected during the last 7 days. + +* In this page: + * [Choosing Query Range](../../../document-extensions/timeseries/querying/choosing-query-range#choosing-query-range) + * [Client Usage Samples](../../../document-extensions/timeseries/querying/choosing-query-range#client-usage-samples) + * [Choosing a Range Using LINQ](../../../document-extensions/timeseries/querying/choosing-query-range#choosing-a-range-using-linq) + * [Choosing a Range Using Raw RQL](../../../document-extensions/timeseries/querying/choosing-query-range#choosing-a-range-using-raw-rql) + +{NOTE/} + +--- + +{PANEL: Choosing Query Range} + +In an RQL query, use `between` and `and` to specify a range of time series +entries to query. The entries are chosen by their timestamps, in UTC format. + +{CODE-BLOCK: JSON} +from Users as jog where Age < 30 +select timeseries( + from HeartRate + between + '2020-05-27T00:00:00.0000000Z' + and + '2020-06-23T00:00:00.0000000Z' +{CODE-BLOCK/} + + * `between '2020-05-27T00:00:00.0000000Z' and '2020-06-23T00:00:00.0000000Z'` + Retrieve all entries between these two timestamps. + + {INFO: } + You can use the Studio to try these queries. + Using the studio, you can use parameters for a clearer query. + E.g. - + {CODE-BLOCK: JSON} + $from = '2020-05-27T00:00:00.0000000Z' +$to = '2020-06-23T00:00:00.0000000Z' + +from Users as jog where Age < 30 +select timeseries( + from HeartRate + between $from and $to +) + {CODE-BLOCK/} + {INFO/} + +{PANEL/} + +{PANEL: Client Usage Samples} + +{INFO: } +You can run queries from your client using raw RQL and LINQ. + +* Learn how to run a LINQ time series query [here](../../../document-extensions/timeseries/client-api/session/query/linq-queries). +* Learn how to run a raw RQL time series query [here](../../../document-extensions/timeseries/client-api/session/query/rql-queries). + +{INFO/} + +--- + +#### Choosing a Range Using LINQ + +To choose a range as part of a LINQ query, pass `RavenQuery.TimeSeries` +a `from` and a `to` DateTime values. +Omitting these values will load the entire series. + +* **`RavenQuery.TimeSeries` Definitions** + {CODE RavenQuery-TimeSeries-Definition-Without-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE RavenQuery-TimeSeries-Definition-With-Range@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Parameters** + + | Parameters | Type | Description | + |:-------------|:-------------|:-------------| + | `documentInstance` | `object` | Document Instance | + | `name` | `string` | Time Series Name | + | `from` | `DateTime` | Range Start | + | `to` | `DateTime` | Range End | + +* In this sample, we select a three-days range from the HeartRate time series. + {CODE ts_region_LINQ-3-Range-Selection@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +--- + +#### Choosing a Range Using Raw RQL + +To choose a range as part of a raw RQL query, use the `between` and `and` keywords. + +In this sample, a raw RQL query chooses the profiles of users under the age of 30 and +retrieves a 24-hours range from each. +An **offset** is defined, adding two hours to retrieved timestamps to adjust them +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/} + +{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/indexed-queries) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.markdown new file mode 100644 index 0000000000..4a696f908f --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/filtering.markdown @@ -0,0 +1,114 @@ +# Querying: Filtering Time Series + +--- + +{NOTE: } + +* Time series entries can be filtered by their **value** (e.g. to + retrieve a "Thermometer" time series entries whose measurement exceed + 32 Celsius degrees) or **tag** (e.g. to retrieve all the entries whose + tag is "Thermometer No. 3"). + +* Entries can also be filtered by the **contents of a document they refer to**. + A time series entry's tag can contain the **ID of a document**. + A query can **load the document** that the entry refers to, check + its properties and filter time series entries by them. + +* In this page: + * [Filtering Results](../../../document-extensions/timeseries/querying/filtering#filtering) + * [Using Tags as References](../../../document-extensions/timeseries/querying/filtering#using-tags-as-references---) + * [Client Usage Samples](../../../document-extensions/timeseries/querying/filtering#client-usage-samples) + +{NOTE/} + +--- + +{PANEL: Filtering} + +In an RQL query, use the `where` keyword to filter time series entries +by their **tags** or **values**. + +{CODE-BLOCK: JSON} +from Users as u where Age < 30 +select timeseries( + from HeartRate + between '2020-05-27T00:00:00.0000000Z' + and '2020-06-23T00:00:00.0000000Z' + where Tag='watches/fitbit' +) +{CODE-BLOCK/} + +* `where Tag='watches/fitbit'` + Retrieve time series entries whose tag is 'watches/fitbit'. + To filter entries by their by value use **Value**, e.g.`where Value < 80`. + +--- + +#### Using Tags as References - `load tag` + +Use the `load Tag ` expression to **load a document** whose ID is stored in +a time series entry's tag. +Use `load Tag ` with `where` to **filter your results by properties of the +loaded document**, as we do in the following example. + +{CODE-BLOCK: JSON} +from Companies as Company where Company.Address.Country = "USA" +select timeseries( + from StockPrice + load Tag as Broker + where Broker.Title == "Sales Representative" + ) +{CODE-BLOCK/} + +* `load Tag as Broker` + Load the document each entry's tag refers to. + Here, we load profiles of potential stock brokers. +* `where Broker.Title == "Sales Representative"` + Filter time series entries so we remain with those + referring to sales representatives. + +{PANEL/} + +{PANEL: Client Usage Samples} + +{INFO: } +You can run queries from your client using raw RQL and LINQ. + +* Learn how to run a LINQ time series query [here](../../../document-extensions/timeseries/client-api/session/query/linq-queries). +* Learn how to run a raw RQL time series query [here](../../../document-extensions/timeseries/client-api/session/query/rql-queries). + +{INFO/} + +To filter results, use `Where()` in a LINQ query or `where` in a raw RQL query. +To filter results by a tag reference to a document, +use `LoadTag()` in a LINQ query or `load tag` in a raw RQL query. + +* In this sample, we send the query we + [presented above](../../../document-extensions/timeseries/querying/filtering#using-tags-as-references---) + to the server in raw RQL and in LINQ format. + + {CODE-TABS} + {CODE-TAB:csharp:LINQ ts_region_Filter-By-LoadTag-LINQ@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE-TAB:csharp:Raw-RQL ts_region_Filter-By-load-Tag-Raw-RQL@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {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/indexed-queries) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/indexed-queries.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/indexed-queries.markdown new file mode 100644 index 0000000000..ae19231983 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/indexed-queries.markdown @@ -0,0 +1,106 @@ +# Querying: Time Series & Static Indexes + +--- + +{NOTE: } + +* Time series [indexes](../../../document-extensions/timeseries/indexing) + are not generated automatically by the server, but static + indexes can be created by clients or using the Studio. As any other index, static + time series indexes can be queried. + +* Querying a time series index projects the contents of fields specified + in the index' `select` clause. The result-set can then be further filtered + using LINQ expressions. + +* In this page: + * [Indexed Queries](../../../document-extensions/timeseries/querying/indexed-queries#indexed-queries) + * [Syntax](../../../document-extensions/timeseries/querying/indexed-queries#syntax) + * [Usage Samples](../../../document-extensions/timeseries/querying/indexed-queries#usage-samples) + +{NOTE/} + +--- + +{PANEL: Indexed Queries} + +You can query time series indexes using `session.Query` and +`session.Advanced.DocumentQuery`, and enhance the queries +using LINQ expressions. + +{PANEL/} + +{PANEL: Syntax} + +* Definitions + + * `session.Query` + {CODE-BLOCK: JSON} + IRavenQueryable Query() where TIndexCreator : AbstractCommonApiForIndexes, new(); + {CODE-BLOCK/} + * `DocumentQuery` + {CODE-BLOCK: JSON} + IDocumentQuery DocumentQuery() where TIndexCreator : AbstractCommonApiForIndexes, new(); + {CODE-BLOCK/} + +* **Parameters** + + | Parameters | Description | + |:-------------|:-------------| + | `T` | Results Container | + | `TIndexCreator` | Index | + +* **Return Values** + + As return values are specific to each index, we need to define + a matching results container. + + In the following sample we define a **map index** that collects three fields from the "HeartRate" + time series, a "Results" container for the results, and an **index query** that uses both. + {CODE ts_region_Index-TS-Queries-6-Index-Definition-And-Results-Class@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE ts_region_Index-TS-Queries-1-session-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{PANEL/} + +{PANEL: Usage Samples} + +* **Indexed Queries** + To query a time series index, call `session.Query` or `session.Advanced.DocumentQuery`. + {CODE-TABS} + {CODE-TAB:csharp:session.Query ts_region_Index-TS-Queries-1-session-Query@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE-TAB:csharp:DocumentQuery ts_region_Index-TS-Queries-3-DocumentQuery@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + {CODE-TABS/} + + +* **Enhancing index queries** + + * When you call `session.Query`, You can add LINQ expressions to your query. + {CODE ts_region_Index-TS-Queries-2-session-Query-with-Linq@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + + * You can add LINQ-like expressions to a DocumentQuery as well. + {CODE ts_region_Index-TS-Queries-4-DocumentQuery-with-Linq@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +* **Async queries** + If you are coding in asynchronous manner, you can take leverage of the async support of our queries. + {CODE ts_region_Index-TS-Queries-5-session-Query-Async@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /} + +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.markdown new file mode 100644 index 0000000000..08cb01a074 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/querying/overview-and-syntax.markdown @@ -0,0 +1,184 @@ +# Querying: Time Series Querying Overview & Syntax + +--- + +{NOTE: } + +* Time series querying is native to RavenDB's RQL. + +* Clients can express time series queries in RQL and LINQ expressions to, + for example, expose the behavior of a process that populates a time series + over time, and to locate documents related to chosen time series entries. + +* Queries can be executed over time series indexes. + +* In this page: + * [Time Series Queries](../../../document-extensions/timeseries/querying/overview-and-syntax#time-series-queries) + * [Server and Client Queries](../../../document-extensions/timeseries/querying/overview-and-syntax#server-and-client-queries) + * [Dynamic and Indexed Queries](../../../document-extensions/timeseries/querying/overview-and-syntax#dynamic-and-indexed-queries) + * [Syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#syntax) + * [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#syntax-creating-a-time-series-section) + * [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#syntax-declaring-a-time-series-function) + + +{NOTE/} + +--- + +{PANEL: Time Series Queries} + +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 resolution, e.g. gather the prices + of a stock that's been collected over the past two months to week-long groups). +* 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. + +{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 **LINQ expressions** + (which will be automatically translated to RQL before their execution by the server). + +{PANEL/} + +{PANEL: Dynamic and Indexed Queries} + +Time series indexes are not created automatically by the server, but static time series +indexes can be created by clients (or using the Studio). + +* Use **dynamic queries** when time series you query are unindexed + or when you prefer that RavenDB would choose an index automatically + using its [query optimizer](../../../indexes/querying/what-is-rql#query-optimizer). E.g. - + {CODE-BLOCK: JSON} +//Look for time series named "HeartRate" in user profiles of users under 30. +from Users as u where Age < 30 + select timeseries( + from HeartRate +) + {CODE-BLOCK/} + +* [Indexed queries](../../../document-extensions/timeseries/querying/indexed-queries) + can be performed over static indexes and their results. E.g. - + {CODE-BLOCK: JSON} +from index 'SimpleIndex' + where Tag = 'watches/fitbit' + {CODE-BLOCK/} + +{PANEL/} + +{PANEL: Syntax} + +You can query time series using two equivalent syntaxes, +choose the syntax you're comfortable with. + +* [`select timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#syntax-creating-a-time-series-section) +* [`declare timeseries` syntax](../../../document-extensions/timeseries/querying/overview-and-syntax#syntax-declaring-a-time-series-function) + +--- + +#### `select timeseries` Syntax: Creating a Time Series Section + +This syntax allows you to encapsulate your query's time series functionality +in a `select timeseries` section. + +{CODE-BLOCK: JSON} +//Look for time series named "HeartRate" in user profiles of users under 30. + +from Users as u where Age < 30 +select timeseries( + from HeartRate +) +{CODE-BLOCK/} + +* `from Users as u where Age < 30` + This **document query** locates the documents whose time series we want to query. + + {INFO: } + A typical time series query starts by locating a single document. + For example, to query a stock prices time series we can locate + a specific company's profile in the Companies collection first, + and then query the StockPrices time series that extends this profile. + {CODE-BLOCK: JSON} + from Companies as c where Name = 'Apple' + select timeseries( + from StockPrices + ) + {CODE-BLOCK/} + {INFO/} + +* `select timeseries` + The `select` clause defines the time series query. + +* `from HeartRate` + The `from` keyword is used to select the time series we'd query, by its name. + +--- + +#### `declare timeseries` Syntax: Declaring a Time Series Function + +This syntax allows you to declare a time series function and call it +from your query. It introduces greater flexibility to your queries as +you can, for example, pass arguments to/by the time series function. + +Here is a query in both syntaxes. It picks users whose age is under 30, +and if they own a time series named "HeartRate" retrieves a range of entries +from this series. + + +| With Time Series Function | Without Time Series Function | +|:---:|:---:| +| {CODE-BLOCK: JSON} +declare timeseries ts(jogger){ + from jogger.HeartRate + between + '2020-05-27T00:00:00.0000000Z' + and + '2020-06-23T00:00:00.0000000Z' +} + +from Users as jog where Age < 30 +select ts(jog) +{CODE-BLOCK/}| {CODE-BLOCK: JSON} + from Users as jog where Age < 30 + select timeseries( + from HeartRate + between + '2020-05-27T00:00:00.0000000Z' + and + '2020-06-23T00:00:00.0000000Z') + {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) +[Indexed Time Series Queries](../../../document-extensions/timeseries/querying/indexed-queries) + +**Policies** +[Time Series Rollup and Retention](../../../document-extensions/timeseries/rollup-and-retention) diff --git a/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.markdown new file mode 100644 index 0000000000..171a9c7cd9 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/rollup-and-retention.markdown @@ -0,0 +1,209 @@ +# Time Series Rollup and Retention +--- + +{NOTE: } + +Many time series applications produce massive amounts of data at a steady rate. +**Time Series Policies** help you to 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 a time series' **Retention** - the amount of time that time series data +is kept before being deleted. + +* In this page: + * [Time Series Policies](../../document-extensions/timeseries/rollup-and-retention#time-series-policies) + * [Usage Flow and Syntax](../../document-extensions/timeseries/rollup-and-retention#usage-flow-and-syntax) + * [Samples](../../document-extensions/timeseries/rollup-and-retention#samples) + +{NOTE/} + +--- + +{PANEL: Time Series Policies} + +#### What are Rollups? + +A **rollup** is a time series that summarizes the data from another time series +by dividing time series entries into set units of time (like a second or a week). +Each entry in the rollup time series represents one of those units, and the data +from that unit in the original time series is aggregated into six values: + +* *First* - the value of the first entry in the unit. +* *Last* - the value of the last entry. +* *Min* - the smallest value. +* *Max* - the largest value. +* *Sum* - the sum of all the values in the unit. +* *Count* - the total number of entries in the unit. + +This results in a much more compact time series that still contains useful +information about the original time series (also called the "named" or "raw" +time series). Rollup time series are created automatically according to +**rollup policies**. Rollup policies apply to all documents in a collection, and +each collection can have multiple policies. + +Let's look at an example of rollup data: +
+!["Rollup time series entries"](images/rollup-1.png "A rollup time series' entries") + +**1) Values:** +Each group of six values represents one value in 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. 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. + +**2) Timestamp:** +The aggregation spans always begin at a round number of one of these time units: a +second, minute, hour, day, week, month, or year. So the span includes all entries +starting at a round number of time units, and ending at the next 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 span it +represents. + +For example, if the aggregation span is one day, the spans will start at times like: +`2020-01-01 00:00:00`, +`2020-01-02 00:00:00`, +`2020-01-03 00:00:00` etc. + +**3) Name:** +A rollup time series' name 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 a `@` character - in the image above these are +"Heartrate & Blood Pressure" and "ByMinute" respectively. For this reason, neither +a time series name nor a policy name can have the character `@` in it. + +{PANEL/} + +{PANEL: Usage Flow and Syntax} + +To configure time series policies for one or more collections: + +* Create time series policy [objects](../../document-extensions/timeseries/rollup-and-retention#the-two-types-of-time-series-policy). +* Use those to populate `TimeSeriesCollectionConfiguration` [objects](../../document-extensions/timeseries/rollup-and-retention#and-) +for each collection you want to configure. +* Use _those_ to populate a `TimeSeriesConfiguration` [object](../../document-extensions/timeseries/rollup-and-retention#and-) +which will belong to the whole database. +* Finally, use the `ConfigureTimeSeriesOperation` [operation](../../document-extensions/timeseries/rollup-and-retention#the-time-series-configuration-operation) +to send the new configurations to the server. +
+###Syntax + +####The two types of time series policy: + +{CODE-BLOCK: csharp} +// Rollup policies +public class TimeSeriesPolicy +{ + public string Name; + public TimeValue RetentionTime; + public TimeValue AggregationTime; +} + +// A retention policy for the raw TS +// Only one per collection +public class RawTimeSeriesPolicy : TimeSeriesPolicy +{ + public string Name; + public TimeValue RetentionTime; + // Does not perform aggregation +} +{CODE-BLOCK/} + +`TimeSeriesPolicy`: + +| Property | Description | +| - | - | +| `Name` | This `string` is used to create the names of the rollup time series created by this policy.
`Name` is added to the name of the raw time series - with `@` as a separator - to create the name of the resulting rollup time series. | +| `RetentionTime` | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +| `AggregationTime` | The time series data being rolled up is divided at round time units, into parts of this length of time. Each of these parts is aggregated into an entry of the rollup time series. | + +`RawTimeSeriesPolicy`: + +| Property | Description | +| - | - | +| `Name` | This `string` is used to create the names of the rollup time series created by this policy.
`Name` is added to the name of the raw time series - with `@` as a separator - to create the name of the resulting rollup time series. | +| `RetentionTime` | Time series entries older than this time span (see `TimeValue` below) are automatically deleted. | +
+####The `TimeValue` struct + +{CODE-BLOCK: csharp} +public struct TimeValue +{ + public static TimeValue FromSeconds(int seconds); + public static TimeValue FromMinutes(int minutes); + public static TimeValue FromHours(int hours); + public static TimeValue FromDays(int days); + public static TimeValue FromMonths(int months); + public static TimeValue FromYears(int years); +} +{CODE-BLOCK/} + +`Each of the above `TimeValue` methods returns a `TimeValue` object representing a +whole number of the specified time units. These are passed as the aggregation and +retention spans of time series policies. + +{INFO: } +The main reason we use `TimeValue` rather than something like `TimeSpan` is that +`TimeSpan` doesn't have a notion of 'months', because a calendar month is not a +standard unit of time (since it ranges from 28-31 days). `TimeValue` enables you +to define retention and aggregation spans for a calendar month. +{/INFO} +
+####`TimeSeriesCollectionConfiguration` and `TimeSeriesConfiguration` + +{CODE-BLOCK: csharp} +public class TimeSeriesCollectionConfiguration +{ + public bool Disabled; + public List Policies; + public RawTimeSeriesPolicy RawPolicy; +} + +public class TimeSeriesConfiguration +{ + public Dictionary Collections; +} +{CODE-BLOCK/} + +| Property | Description | +| - | - | +| `Disabled` | If set to `true`, rollup processes will stop, and time series data will not be deleted by retention policies. | +| `Policies` | Populate this `List` with your rollup policies | +| `RawPolicy` | The `RawTimeSeriesPolicy`, the retention policy for the raw time series | +| `Collections` | Populate this `Dictionary` with the `TimeSeriesCollectionConfiguration`s and the names of the corresponding collections. | +
+####The Time Series Configuration Operation + +{CODE-BLOCK: csharp} +public ConfigureTimeSeriesOperation(TimeSeriesConfiguration configuration); +{CODE-BLOCK/} + +Pass this your `TimeSeriesConfiguration`, see usage example below. How to use an [operation](../../client-api/operations/what-are-operations). + +{PANEL/} + +{PANEL: Samples} + +How to create time series policies for a collection and pass them to the server: + +{CODE rollup_and_retention_0@DocumentExtensions\TimeSeries\RollupAndRetention.cs /} + +How to access a rollup time series: + +{CODE rollup_and_retention_1@DocumentExtensions\TimeSeries\RollupAndRetention.cs /} +{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.0/Raven.Documentation.Pages/document-extensions/timeseries/time-series-and-other-features.markdown b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/time-series-and-other-features.markdown new file mode 100644 index 0000000000..bbea1b62f7 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/document-extensions/timeseries/time-series-and-other-features.markdown @@ -0,0 +1,141 @@ +# Time Series and Other Features + +--- + +{NOTE: } +* This page describes how time series interact with various other RavenDB +features. + +* In this page: + * [General Features](../../document-extensions/timeseries/time-series-and-other-features#general-features) + * [Smuggler](../../document-extensions/timeseries/time-series-and-other-features#smuggler) + * [Ongoing Tasks](../../document-extensions/timeseries/time-series-and-other-features#ongoing-tasks) + * [Revisions](../../document-extensions/timeseries/time-series-and-other-features#revisions) +{NOTE/} + +--- + +{PANEL: General Features} +Most RavenDB features apply to time series in ways analogous to other types of +data and document extensions. + +* The Document Session [tracks](../../client-api/session/what-is-a-session-and-how-does-it-work#tracking-changes) +changes to time series data. +* The [Changes API](../../client-api/changes/what-is-changes-api) service +is triggered by changes to time series data. +* Learn about how to **index** time series [here](../../document-extensions/timeseries/indexing). +* Learn about how to **query** time series data [here](../../document-extensions/timeseries/querying/overview-and-syntax). +* Learn how to **include** time series with `session.Load()` and in queries +[here](../../document-extensions/timeseries/client-api/session/include/overview). +{PANEL/} + +{PANEL: Smuggler} +[Smuggler](../../client-api/smuggler/what-is-smuggler) is a DocumentStore +property that can be used to export chosen database items to an external +file or to import database items from an existing file into the database. + +To [configure smuggler](../../client-api/smuggler/what-is-smuggler#databasesmugglerexportoptions) +to handle time series, add the paramater `DatabaseItemType.TimeSeries` +to the `OperateOnTypes` object. + +{CODE-BLOCK: csharp} +OperateOnTypes = DatabaseItemType.Documents + | DatabaseItemType.TimeSeries +{CODE-BLOCK/} +{PANEL/} + +{PANEL: Ongoing Tasks} +"[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info)" are +various automatic processes that operate on an entire database. Some of these +apply to time series data and some do not. +
+ +#### Tasks that apply to time series + +* [External replication](../../server/ongoing-tasks/external-replication) +creates a complete copy of a database, including documents and their extensions. +* [Pull replication](../../server/ongoing-tasks/pull-replication) is similar +to external replication except that the process is initiated by the +destination server rather than the source server. +* [Backup](../../client-api/operations/maintenance/backup/backup)s save the +whole database at a certain point in time and can be used to restore the +database later. All kinds of backups include time series data: "logical"-backup +and snapshot, full and incremental. + +#### Cannot be applied to time series + +* [ETL](../../server/ongoing-tasks/etl/basics) is a type of task that _extracts_ +some portion of the data from a database, _transforms_ it according to a script, +and _loads_ it to some external target. Neither the **RavenDB ETL** nor the +**SQL ETL** tasks can access or operate on time series data. +* [Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions) +send data to "worker" clients in batches. +{PANEL/} + +{PANEL: Revisions} + +[Revisions](../../client-api/session/revisions/what-are-revisions) are old +versions of a document. They can be saved manually or by setting a policy for +a collection that creates them automatically. + +Revisions do not preserve time series data, and editing a time series does +not trigger the creation of a new revision the way editing a document would. +This is because time series are designed so for new entries to be added +quickly and often, and creating revisions each time would significantly slow +this process down. + +However, revisions _can_ be triggered / created manually if a _new_ time series +is added to the document, or an existing time series is deleted. (Remember that +a time series is deleted by deleting all of its entries). +
+ +#### The   `@timeseries-snapshot` + +While revisions don't contain the time series data themselves, they do contain +few details about the time series the document had at the time. These details +appear as though they are part of the document's metadata, but it's not really +part of the document. When a revision is viewed in the studio, this +"time series snapshot" looks like this: + +![](images/TSSnapshot.png) + +This time series snapshot can also be accessed by loading a revision in the +client. This is the general JSON format of the time series snapshot: + +{CODE-BLOCK: json} +"@metadata": { + ... + "@timeseries-snapshot": { + "": { + "Count": , + "Start": "", + "End": "" + }, + "": { ... } + } +{CODE-BLOCK/} +{PANEL/} + +## Related articles + +### Time Series +[Time Series Overview](../../document-extensions/timeseries/overview) +[Include Time Series](../../document-extensions/timeseries/client-api/session/include/overview) +[Time Series Indexing](../../document-extensions/timeseries/indexing) +[Querying Time Series](../../document-extensions/timeseries/querying/overview-and-syntax) + +### Client-API +[Session Entity Tracking](../../client-api/session/what-is-a-session-and-how-does-it-work#tracking-changes) +[Changes API](../../client-api/changes/what-is-changes-api) +[Smuggler](../../client-api/smuggler/what-is-smuggler) +[Data Subscriptions](../../client-api/data-subscriptions/what-are-data-subscriptions) +[Revisions](../../client-api/session/revisions/what-are-revisions) + +### Server +[External replication](../../server/ongoing-tasks/external-replication) +[Pull replication](../../server/ongoing-tasks/pull-replication) +[Backup](../../client-api/operations/maintenance/backup/backup) +[ETL](../../server/ongoing-tasks/etl/basics) + +### Studio +[Ongoing tasks](../../studio/database/tasks/ongoing-tasks/general-info) diff --git a/Documentation/5.0/Raven.Documentation.Pages/indexes/querying/what-is-rql.markdown b/Documentation/5.0/Raven.Documentation.Pages/indexes/querying/what-is-rql.markdown new file mode 100644 index 0000000000..fc6e0622a0 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/indexes/querying/what-is-rql.markdown @@ -0,0 +1,362 @@ +# Querying: RQL - Raven Query Language +--- + +{NOTE: } + +Queries in RavenDB use an SQL-like language called **RQL** (Raven Query Language). + +* In this page: + * [Overview](../../indexes/querying/what-is-rql#overview) + * [Query Optimizer](../../indexes/querying/what-is-rql#query-optimizer) + * [Dynamic and Indexed Queries](../../indexes/querying/what-is-rql#dynamic-and-indexed-queries) + * [Queries Usage of Indexes](../../indexes/querying/what-is-rql#queries-usage-of-indexes) + * [RQL Keywords and Methods](../../indexes/querying/what-is-rql#rql-keywords-and-methods) + * [`declare`](../../indexes/querying/what-is-rql#declare) + * [`from`](../../indexes/querying/what-is-rql#from) + * [`group by`](../../indexes/querying/what-is-rql#group-by) + * [`where`](../../indexes/querying/what-is-rql#where) + * [`order by`](../../indexes/querying/what-is-rql#order-by) + * [`load`](../../indexes/querying/what-is-rql#load) + * [`select`](../../indexes/querying/what-is-rql#select) + * [`update`](../../indexes/querying/what-is-rql#update) + * [`include`](../../indexes/querying/what-is-rql#include) + * [`Keywords and Methods Summary`](../../indexes/querying/what-is-rql#keywords-and-methods) + +{NOTE/} + +--- + +{PANEL: Overview} + +RQL is designed to expose externally the RavenDB query pipeline in a way that is easy +to understand, easy to use, and not overwhelming to the user. + +{PANEL/} + +{PANEL: Query Optimizer} + +As soon as a query reaches a RavenDB instance, the instance calls its query optimizer to +analyze the query and determine which indexes should be used to retrieve the requested data. + +--- + +#### Dynamic and Indexed Queries + +RavenDB has two types of queries: + +* A **dynamic query**, e.g. ```from Orders where ...```, which gives the query optimizer + full freedom to choose which index the query will use. +* An **indexed query**, that specifies the index it would use. + E.g. ```from index 'Orders/ByCompany' where ...```, + which instructs RavenDB to use the ```Orders/ByCompany``` index. + +--- + +#### Queries Usage of Indexes + +In other databases, the query optimizer may fail to find a suitable index and fall back +into querying using a full scan. + +RavenDB doesn't include support for full scans. If an index cannot be found for a query, +the query optimizer will **create a new index for the query**. + +RavenDB queries will use the index they have created or found, to minimize response +time and return results at the same speed regardless of the size of the data. + +You can read more about indexes [here](../indexing-basics). + + +{NOTE: Exceptions: Time-Series and Counters} +Queries in RavenDB will always use an index, with the exception of [distributed time-series]() +and [distributed counters](). +Time-series and counters are **not** automatically indexed. They **can** be indexed manually. +When indexes are not created for them manually, time-series and counters are queried with no index. +{NOTE/} + +{NOTE: Indexing and queries in RavenDB } +Indexing in RavenDB is a **background operation**. +An yet-unindexed query will wait for the indexing process to complete (or timeout). +A query that can be answered using an existing index will proceed normally +using this index. +When the creation of a new index has caught up, RavenDB will remove all the +old indexes that are now superseded by the new index. +{NOTE/} + +{PANEL/} + +--- + +#RQL Keywords and Methods + +{PANEL: `declare`} + +The keyword `declare` gives you the ability to create a JavaScript function that can be reused in `select` (when projection is done). You can read more about it [here](../../client-api/session/querying/how-to-project-query-results#example-iv---projection-with-). + +{PANEL/} + +{PANEL: `from`} + +The keyword `from` is used to determine the source data that will be used when a query is executed. + +You have two options: + +* `from ` + This option is used to perform: + - Collection queries that perform just basic ID filtering. + When this is the case, there is no need to query an index + and the required document is returned directlry from the storage. + E.g. + `from Companies where id() == 'companies/1-A'` + - Dynamic queries that are executed using [auto indexs](../../indexes/creating-and-deploying#auto-indexes). + + {INFO:All Documents} + In order to query all documents, the `@all_docs` keyword can be used: + + - `from @all_docs where FirstName = 'Laura'` + - `from @all_docs where id() = 'companies/1-A'`. + {INFO/} + +* `from INDEX ` + This option is used to perform RQL operations with a specific index. + +{PANEL/} + +{PANEL: `group by`} + +The keyword `group by` is used to create an aggregation query. Please refer to the article about [dynamic group by queries](../../client-api/session/querying/how-to-perform-group-by-query) to find out more. + +{PANEL/} + +{PANEL: `where`} + +You can use the `where` keyword with various operators +to filter chosen documents from the final result-set. + +--- + +### Operator: `>=`, `<=`, `<>`, `!=`, `<`, `>`, `=`, `==` + +These basic operators can be used with all value types, including 'numbers' and 'strings'. + +You can, for example, return every document from the +[companies collection](../../client-api/faq/what-is-a-collection) +whose _field value_ **=** _a given input_. + +{CODE-BLOCK:csharp} +from Companies +where Name = 'The Big Cheese' +{CODE-BLOCK/} + +Filtering on **nested properties** is also supported, so in order to return all companies from 'Albuquerque' we need to execute following query: + +{CODE-BLOCK:csharp} +from Companies +where Address.City = 'Albuquerque' +{CODE-BLOCK/} + +--- + +### Operator: `between` + +The operator `between` returns results inclusively, and the type of border values used must match. It works on both 'numbers' and 'strings' and can be substituted with the `>=` and `<=` operators (see the example below). + +{CODE-BLOCK:csharp} +from Products +where PricePerUnit between 10.5 and 13.0 +{CODE-BLOCK/} + +or + +{CODE-BLOCK:csharp} +from Products +where PricePerUnit >= 10.5 and PricePerUnit <= 13.0 +{CODE-BLOCK/} + +--- + +### Operator: `in` + +The operator `in` is validating if a given field contains passed values. It will return results if a given field matches **any** of the passed values. + +{CODE-BLOCK:csharp} +from Companies +where Name IN ('The Big Cheese', 'Unknown company name') +{CODE-BLOCK/} + +{CODE-BLOCK:csharp} +from Orders +where Lines[].ProductName in ('Chang', 'Spegesild', 'Unknown product name') +{CODE-BLOCK/} + +--- + +### Operator: `all in` + +This operator checks if **all** passes values are matching a given field. Due to its mechanics, it is only useful when used on array fields. + +The following query will yield no results in contrast to an 'in' operator. + +{CODE-BLOCK:csharp} +from Orders +where Lines[].ProductName all in ('Chang', 'Spegesild', 'Unknown product name') +{CODE-BLOCK/} + +but removing the 'Unknown product name' will give you orders that only contains products with both 'Chang' and 'Spegesild' names + +{CODE-BLOCK:csharp} +from Orders +where Lines[].ProductName all in ('Chang', 'Spegesild') +{CODE-BLOCK/} + +--- + +### Binary Operators: `AND`, `OR`, `NOT` + +Binary operators can be used to build more complex statements. The `NOT` operator can only be used with one of the other binary operators creating `OR NOT` or `AND NOT` ones. + +{CODE-BLOCK:csharp} +from Companies +where Name = 'The Big Cheese' OR Name = 'Richter Supermarkt' +{CODE-BLOCK/} + +{CODE-BLOCK:csharp} +from Orders +where Freight > 500 AND ShippedAt > '1998-01-01' +{CODE-BLOCK/} + +{CODE-BLOCK:csharp} +from Orders +where Freight > 500 AND ShippedAt > '1998-01-01' AND NOT Freight = 830.75 +{CODE-BLOCK/} + +--- + +### Subclauses: `(`, `)` + +Subclauses can be used along with binary operators to build even more complex logical statements. They are self-explanatory so no example will be given. + +--- + +{PANEL/} + +{PANEL: `order by`} + +To perform sorting, `order by` must be used. +Read more about this subject in the [article dedicated to sorting](../../indexes/querying/sorting). + +{PANEL/} + +{PANEL: `load`} + +When there is a need to use data from an external document in projection, `load` can be used. Please refer to the following [projection article](../../indexes/querying/projections#example-vii---projection-using-a-loaded-document) to find out more about it. + +{PANEL/} + +{PANEL: `select`} + +Projections can be performed by using `select`. Please read our dedicated projection article [here](../../indexes/querying/projections). + +{PANEL/} + +{PANEL: `update`} + +To patch documents on the server-side, use `update` with the desired JavaScript script that will be applied to any documents matching the query criteria. For more information, please refer to our [patching article](../../client-api/operations/patching/set-based). + +{PANEL/} + +{PANEL: `include`} + +The keyword `include` has been introduced to support: + +- [including additional documents](../../client-api/how-to/handle-document-relationships#includes) or counters to the query response +- [highlighting](../../client-api/session/querying/how-to-use-highlighting) results +- query timings +- explanations + +{PANEL/} + +{PANEL: Keywords and Methods} + +The following keywords and methods are available in RQL: + +- DECLARE +- [FROM](../../indexes/querying/what-is-rql#from) + - INDEX +- [GROUP BY](../../indexes/querying/what-is-rql#group-by) + - [array()](../../client-api/session/querying/how-to-perform-group-by-query#by-array-content) +- [WHERE](../../indexes/querying/what-is-rql#where) + - id() + - [search()](../../indexes/querying/searching) + - cmpxchg() + - boost() + - [regex()](../../client-api/session/querying/how-to-use-regex) + - startsWith() + - endsWith() + - [lucene()](../../client-api/session/querying/document-query/how-to-use-lucene) + - [exists()](../../client-api/session/querying/how-to-filter-by-field) + - exact() + - [intersect()](../../indexes/querying/intersection) + - [spatial.within()](../../indexes/querying/spatial) + - [spatial.contains()](../../indexes/querying/spatial) + - [spatial.disjoint()](../../indexes/querying/spatial) + - [spatial.intersects()](../../indexes/querying/spatial) + - [moreLikeThis()](../../client-api/session/querying/how-to-use-morelikethis) +- [ORDER BY](../../indexes/querying/what-is-rql#order-by) + - [ASC | ASCENDING](../../indexes/querying/sorting#basics) + - [DESC | DESCEDING](../../indexes/querying/sorting#basics) + - [AS](../../indexes/querying/sorting#basics) + - [string](../../indexes/querying/sorting#basics) + - [long](../../indexes/querying/sorting#basics) + - [double](../../indexes/querying/sorting#basics) + - [alphaNumeric](../../indexes/querying/sorting#alphanumeric-ordering) + - [random()](../../indexes/querying/sorting#random-ordering) + - [score()](../../indexes/querying/sorting#ordering-by-score) + - [spatial.distance()](../../client-api/session/querying/how-to-query-a-spatial-index#orderbydistance) +- [LOAD](../../indexes/querying/what-is-rql#load) +- [SELECT](../../indexes/querying/what-is-rql#select) + - DISTINCT + - key() + - sum() + - count() + - [facet()](../../indexes/querying/faceted-search) +- [UPDATE](../../indexes/querying/what-is-rql#update) +- [INCLUDE](../../indexes/querying/what-is-rql#include) + +With the following operators: + +- >= +- <= +- <> or != +- < +- > +- = or == +- BETWEEN +- IN +- ALL IN +- OR +- AND +- NOT +- ( +- ) + +And the following values: + +- true +- false +- null +- string e.g. 'John' or "John" +- number (long and double) e.g. 17 +- parameter e.g. $param1 + +{PANEL/} + +## Related Articles + +### Client API + +- [How to Query](../../client-api/session/querying/how-to-query) +- [How to Use RQL Directly When Querying](../../client-api/session/querying/how-to-query#session.advanced.rawquery) + +### Querying + +- [Basics](../../indexes/querying/basics) diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/studio/database/.docs.json index 8da156927e..19fafe0a1b 100644 --- a/Documentation/5.0/Raven.Documentation.Pages/studio/database/.docs.json +++ b/Documentation/5.0/Raven.Documentation.Pages/studio/database/.docs.json @@ -5,6 +5,11 @@ "Mappings": [], "IsPlaceholder": "true" }, + { + "Path": "/document-extensions", + "Name": "Document Extensions", + "Mappings": [] + }, { "Path": "/settings", "Name": "Settings", diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/.docs.json new file mode 100644 index 0000000000..b575a930ec --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/.docs.json @@ -0,0 +1,8 @@ +[ + { + "Path": "time-series.markdown", + "Name": "Time-Series", + "DiscussionId": "19d1538e-bb89-4887-8a9d-e6b8dce5d6cf", + "Mappings": [] + } +] \ No newline at end of file diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.png new file mode 100644 index 0000000000..dc1713b891 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.snag new file mode 100644 index 0000000000..b290268832 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range-2.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.png new file mode 100644 index 0000000000..5039394f09 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.snag new file mode 100644 index 0000000000..ef855e5341 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/delete-range.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.png new file mode 100644 index 0000000000..25956207ec Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.snag new file mode 100644 index 0000000000..4303fe6e56 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/document-time-series.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.png new file mode 100644 index 0000000000..524250c947 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.snag new file mode 100644 index 0000000000..ddcab07248 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/new-entry.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.png new file mode 100644 index 0000000000..a97630dd71 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.snag new file mode 100644 index 0000000000..dcfc81b01b Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-entry.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.png new file mode 100644 index 0000000000..027f49d3f0 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.snag new file mode 100644 index 0000000000..3c8a9d53d3 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-graph.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.png new file mode 100644 index 0000000000..475b3fc585 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.snag new file mode 100644 index 0000000000..801ebecc75 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-query.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.png new file mode 100644 index 0000000000..296ea128ea Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.snag new file mode 100644 index 0000000000..2a8dacc9f0 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/images/time-series-view.snag differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/time-series.markdown b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/time-series.markdown new file mode 100644 index 0000000000..650372dc18 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/studio/database/document-extensions/time-series.markdown @@ -0,0 +1,146 @@ +# Time Series +--- + +{NOTE: } + +Time series are sets of numeric data associated with timestamps and ordered by time. The studio interface +allows you to edit, query and index time series data, as well as view it as list of entries or as a graph. + +* In this page: + * [Document View](../../../studio/database/document-extensions/time-series#document-view) + * [Create New Time Series / New Entry](../../../studio/database/document-extensions/time-series#create-new-time-series) + * [Time Series View](../../../studio/database/document-extensions/time-series#time-series-view) + * [Edit Entry](../../../studio/database/document-extensions/time-series#editing-an-entry) + * [Delete Range](../../../studio/database/document-extensions/time-series#deleting-a-range-of-entries) + * [Graphical Display & Querying](../../../studio/database/document-extensions/time-series#querying-time-series) + * [Graph View](../../../studio/database/document-extensions/time-series#time-series-graph-view) + +{NOTE/} + +--- + +{PANEL: Document View} + +![](images/document-time-series.png) + +{WARNING: Actions} +1. To view a documents' time series, go to its page and click the time series tab on the right. +2. Allows you to create a new time series, see more below. +3. Allows you to view the time series data. +{WARNING/} + +{INFO: Info} +1. Displays the time series': + +* Name +* The number of entries it contains +* The range of time from the first to the last entry in the time series +{INFO/} + +--- + +#### Create new Time Series (by Creating a First Entry) + +![](images/new-entry.png) + +{WARNING: } +A time series must contain at least one entry when it is created (and a time series is deleted when all +of its entries are deleted). +1. Create the new time series' name. +2. Select a timestamp for the new entry. +3. Create an optional tag. +4. Specify one or more numerical values. +{WARNING/} + +{PANEL/} + +{PANEL: Time Series View} + +![](images/time-series-view.png) + +{WARNING: } +1. Create a new entry to add to this time series. +2. Delete all entries from a specified range of time. +{WARNING/} + +{INFO: } +Displays the time series entry's: + +* Timestamp +* Optional tag `string` +* The numerical data; between 1 and 32 `double` values. +{INFO/} + +--- + +#### Editing an Entry + +![](images/time-series-entry.png) + +{WARNING: } +1. Edit the optional tag. +2. Edit a numerical value. +3. Add another value (up to 32). +4. Delete value. +{WARNING/} + +--- + +#### Deleting a Range of Entries + +![](images/delete-range.png) + +{WARNING: } +To specify a range of time series entries: +1. Select the first entry's timestamp as the start of the range. +2. Specify a time value for the start of the range. Opens the menu shown below. +3. Select the last entry's timestamp as the start of the range. +{WARNING/} + +![](images/delete-range-2.png) + +{PANEL/} + +{PANEL: Querying Time Series} + +![](images/time-series-query.png) + +{INFO: } +1. A simple query for all time series in the collection `Companies` and the name `StockPrice`. +2. A list of time series that satisfy the query, with: + + * The ID of the associated document. + * Number of entries and time range. +{INFO/} + +{WARNING: } +1. Run the query. +2. Go to this series' time series view, discussed above. +3. Go to graph view, shown below. +{WARNING/} + +--- + +#### Time Series Graph View + +![](images/time-series-graph.png) + +{WARNING: } +1. Toggle a certain value in the graph. +2. Hover your mouse over the graph to view the data of one particular entry. +3. This bottom display shows the entire time series. Drag and resize the pink box to select +the range of time displayed in the main graph above. +{WARNING/} + +{INFO: } +1. A legend for the different lines by their color and their corresponding value's place in the +entry's list of values. +2. A hint box the appears when you hover your mouse over the graph, listing the values of that entry. +{INFO/} + +{PANEL/} + + + + +## Related articles diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/.docs.json new file mode 100644 index 0000000000..49b188f835 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/.docs.json @@ -0,0 +1,25 @@ +[ + { + "Path": "/document-view", + "Name": "Document View", + "Mappings": [] + }, + { + "Path": "documents-and-collections.markdown", + "Name": "Documents and Collections", + "DiscussionId": "a0393edb-501a-4679-bd4d-6991ec12e189", + "Mappings": [] + }, + { + "Path": "create-new-document.markdown", + "Name": "Create New Document", + "DiscussionId": "8c281a87-5b83-464d-b710-0d4bb41a5f9c", + "Mappings": [] + }, + { + "Path": "conflicts-view.markdown", + "Name": "Conflicts View", + "DiscussionId": "ed8d7cb0-288d-4967-92f6-d3e1bab4d95c", + "Mappings": [] + } +] \ No newline at end of file diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/.docs.json b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/.docs.json new file mode 100644 index 0000000000..a75c37bc83 --- /dev/null +++ b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/.docs.json @@ -0,0 +1,8 @@ +[ + { + "Path": "counters.markdown", + "Name": "Counters", + "DiscussionId": "eeb68f75-666c-44e8-889d-e9583bba2435", + "Mappings": [] + } +] diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.png b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.png new file mode 100644 index 0000000000..027f49d3f0 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.png differ diff --git a/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.snag b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.snag new file mode 100644 index 0000000000..3c8a9d53d3 Binary files /dev/null and b/Documentation/5.0/Raven.Documentation.Pages/studio/database/documents/document-view/additional-features/images/time-series-graph.snag differ diff --git a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/Indexing.cs b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/Indexing.cs new file mode 100644 index 0000000000..29580b019d --- /dev/null +++ b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/Indexing.cs @@ -0,0 +1,175 @@ +using System; +using System.Linq; +using System.Threading.Tasks; +using Raven.Client.Documents; +using Raven.Client.Documents.Indexes; +using Raven.Client.Documents.Indexes.TimeSeries; +using Raven.Client.Documents.Operations.Indexes; +using Sparrow.Extensions; +using Xunit; +using Xunit.Abstractions; +using System.Collections.Generic; + + +namespace Raven.Documentation.Samples.DocumentExtensions.TimeSeries.Indexing +{ + class Indexing + { + public void Examples() + { + var documentStore = new DocumentStore + { + Urls = new[] { "http://localhost:8080" }, + Database = "products" + }; + documentStore.Initialize(); + + #region indexes_IndexDefinition + documentStore.Maintenance.Send(new PutIndexesOperation( + new TimeSeriesIndexDefinition + { + Name = "Stocks_ByTradeVolume", + Maps = { + "from ts in timeSeries.Companies.StockPrice " + + "from entry in ts.Entries " + + "select new " + + "{ " + + " TradeVolume = entry.Values[4], " + + " entry.Timestamp.Date " + + "}" + } + })); + #endregion + + #region indexes_IndexDefinitionBuilder + var TSIndexDefBuilder = + new TimeSeriesIndexDefinitionBuilder("Stocks_ByTradeVolume"); + + TSIndexDefBuilder.AddMap("StockPrice", + timeseries => from ts in timeseries + from entry in ts.Entries + select new + { + TradeVolume = entry.Values[4], + entry.Timestamp.Date + }); + + documentStore.Maintenance.Send(new PutIndexesOperation( + TSIndexDefBuilder.ToIndexDefinition(documentStore.Conventions))); + #endregion + + + } + + #region indexes_CreationTask + public class Stocks_ByTradeVolume : AbstractTimeSeriesIndexCreationTask + { + public Stocks_ByTradeVolume() + { + AddMap("StockPrice", + timeseries => from ts in timeseries + from entry in ts.Entries + select new + { + TradeVolume = entry.Values[4], + entry.Timestamp.Date + }); + } + } + #endregion + + #region indexes_MultiMapCreationTask + public class Vehicles_ByLocation : AbstractMultiMapTimeSeriesIndexCreationTask + { + public Vehicles_ByLocation() + { + AddMap( + "GPS_Coordinates", + timeSeries => from ts in timeSeries + from entry in ts.Entries + select new + { + Latitude = entry.Values[0], + Longitude = entry.Values[0], + entry.Timestamp + }); + + AddMap( + "GPS_Coordinates", + timeSeries => from ts in timeSeries + from entry in ts.Entries + select new + { + Latitude = entry.Values[0], + Longitude = entry.Values[0], + entry.Timestamp + }); + } + } + #endregion + + #region indexes_MapReduce + public class TradeVolume_PerDay_ByCountry : + AbstractTimeSeriesIndexCreationTask + { + public class Result + { + public double TradeVolume { get; set; } + public DateTime Date { get; set; } + public string Country { get; set; } + } + + public TradeVolume_PerDay_ByCountry() + { + AddMap( + "StockPrice", + timeSeries => from ts in timeSeries + let company = LoadDocument(ts.DocumentId) + from entry in ts.Entries + select new Result + { + TradeVolume = entry.Values[4], + Date = entry.Timestamp.Date, + Country = company.Address.Country + }); + + Reduce = results => + from r in results + group r by new { r.Date, r.Country } into g + select new Result + { + TradeVolume = g.Sum(x => x.TradeVolume), + Date = g.Key.Date, + Country = g.Key.Country + }; + } + } + #endregion + } + + internal class Ship + { + } + + internal class Plane + { + } + + internal class Employee + { + } + + internal class User + { + } + + internal class Company + { + public Address Address { get; set; } + } + + internal class Address + { + public string Country { get; set; } + } +} diff --git a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/RollupAndRetention.cs b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/RollupAndRetention.cs new file mode 100644 index 0000000000..4b184f731c --- /dev/null +++ b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/RollupAndRetention.cs @@ -0,0 +1,80 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using Raven.Client.Documents; +using Raven.Client.Documents.Operations.TimeSeries; +using Sparrow; +using Xunit; + +namespace Raven.Documentation.Samples.DocumentExtensions.TimeSeries +{ + class rollup_and_retention + { + public void Examples() + { + var store = new DocumentStore + { + Urls = new[] { "http://localhost:8080" }, + Database = "Examples" + }; + store.Initialize(); + + using (var session = store.OpenSession()) + { + #region rollup_and_retention_0 + //Policy for the original ("raw") time-series, + //to keep the data for one week + var oneWeek = TimeValue.FromDays(7); + var rawRetention = new RawTimeSeriesPolicy(oneWeek); + + //Roll-up the data for each day, + //and keep the results for one year + var oneDay = TimeValue.FromDays(1); + var oneYear = TimeValue.FromYears(1); + var dailyRollup = new TimeSeriesPolicy("DailyRollupForOneYear", + oneDay, + oneYear); + + //Enter the above policies into a + //time-series collection configuration + //for the collection 'Sales' + var salesTSConfig = new TimeSeriesCollectionConfiguration + { + Policies = new List + { + dailyRollup + }, + RawPolicy = rawRetention + }; + + //Enter the configuration for the Sales collection + //into a time-series configuration for the whole database + var DatabaseTSConfig = new TimeSeriesConfiguration(); + DatabaseTSConfig.Collections["Sales"] = salesTSConfig; + + //Send the time-series configuration to the server + store.Maintenance.Send(new ConfigureTimeSeriesOperation(DatabaseTSConfig)); + #endregion + + #region rollup_and_retention_1 + //Create local instance of the time-series "rawSales" + //in the document "sales/1" + var rawTS = session.TimeSeriesFor("sales/1", "rawSales"); + + //Create local instance of the rollup time-series - first method: + var dailyRollupTS = session.TimeSeriesFor("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 + var rollupTimeSeries2 = session.TimeSeriesFor("sales/1", + dailyRollup.GetTimeSeriesName("rawSales")); + + //Retrieve all the data from both time-series + var rawData = rawTS.Get(DateTime.MinValue, DateTime.MaxValue).ToList(); + var rollupData = dailyRollupTS.Get(DateTime.MinValue, DateTime.MaxValue).ToList(); + #endregion + } + } + } +} diff --git a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/TimeSeriesTests.cs b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/TimeSeriesTests.cs new file mode 100644 index 0000000000..6894b70a5f --- /dev/null +++ b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/TimeSeriesTests.cs @@ -0,0 +1,1295 @@ +using System; +using System.Linq; +using FastTests; +using Raven.Client.Documents; +using Raven.Tests.Core.Utils.Entities; +using Xunit; +using Xunit.Abstractions; +using System.Collections.Generic; +using Raven.Server.Utils; +using MongoDB.Driver; +using Raven.Client.Documents.Operations.TimeSeries; +using Raven.Client.Documents.Commands.Batches; +using PatchRequest = Raven.Client.Documents.Operations.PatchRequest; +using Raven.Client.Documents.Operations; +using Xunit.Abstractions; +using Raven.Client.Documents.Session; +using Raven.Client.Documents.Session.TimeSeries; +using Raven.Client.Documents.Linq; +using Raven.Client.Documents.BulkInsert; +using static Raven.Client.Documents.BulkInsert.BulkInsertOperation; +using Raven.Client.Documents.Indexes.TimeSeries; +using Raven.Client.Documents.Queries.TimeSeries; +using Raven.Client.Documents.Queries; + +namespace SlowTests.Client.TimeSeries.Session +{ + public class TimeSeriesSessionTests + { + public TimeSeriesSessionTests(ITestOutputHelper output) + { + } + + public void SessionTests() + { + var store = new DocumentStore + { + Urls = new[] { "http://localhost:8080" }, + Database = "products" + }; + store.Initialize(); + + var baseline = DateTime.Today; + + // create time series + #region timeseries_region_TimeSeriesFor_without_document_load + // Open a session + using (var session = store.OpenSession()) + { + // Use the session to create a document + session.Store(new { 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.TimeSeriesFor("users/john", "HeartRate") + .Append(baseline.AddMinutes(1), 70d, "watches/fitbit"); + + session.SaveChanges(); + } + #endregion + + // retrieve a single value + #region timeseries_region_TimeSeriesFor_with_document_load + using (var session = store.OpenSession()) + { + // Use the session to load a document + User user = session.Load("users/john"); + + // Pass the document object returned from session.Load as a param + // Retrieve a single value from the time series + IEnumerable val = session.TimeSeriesFor(user, "HeartRate") + .Get(DateTime.MinValue, DateTime.MaxValue); + } + #endregion + + // retrieve a single value - use the document object + #region timeseries_region_TimeSeriesFor-Get-Single-Value-Using-Document-Object + using (var session = store.OpenSession()) + { + // Use the session to load a document + User user = session.Load("users/john"); + + // Pass the document object returned from session.Load as a param + // Retrieve a single value from the time series + IEnumerable val = session.TimeSeriesFor(user, "HeartRate") + .Get(DateTime.MinValue, DateTime.MaxValue); + } + #endregion + + #region timeseries_region_Get-All-Entries-Using-Document-ID + // retrieve all entries of a time-series named "HeartRate" + // by passing TimeSeriesFor.Get an explict document ID + // Include all time points - from the first timestamp to the last + TimeSeriesEntry[] val = session.TimeSeriesFor("users/john", "HeartRate") + .Get(DateTime.MinValue, DateTime.MaxValue); + #endregion + + #region timeseries_region_Pass-TimeSeriesFor-Get-Query-Results + // Query for a document with the Name property "John" + // and get its HeartRate time-series values + using (var session = store.OpenSession()) + { + var baseline = DateTime.Today; + + IRavenQueryable query = session.Query() + .Where(u => u.Name == "John"); + + var result = query.ToList(); + + TimeSeriesEntry[] val = session.TimeSeriesFor(result[0], "HeartRate") + .Get(DateTime.MinValue, DateTime.MaxValue); + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_Get-Strongly-Typed + bool goingUp = false; + + // Use Get + using (var session = store.OpenSession()) + { + // get entries by GetAsync, using the strongly typed StockPrice class + var results = session.TimeSeriesFor("users/john") + .Get(); + + var ClosePriceDay1 = results[0].Value.Close; + var ClosePriceDay2 = results[1].Value.Close; + var ClosePriceDay3 = results[2].Value.Close; + + if ((ClosePriceDay2 > ClosePriceDay1) + && + (ClosePriceDay3 > ClosePriceDay2)) + goingUp = true; + } + #endregion + + #region timeseries_region_Append-Strongly-Typed-1 + using (var session = store.OpenSession()) + { + session.Store(new User { Name = "John" }, "users/john"); + + // Append coordinates + session.TimeSeriesFor("users/john") + .Append(DateTime.Now, new RoutePoint + { + Latitude = 40.712776, + Longitude = -74.005974 + }, "watches/anotherFirm"); + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_Append-Strongly-Typed-2 + // append multi-value entries using a registered time series type + using (var session = store.OpenSession()) + { + session.Store(new User { Name = "John" }, "users/john"); + + session.TimeSeriesFor("users/john") + .Append(baseline.AddDays(1), new StockPrice + { + Open = 52, + Close = 54, + High = 63.5, + Low = 51.4, + Volume = 9824, + }, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseline.AddDays(2), new StockPrice + { + Open = 54, + Close = 55, + High = 61.5, + Low = 49.4, + Volume = 8400, + }, "companies/kitchenAppliances"); + + session.TimeSeriesFor("users/john") + .Append(baseline.AddDays(3), new StockPrice + { + Open = 55, + Close = 57, + High = 65.5, + Low = 50, + Volume = 9020, + }, "companies/kitchenAppliances"); + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_Strongly-Typed-Query + using (var session = store.OpenSession()) + { + IRavenQueryable> query = + session.Query() + .Where(c => c.Address1 == "New York") + .Select(q => RavenQuery.TimeSeries(q, "StockPrices", baseline, baseline.AddDays(3)) + .Where(ts => ts.Tag == "companies/kitchenAppliances") + .ToList()); + } + #endregion + + #region timeseries_region_Strongly-Typed-Register + await store.TimeSeries.RegisterAsync(); + #endregion + + + + // retrieve time series names + using (var session = store.OpenSession()) + { + #region timeseries_region_Retrieve-TimeSeries-Names + User user = session.Load("users/john"); + List tsNames = session.Advanced.GetTimeSeriesFor(user); + #endregion + } + + #region timeseries_region_TimeSeriesFor-Append-TimeSeries-Range + var baseline = DateTime.Today; + + // Append 10 HeartRate values + using (var session = store.OpenSession()) + { + session.Store(new { Name = "John" }, "users/john"); + + ISessionDocumentTimeSeries tsf = session.TimeSeriesFor("users/john", "HeartRate"); + + for (int i = 0; i < 10; i++) + { + tsf.Append(baseline.AddSeconds(i), new[] { 67d }, "watches/fitbit"); + } + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_Remove-TimeSeriesFor-Single-Time-Point + var baseline = DateTime.Today; + using (var session = store.OpenSession()) + { + //remove a single entry + session.TimeSeriesFor("users/john", "HeartRate") + .Remove(baseline.AddMinutes(4)); + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_TimeSeriesFor-Remove-Time-Points-Range + var baseline = DateTime.Today; + + // Append 10 HeartRate values + using (var session = store.OpenSession()) + { + session.Store(new { Name = "John" }, "users/john"); + + var tsf = session.TimeSeriesFor("users/john", "HeartRate"); + + for (int i = 0; i < 10; i++) + { + tsf.Append(baseline.AddSeconds(i), new[] { 67d }, "watches/fitbit"); + } + + session.SaveChanges(); + } + + // remove a range of 4 values from the time series + using (var session = store.OpenSession()) + { + session.TimeSeriesFor("users/john", "HeartRate") + .Remove(baseline.AddSeconds(4), baseline.AddSeconds(7)); + + session.SaveChanges(); + } + #endregion + + #region timeseries_region_Append-With-IEnumerable + using (var store = GetDocumentStore()) + { + var baseline = DateTime.Today; + + // Open a session + using (var session = store.OpenSession()) + { + // Create a document + session.Store(new { Name = "John" }, "users/john"); + + // Pass TimeSeriesFor an explicit document ID + // Append values at the first-minute timestamp + session.TimeSeriesFor("users/john", "HeartRate") + .Append(baseline.AddMinutes(1), + new[] { 65d, 52d, 72d }, + "watches/fitbit"); + + session.SaveChanges(); + } + } + #endregion + + + #region timeseries_region_Load-Document-And-Include-TimeSeries + // Load a document and Include a specified range of a time-series + using (var session = store.OpenSession()) + { + var baseline = DateTime.Today; + + User user = session.Load("users/1-A", includeBuilder => + includeBuilder.IncludeTimeSeries("HeartRate", + baseline.AddMinutes(200), baseline.AddMinutes(299))); + + IEnumerable val = session.TimeSeriesFor("users/1-A", "HeartRate") + .Get(baseline.AddMinutes(200), baseline.AddMinutes(299)); + } + #endregion + + #region timeseries_region_Query-Document-And-Include-TimeSeries + // Query for a document and include a whole time-series + using (var session = store.OpenSession()) + { + baseline = DateTime.Today; + + IRavenQueryable query = session.Query() + .Where(u => u.Name == "John") + .Include(includeBuilder => includeBuilder.IncludeTimeSeries( + "HeartRate", DateTime.MinValue, DateTime.MaxValue)); + + var result = query.ToList(); + + IEnumerable val = session.TimeSeriesFor(result[0], "HeartRate") + .Get(DateTime.MinValue, DateTime.MaxValue); + } + #endregion + + #region timeseries_region_Raw-Query-Document-And-Include-TimeSeries + // Include a Time Series in a Raw Query + using (var session = store.OpenSession()) + { + baseline = DateTime.Today; + + var start = baseline; + var end = baseline.AddHours(1); + + IRawDocumentQuery query = session.Advanced.RawQuery + ("from Users include timeseries('HeartRate', $start, $end)") + .AddParameter("start", start) + .AddParameter("end", end); + + var result = query.ToList(); + + IEnumerable val = session.TimeSeriesFor(result[0], "HeartRate") + .Get(start, end); + } + #endregion + + #region TS_region-Session_Patch-Append-100-Random-TS-Entries + var baseline = DateTime.Today; + + // Create arrays of timestamps and random values to patch + List values = new List(); + List timeStamps = new List(); + + for (var cnt = 0; cnt < 100; cnt++) + { + values.Add(68 + Math.Round(19 * new Random().NextDouble())); + timeStamps.Add(baseline.AddSeconds(cnt)); + } + + session.Advanced.Defer(new PatchCommandData("users/1-A", null, + new PatchRequest + { + Script = @" + var i = 0; + for(i = 0; i < $values.length; i++) + { + timeseries(id(this), $timeseries) + .append ( + new Date($timeStamps[i]), + $values[i], + $tag); + }", + + Values = + { + { "timeseries", "HeartRate" }, + { "timeStamps", timeStamps }, + { "values", values }, + { "tag", "watches/fitbit" } + } + }, null)); + + session.SaveChanges(); + #endregion + + var baseline = DateTime.Today; + + // Create arrays of timestamps and random values to patch + List values = new List(); + List timeStamps = new List(); + + for (var cnt = 0; cnt < 100; cnt++) + { + values.Add(68 + Math.Round(19 * new Random().NextDouble())); + timeStamps.Add(baseline.AddSeconds(cnt)); + } + + #region TS_region-Session_Patch-Append-100-TS-Entries + session.Advanced.Defer(new PatchCommandData("users/1-A", null, + new PatchRequest + { + Script = @" + var i = 0; + for(i = 0; i < $values.length; i++) + { + timeseries(id(this), $timeseries) + .append ( + new Date($timeStamps[i]), + $values[i], + $tag); + }", + + Values = + { + { "timeseries", "HeartRate" }, + { "timeStamps", timeStamps }, + { "values", values }, + { "tag", "watches/fitbit" } + } + }, null)); + + session.SaveChanges(); + #endregion + + #region TS_region-Session_Patch-Remove-50-TS-Entries + // Remove time-series entries + session.Advanced.Defer(new PatchCommandData("users/1-A", null, + new PatchRequest + { + Script = @"timeseries(this, $timeseries) + .remove( + $from, + $to + );", + Values = + { + { "timeseries", "HeartRate" }, + { "from", baseline.AddSeconds(0) }, + { "to", baseline.AddSeconds(49) } + } + }, null)); + session.SaveChanges(); + #endregion + + } + + public void ReebUseTimeSeriesBatchOperation() + { + const string documentId = "users/john"; + + using (var store = GetDocumentStore()) + { + using (var session = store.OpenSession()) + { + session.Store(new User(), documentId); + session.SaveChanges(); + } + + #region timeseries_region_Append-Using-TimeSeriesBatchOperation + var baseline = DateTime.Today; + + var timeSeriesExcersizeneHeartRate = new TimeSeriesOperation + { + Name = "RoutineHeartRate" + }; + + timeSeriesExcersizeneHeartRate.Append(new TimeSeriesOperation.AppendOperation { Tag = "watches/fitbit", Timestamp = baseline.AddMinutes(1), Values = new[] { 79d } }); + timeSeriesExcersizeneHeartRate.Append(new TimeSeriesOperation.AppendOperation { Tag = "watches/fitbit", Timestamp = baseline.AddMinutes(2), Values = new[] { 82d } }); + timeSeriesExcersizeneHeartRate.Append(new TimeSeriesOperation.AppendOperation { Tag = "watches/fitbit", Timestamp = baseline.AddMinutes(3), Values = new[] { 80d } }); + timeSeriesExcersizeneHeartRate.Append(new TimeSeriesOperation.AppendOperation { Tag = "watches/fitbit", Timestamp = baseline.AddMinutes(4), Values = new[] { 78d } }); + + var timeSeriesBatch = new TimeSeriesBatchOperation(documentId, timeSeriesExcersizeneHeartRate); + + store.Operations.Send(timeSeriesBatch); + #endregion + + + #region timeseries_region_Remove-Range-Using-TimeSeriesBatchOperation + var removeEntries = new TimeSeriesOperation + { + Name = "RoutineHeartRate" + }; + + removeEntries.Remove(new TimeSeriesOperation.RemoveOperation { From = baseline.AddMinutes(2), To = baseline.AddMinutes(3) }); + + var removeEntriesBatch = new TimeSeriesBatchOperation(documentId, removeEntries); + + store.Operations.Send(removeEntriesBatch); + #endregion + } + } + + + #region timeseries_region_Get-Single-Time-Series + // Get all values of a single time-series + TimeSeriesRangeResult singleTimeSeriesRange = store.Operations.Send( + new GetTimeSeriesOperation(documentId, "HeartRate", DateTime.MinValue, DateTime.MaxValue)); + #endregion + + #region timeseries_region_Get-Multiple-Time-Series + // Get value ranges from two time-series using GetMultipleTimeSeriesOperation + TimeSeriesDetails multipleTimesSeriesDetails = store.Operations.Send( + new GetMultipleTimeSeriesOperation(documentId, new List + { + new TimeSeriesRange + { + Name = "ExcersizeHeartRate", + From = baseTime.AddHours(1), + To = baseTime.AddHours(10) + }, + + new TimeSeriesRange + { + Name = "RestHeartRate", + From = baseTime.AddHours(11), + To = baseTime.AddHours(20) + } + })); + #endregion + + #region timeseries_region_Use-BulkInsert-To-Append-2-Entries + // Use BulkInsert to append 2 time-series entries + using (BulkInsertOperation bulkInsert = store.BulkInsert()) + { + using (TimeSeriesBulkInsert timeSeriesBulkInsert = bulkInsert.TimeSeriesFor(documentID, "HeartRate")) + { + timeSeriesBulkInsert.Append(baseline.AddMinutes(2), 61d, "watches/fitbit"); + timeSeriesBulkInsert.Append(baseline.AddMinutes(3), 62d, "watches/apple-watch"); + } + } + #endregion + + #region timeseries_region_Use-BulkInsert-To-Append-100-Entries + // Append 100 entries in a single transaction + using (BulkInsertOperation bulkInsert = store.BulkInsert()) + { + using (TimeSeriesBulkInsert timeSeriesBulkInsert = bulkInsert.TimeSeriesFor(documentId, "HeartRate")) + { + for (int minute = 0; minute < 100; minute++) + { + timeSeriesBulkInsert.Append(baseline.AddMinutes(minute), new double[] { 80d }, "watches/fitbit"); + } + } + } + #endregion + + #region BulkInsert-overload-2-Two-HeartRate-Sets + ICollection ExcersizeHeartRate = new List + { 89d, 82d, 85d }; + + ICollection RestingHeartRate = new List + {59d, 63d, 61d, 64d, 64d, 65d }; + + using (TimeSeriesBulkInsert timeSeriesBulkInsert = bulkInsert.TimeSeriesFor(documentId, "HeartRate")) + { + timeSeriesBulkInsert.Append(baseline.AddMinutes(2), ExcersizeHeartRate, "watches/fitbit"); + timeSeriesBulkInsert.Append(baseline.AddMinutes(3), RestingHeartRate, "watches/apple-watch"); + } + #endregion + + + + + #region TS_region-Operation_Patch-Append-Single-TS-Entry + store.Operations.Send(new PatchOperation("users/1-A", null, + new PatchRequest + { + Script = "timeseries(this, $timeseries).append($timestamp, $values, $tag);", + Values = + { + { "timeseries", "HeartRate" }, + { "timestamp", baseline.AddMinutes(1) }, + { "values", 59d }, + { "tag", "watches/fitbit" } + } + })); + #endregion + + #region TS_region-Operation_Patch-Append-100-TS-Entries + var baseline = DateTime.Today; + + // Create arrays of timestamps and random values to patch + List values = new List(); + List timeStamps = new List(); + + for (var cnt = 0; cnt < 100; cnt++) + { + values.Add(68 + Math.Round(19 * new Random().NextDouble())); + timeStamps.Add(baseline.AddSeconds(cnt)); + } + + store.Operations.Send(new PatchOperation("users/1-A", null, + new PatchRequest + { + Script = @"var i = 0; + for (i = 0; i < $values.length; i++) + {timeseries(id(this), $timeseries) + .append ( + new Date($timeStamps[i]), + $values[i], + $tag); + }", + Values = + { + { "timeseries", "HeartRate" }, + { "timeStamps", timeStamps}, + { "values", values }, + { "tag", "watches/fitbit" } + } + + })); + #endregion + + #region TS_region-Operation_Patch-Remove-50-TS-Entries + store.Operations.Send(new PatchOperation("users/1-A", null, + new PatchRequest + { + Script = "timeseries(this, $timeseries).remove($from, $to);", + Values = + { + { "timeseries", "HeartRate" }, + { "from", baseline.AddSeconds(0) }, + { "to", baseline.AddSeconds(49) } + } + })); + #endregion + + #region TS_region-PatchByQueryOperation-Append-To-Multiple-Docs + // Append time-series to all users + PatchByQueryOperation appendOperation = new PatchByQueryOperation(new IndexQuery + { + Query = @"from Users as u update + { + timeseries(u, $name).append($time, $values, $tag) + }", + QueryParameters = new Parameters + { + { "name", "HeartRate" }, + { "time", baseline.AddMinutes(1) }, + { "values", new[]{59d} }, + { "tag", "watches/fitbit" } + } + }); + store.Operations.Send(appendOperation); + #endregion + + #region TS_region-PatchByQueryOperation-Remove-From-Multiple-Docs + // Remove time-series from all users + PatchByQueryOperation removeOperation = new PatchByQueryOperation(new IndexQuery + { + Query = @"from Users as u + update + { + timeseries(u, $name).remove($from, $to) + }", + QueryParameters = new Parameters + { + { "name", "HeartRate" }, + { "from", DateTime.MinValue }, + { "to", DateTime.MaxValue } + } + }); + store.Operations.Send(removeOperation); + #endregion + + #region TS_region-PatchByQueryOperation-Get + PatchByQueryOperation getExcersizeHeartRateOperation = new PatchByQueryOperation(new 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)) + }", + + QueryParameters = new Parameters + { + { "name", "ExcersizeHeartRate" }, + { "from", DateTime.MinValue }, + { "to", DateTime.MaxValue } + } + }); + + var result = store.Operations.Send(getExcersizeHeartRateOperation).WaitForCompletion(); + + #endregion + + #region ts_region_Raw-Query-Non-Aggregated-Declare-Syntax + // May 17 2020, 00:00:00 + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + // Raw query with no aggregation - Declare syntax + IRawDocumentQuery nonAggregatedRawQuery = + session.Advanced.RawQuery(@" + declare timeseries getHeartRate(user) + { + from user.HeartRate + between $start and $end + offset '02:00' + } + from Users as u where Age < 30 + select getHeartRate(u) + ") + .AddParameter("start", baseline) + .AddParameter("end", baseline.AddHours(24)); + + var nonAggregatedRawQueryResult = nonAggregatedRawQuery.ToList(); + #endregion + + #region ts_region_Raw-Query-Non-Aggregated-Select-Syntax + // May 17 2020, 00:00:00 + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + // Raw query with no aggregation - Select syntax + IRawDocumentQuery nonAggregatedRawQuery = + session.Advanced.RawQuery(@" + from Users as u where Age < 30 + select timeseries ( + from HeartRate + between $start and $end + offset '02:00' + )") + .AddParameter("start", baseline) + .AddParameter("end", baseline.AddHours(24)); + + var nonAggregatedRawQueryResult = nonAggregatedRawQuery.ToList(); + #endregion + + #region ts_region_Raw-Query-Aggregated + // May 17 2020, 00:00:00 + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + // Raw Query with aggregation + IRawDocumentQuery aggregatedRawQuery = + session.Advanced.RawQuery(@" + from Users as u + select timeseries( + from HeartRate + between $start and $end + group by '1 days' + select min(), max()) + ") + .AddParameter("start", baseline) + .AddParameter("end", baseline.AddDays(7)); + + var aggregatedRawQueryResult = aggregatedRawQuery.ToList(); + #endregion + + #region ts_region_LINQ-1-Select-Timeseries + using (var session = store.OpenSession()) + { + IRavenQueryable query = (IRavenQueryable)session + .Query() + .Where(u => u.Age < 30) + .Select(q => RavenQuery.TimeSeries(q, "HeartRate") + .ToList()); + + var result = query.ToList(); + } + #endregion + + #region ts_region_LINQ-2-RQL-Equivalent + using (var session = store.OpenSession()) + { + IRawDocumentQuery nonAggregatedRawQuery = + session.Advanced.RawQuery(@" + from Users as u where Age < 30 + select timeseries ( + from HeartRate + )"); + + var nonAggregatedRawQueryResult = nonAggregatedRawQuery.ToList(); + } + #endregion + + // Query - LINQ format with Range selection + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + #region ts_region_LINQ-3-Range-Selection + IRavenQueryable query = + (IRavenQueryable)session.Query() + .Where(u => u.Age < 30) + .Select(q => RavenQuery.TimeSeries(q, "HeartRate", baseline, baseline.AddDays(3)) + .ToList()); + #endregion + + var result = query.ToList(); + } + + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + #region ts_region_LINQ-4-Where + IRavenQueryable query = + (IRavenQueryable)session.Query() + + // Choose user profiles of users under the age of 30 + .Where(u => u.Age < 30) + + .Select(q => RavenQuery.TimeSeries(q, "HeartRate", baseline, baseline.AddDays(3)) + + // Filter time-series entries by their tag. + .Where(ts => ts.== "watches/fitbit") + #endregion + + .ToList()); + + var result = query.ToList(); + } + + using (var session = store.OpenSession()) + { + // May 17 2020, 00:00:00 + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + #region ts_region_Filter-By-load-Tag-Raw-RQL + IRawDocumentQuery nonAggregatedRawQuery = + session.Advanced.RawQuery(@" + from Companies as c where c.Address.Country = 'USA' + select timeseries( + from StockPrice + load Tag as emp + where emp.Title == 'Sales Representative' + )"); + + var result = nonAggregatedRawQuery.ToList(); + #endregion + } + } + + // Query - LINQ format - LoadTag to find a stock broker + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17, 00, 00, 00); + + #region ts_region_Filter-By-LoadTag-LINQ + IRavenQueryable query = + (IRavenQueryable)session.Query() + + .Where(c => c.Address.Country == "USA") + .Select(q => RavenQuery.TimeSeries(q, "StockPrice") + + .LoadTag() + .Where((ts, src) => src.Title == "Sales Representative") + + .ToList()); + + var result = query.ToList(); + #endregion + } + + + // Query - LINQ format - Aggregation + using (var session = store.OpenSession()) + { + var baseline = DateTime.Today; + + #region ts_region_LINQ-6-Aggregation + IRavenQueryable query = session.Query() + .Where(u => u.Age > 72) + .Select(q => RavenQuery.TimeSeries(q, "HeartRate", baseline, baseline.AddDays(10)) + .Where(ts => ts.Tag == "watches/fitbit") + .GroupBy(g => g.Days(1)) + .Select(g => new + { + Avg = g.Average(), + Cnt = g.Count() + }) + .ToList()); + #endregion + + + // Query - LINQ format - StockPrice + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17); + + #region ts_region_LINQ-Aggregation-and-Projections-StockPrice + IRavenQueryable query = session.Query() + .Where(c => c.Address.Country == "USA") + .Select(q => RavenQuery.TimeSeries(q, "StockPrice") + .Where(ts => ts.Values[4] > 500000) + .GroupBy(g => g.Days(7)) + .Select(g => new + { + Min = g.Min(), + Max = g.Max() + }) + .ToList()); + + var result = query.ToList(); + #endregion + } + + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17); + + var start = baseline; + var end = baseline.AddHours(1); + + #region ts_region_Raw-RQL-Select-Syntax-Aggregation-and-Projections-StockPrice + IRawDocumentQuery aggregatedRawQuery = + session.Advanced.RawQuery(@" + from Companies as c + where c.Address.Country = 'USA' + select timeseries ( + from StockPrice + where Values[4] > 500000 + group by '7 day' + select max(), min() + ) + "); + + var aggregatedRawQueryResult = aggregatedRawQuery.ToList(); + #endregion + } + + // Raw Query - StockPrice + using (var session = store.OpenSession()) + { + var baseline = new DateTime(2020, 5, 17); + + var start = baseline; + var end = baseline.AddHours(1); + + #region ts_region_Raw-RQL-Declare-Syntax-Aggregation-and-Projections-StockPrice + IRawDocumentQuery aggregatedRawQuery = + session.Advanced.RawQuery(@" + declare timeseries SP(c) { + from c.StockPrice + 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)" + ); + + var aggregatedRawQueryResult = aggregatedRawQuery.ToList(); + #endregion + } + + + var result = query.ToList(); + } + + // index queries + #region ts_region_Index-TS-Queries-1-session-Query + // Query time-series index using session.Query + using (var session = store.OpenSession()) + { + List results = session.Query() + .ToList(); + } + #endregion + + #region ts_region_Index-TS-Queries-2-session-Query-with-Linq + // Enhance the query using LINQ expressions + var chosenDate = new DateTime(2020, 5, 20); + using (var session = store.OpenSession()) + { + List results = session.Query() + .Where(w => w.Date < chosenDate) + .OrderBy(o => o.HeartBeat) + .ToList(); + } + #endregion + + #region ts_region_Index-TS-Queries-3-DocumentQuery + // Query time-series index using DocumentQuery + using (var session = store.OpenSession()) + { + List results = session.Advanced.DocumentQuery() + .ToList(); + } + #endregion + + #region ts_region_Index-TS-Queries-4-DocumentQuery-with-Linq + // Query time-series index using DocumentQuery with Linq-like expressions + using (var session = store.OpenSession()) + { + List results = session.Advanced.DocumentQuery() + .WhereEquals("Tag", "watches/fitbit") + .ToList(); + } + #endregion + + #region ts_region_Index-TS-Queries-5-session-Query-Async + // Time-series async index query using session.Query + using (var session = store.OpenAsyncSession()) + { + List results = await session.Query() + .ToListAsync(); + } + #endregion + + + } + } + + #region ts_region_Index-TS-Queries-6-Index-Definition-And-Results-Class + public class SimpleIndex : AbstractTimeSeriesIndexCreationTask + { + + public class Result + { + public double HeartBeat { get; set; } + public DateTime Date { get; set; } + public string User { get; set; } + public string Tag { get; set; } + } + + public SimpleIndex() + { + AddMap( + "HeartRate", + timeSeries => from ts in timeSeries + from entry in ts.Entries + select new + { + HeartBeat = entry.Values[0], + entry.Timestamp.Date, + User = ts.DocumentId, + Tag = entry.Tag + }); + } + } + #endregion + + + + private IDisposable GetDocumentStore() + { + throw new NotImplementedException(); + } + } + + internal class User + { + } + + private interface IFoo + { + #region TimeSeriesFor-Append-definition-double + // Append an entry with a single value (double) + void Append(DateTime timestamp, double value, string tag = null); + #endregion + + #region TimeSeriesFor-Append-definition-inum + // Append an entry with multiple values (IEnumerable) + void Append(DateTime timestamp, IEnumerable values, string tag = null); + #endregion + + #region TimeSeriesFor-Remove-definition-single-timepoint + // Remove a single time-series entry + void Remove(DateTime at); + #endregion + + #region TimeSeriesFor-Remove-definition-range-of-timepoints + // Remove a range of time-series entries + void Remove(DateTime from, DateTime to); + #endregion + + #region TimeSeriesFor-Get-definition + TimeSeriesEntry[] Get(DateTime? from = null, DateTime? to = null, + int start = 0, int pageSize = int.MaxValue); + #endregion + + #region TimeSeriesFor-Get-Strongly-Typed + //The stongly-typed API is used, to address time series values by name. + TimeSeriesEntry[] Get(DateTime? from = null, DateTime? to = null, + int start = 0, int pageSize = int.MaxValue); + #endregion + + #region IncludeTimeSeries-definition + TBuilder IncludeTimeSeries(string name, DateTime from, DateTime to); + #endregion + + #region BulkInsert.TimeSeriesFor-definition + public TimeSeriesBulkInsert TimeSeriesFor(string id, string name) + #endregion + + + #region GetTimeSeriesFor-definition + List GetTimeSeriesFor(T instance); + #endregion + + #region Load-definition + T Load(string id, Action> includes); + #endregion + + #region Include-definition + IRavenQueryable Include(this IQueryable source, + Action> includes) + #endregion + + #region RawQuery-definition + IRawDocumentQuery RawQuery(string query); + #endregion + + #region Query-definition + IRavenQueryable Query(string indexName = null, + string collectionName = null, bool isMapReduce = false); + #endregion + + #region PatchCommandData-definition + public PatchCommandData(string id, string changeVector, PatchRequest patch, + PatchRequest patchIfMissing) + #endregion + + #region PatchRequest-definition + public class PatchRequest + { + // Patching script + public string Script { get; set; } + // Values that can be used by the patching script + public Dictionary Values { get; set; } + //... + } + #endregion + + #region TimeSeriesBatchOperation-definition + public TimeSeriesBatchOperation(string documentId, TimeSeriesOperation operation) + #endregion + + #region Append-Operation-Definition-1 + // Each appended entry has a single value. + public void Append(DateTime timestamp, double value, string tag = null) + #endregion + + #region Append-Operation-Definition-2 + // Each appended entry has multiple values. + public void Append(DateTime timestamp, ICollection values, string tag = null) + #endregion + + #region AppendOperation-class + public class AppendOperation + { + public DateTime Timestamp; + public double[] Values; + public string Tag; + //... + } + #endregion + + #region RemoveOperation-class + public class RemoveOperation + { + public DateTime From, To; + //... + } + #endregion + + #region TimeSeriesRangeResult-class + public class TimeSeriesRangeResult + { + public DateTime From, To; + public TimeSeriesEntry[] Entries; + public long? TotalResults; + + //.. + } + #endregion + + #region GetTimeSeriesOperation-Definition + public GetTimeSeriesOperation(string docId, string timeseries, + DateTime? @from = null, DateTime? to = null, int start = 0, int pageSize = int.MaxValue) + #endregion + + #region TimeSeriesDetails-class + public class TimeSeriesDetails + { + public string Id { get; set; } + public Dictionary> Values { get; set; } + } + #endregion + + #region GetMultipleTimeSeriesOperation-Definition + public GetMultipleTimeSeriesOperation(string docId, IEnumerable ranges, + int start = 0, int pageSize = int.MaxValue) + #endregion + + #region TimeSeriesRange-class + public class TimeSeriesRange + { + public string Name; + public DateTime From, To; + } + #endregion + + #region PatchOperation-Definition + public PatchOperation(string id, string changeVector, PatchRequest patch, + PatchRequest patchIfMissing = null, bool skipPatchIfChangeVectorMismatch = false) + #endregion + + #region PatchByQueryOperation-Definition + public PatchByQueryOperation(IndexQuery queryToUpdate, QueryOperationOptions options = null) + #endregion + + #region Store-Operations-send-Definition + public Operation Send(IOperation operation, SessionInfo sessionInfo = null) + #endregion + + #region RavenQuery-TimeSeries-Definition-With-Range + public static ITimeSeriesQueryable TimeSeries(object documentInstance, + string name, DateTime from, DateTime to) + #endregion + + #region RavenQuery-TimeSeries-Definition-Without-Range + public static ITimeSeriesQueryable TimeSeries(object documentInstance, string name) + #endregion + + + #region RegisterAsync-Definitions + public Task RegisterAsync(string name = null) + public Task RegisterAsync(string name, string[] valueNames) + public Task RegisterAsync(string collection, string name, string[] valueNames) + #endregion + + + + + #region TimeSeriesEntry-Definition + public class TimeSeriesEntry + { + public DateTime Timestamp { get; set; } + public double[] Values { get; set; } + public string Tag { get; set; } + public bool IsRollup { get; set; } + + public double Value + + //.. + } + #endregion + + #region Custom-Data-Type-1 + private struct StockPrice + { + [TimeSeriesValue(0)] public double Open; + [TimeSeriesValue(1)] public double Close; + [TimeSeriesValue(2)] public double High; + [TimeSeriesValue(3)] public double Low; + [TimeSeriesValue(4)] public double Volume; + } + #endregion + + #region Custom-Data-Type-2 + private struct RoutePoint + { + [TimeSeriesValue(0)] public double Latitude; + [TimeSeriesValue(1)] public double Longitude; + } + #endregion + + +} + + +} diff --git a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/timeseries.cs b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/timeseries.cs new file mode 100644 index 0000000000..5a65099561 --- /dev/null +++ b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/DocumentExtensions/TimeSeries/timeseries.cs @@ -0,0 +1,307 @@ +using System; +using Raven.Client.Documents; +using System.Linq; +using System.Collections.Generic; +using Raven.Client.Documents.Queries; +using System.Threading.Tasks; +using System.Threading; +using Raven.Client.Documents.Smuggler; + +namespace Rvn.Ch02 +{ + class Program + { + static void Main(string[] args) + { + var docStore = new DocumentStore + { + Urls = new[] { "http://localhost:8080" }, + Database = "products" + }; + docStore.Initialize(); + + #region timeseries_region_TimeSeriesFor_with_document_load + // Use TimeSeriesFor by passing it a document object + + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. Use the session to load a document. + var document = session.Load("products/1-C"); + + // 3. Create an instance of `CountersFor` + // Pass the document object returned from session.Load as a param. + var documentCounters = session.CountersFor(document); + + // 4. Use `CountersFor` methods to manage the product document's Counters + documentCounters.Delete("ProductLikes"); // Delete the "ProductLikes" Counter + documentCounters.Increment("ProductModified", 15); // Add 15 to Counter "ProductModified" + var counter = documentCounters.Get("DaysLeftForSale"); // Get value of "DaysLeftForSale" + + // 5. Save the changes to the session + session.SaveChanges(); + } + #endregion + + #region timeseries_region_TimeSeriesFor_without_document_load + // Use TimeSeriesFor without loading a document + + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. pass an explicit document ID to the CountersFor constructor + var documentCounters = session.CountersFor("products/1-C"); + + // 3. Use `CountersFor` methods to manage the product document's Counters + documentCounters.Delete("ProductLikes"); // Delete the "ProductLikes" Counter + documentCounters.Increment("ProductModified", 15); // Add 15 to Counter "ProductModified" + var counter = documentCounters.Get("DaysLeftForSale"); // Get "DaysLeftForSale"'s value + + // 4. Save changes to the session + session.SaveChanges(); + } + #endregion + + // remove a counter from a document + #region counters_region_Delete + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. pass CountersFor's constructor a document ID + var documentCounters = session.CountersFor("products/1-C"); + + // 3. Delete the "ProductLikes" Counter + documentCounters.Delete("ProductLikes"); + + // 4. Save changes to the session + session.SaveChanges(); + } + #endregion + + // Increment a counter's value + #region counters_region_Increment + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. pass CountersFor's constructor a document ID + var documentCounters = session.CountersFor("products/1-C"); + + // 3. Use `CountersFor.Increment` + documentCounters.Increment("ProductLikes"); // Increase "ProductLikes" by 1, or create it with a value of 1 + documentCounters.Increment("ProductDislikes", 1); // Increase "ProductDislikes" by 1, or create it with a value of 1 + documentCounters.Increment("ProductPageViews", 15); // Increase "ProductPageViews" by 15, or create it with a value of 15 + documentCounters.Increment("DaysLeftForSale", -10); // Decrease "DaysLeftForSale" by 10, or create it with a value of -10 + + // 4. Save changes to the session + session.SaveChanges(); + } + #endregion + + // get a counter's value by the counter's name + #region counters_region_Get + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. pass CountersFor's constructor a document ID + var documentCounters = session.CountersFor("products/1-C"); + + // 3. Use `CountersFor.Get` to retrieve a Counter's value + var DaysLeft = documentCounters.Get("DaysLeftForSale"); + Console.WriteLine("Days Left For Sale: " + DaysLeft); + } + #endregion + + // GetAll + #region counters_region_GetAll + // 1. Open a session + using (var session = docStore.OpenSession()) + { + // 2. pass CountersFor's constructor a document ID + var documentCounters = session.CountersFor("products/1-C"); + + // 3. Use GetAll to retrieve all of the document's Counters' names and values. + var counters = documentCounters.GetAll(); + + // list counters' names and values + foreach (var counter in counters) + { + Console.WriteLine("counter name: " + counter.Key + ", counter value: " + counter.Value); + } + } + #endregion + //Query a collection for documents with a Counter named "ProductLikes" + #region counters_region_query + using (var session = docStore.OpenSession()) + { + //Select documents from the "Products" collection, with a Counter named `ProductLikes`. + //Querying upon Counter values (e.g. using "Where") is not possible. + //In this example the documents that contain the Counter are NOT returned, only Counter values. + var query = session.Query() + .Select(product => RavenQuery.Counter(product, "ProductLikes")); + + var queryResults = query.ToList(); + + //Show ProductLikes's value, or NULL for documents with no such Counter. + foreach (var counterValue in queryResults) + { + Console.WriteLine("ProductLikes: " + counterValue); + } + } + #endregion + + //Query a collection for documents with a Counter named "ProductLikes" + using (var session = docStore.OpenSession()) + { + + #region counters_region_load_include1 + //include single Counters + var productPage = session.Load("products/1-C", includeBuilder => + includeBuilder.IncludeCounter("ProductLikes") + .IncludeCounter("ProductDislikes") + .IncludeCounter("ProductDownloads")); + #endregion + } + + using (var session = docStore.OpenSession()) + { + #region counters_region_load_include2 + //include multiple Counters + //note that you can combine the inclusion of Counters and documents. + var productPage = session.Load("orders/1-A", includeBuilder => + includeBuilder.IncludeDocuments("products/1-C") + .IncludeCounters(new[] { "ProductLikes", "ProductDislikes" })); + #endregion + } + using (var session = docStore.OpenSession()) + { + #region counters_region_query_include_single_Counter + //include a single Counter + var query = session.Query() + .Include(includeBuilder => + includeBuilder.IncludeCounter("ProductLikes")); + #endregion + } + + using (var session = docStore.OpenSession()) + { + #region counters_region_query_include_multiple_Counters + //include multiple Counters + var query = session.Query() + .Include(includeBuilder => + includeBuilder.IncludeCounters(new[] { "ProductLikes", "ProductDownloads" })); + #endregion + } + + using (var session = docStore.OpenSession()) + { + #region counters_region_rawqueries_counter + //Various RQL expressions sent to the server using counter() + //Returned Counter value is accumulated + var rawquery1 = session.Advanced + .RawQuery("from products as p select counter(p, \"ProductLikes\")") + .ToList(); + + var rawquery2 = session.Advanced + .RawQuery("from products select counter(\"ProductLikes\") as ProductLikesCount") + .ToList(); + + var rawquery3 = session.Advanced + .RawQuery("from products where PricePerUnit > 50 select Name, counter(\"ProductLikes\")") + .ToList(); + #endregion + + #region counters_region_rawqueries_counterRaw + //An RQL expression sent to the server using counterRaw() + //Returned Counter value is distributed + var query = session.Advanced + .RawQuery("from users as u select counterRaw(u, \"downloads\")") + .ToList(); + #endregion + } + + + + + } + + private class CounterResult + { + public long? ProductPrice { get; set; } + public long? ProductLikes { get; set; } + public string ProductSection { get; set; } + } + + private class CounterResultRaw + { + public Dictionary Downloads { get; set; } + } + + + public class Product + { + public string Id { get; set; } + public string CustomerId { get; set; } + public DateTime Started { get; set; } + public DateTime? Ended { get; set; } + public double PricePerUnit { get; set; } + public string Issue { get; set; } + public int Votes { get; set; } + } + + #region counters_region_CounterItem + // The value given to a Counter by each node, is placed in a CounterItem object. + public struct CounterItem + { + public string Name; + public string DocId; + public string ChangeVector; + public long Value; + } + #endregion + + + private interface IFoo + { + #region Increment-definition + void Increment(string counterName, long incrementValue = 1); + #endregion + + #region Delete-definition + void Delete(string counterName); + #endregion + + #region Get-definition + long Get(string counterName); + #endregion + + #region GetAll-definition + Dictionary GetAll(); + #endregion + } + + + + public async Task Sample() + { + var token = new CancellationToken(); + + using (var store = new DocumentStore()) + { + // export only Indexes and Documents to a given file + var exportOperation = await store + .Smuggler + .ExportAsync( + new DatabaseSmugglerExportOptions + { + #region smuggler_options + OperateOnTypes = DatabaseItemType.Indexes + | DatabaseItemType.Documents + | DatabaseItemType.Counters + #endregion + }, + @"C:\ravendb-exports\Northwind.ravendbdump", + token); + } + } + } +} diff --git a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/Raven.Documentation.Samples.csproj b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/Raven.Documentation.Samples.csproj index f42e2b97ab..911c72d1c9 100644 --- a/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/Raven.Documentation.Samples.csproj +++ b/Documentation/5.0/Samples/csharp/Raven.Documentation.Samples/Raven.Documentation.Samples.csproj @@ -6,9 +6,9 @@ - - - + + + diff --git a/Raven.Documentation.Parser/Data/Category.cs b/Raven.Documentation.Parser/Data/Category.cs index 4068b88d16..b9c1c3f7b1 100644 --- a/Raven.Documentation.Parser/Data/Category.cs +++ b/Raven.Documentation.Parser/Data/Category.cs @@ -72,6 +72,10 @@ public enum Category Migration, [Prefix("cloud")] - Cloud + Cloud, + + [Prefix("document-extensions")] + [Description("Document Extensions")] + DocumentExtensions } }