Merge pull request #1848 from Danielle9897/RDoc-2863-TS-bulkInsert

RDoc-2863 [Node.js] Document extensions > Time series > Client API > Bulk insert > Append time series [Replace C# samples]
ravendb · Jun 6, 2024 · d71011d · d71011d
2 parents 21a9f20 + cf42abe
commit d71011d
Show file tree

Hide file tree

Showing 7 changed files with 537 additions and 126 deletions.
diff --git a/...ent-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown b/...ent-extensions/timeseries/client-api/bulk-insert/append-in-bulk.dotnet.markdown
@@ -0,0 +1,127 @@
+# Append Time Series with Bulk Insert
+
+---
+
+{NOTE: }
+
+* `store.BulkInsert` is RavenDB's high-performance data insertion operation.  
+
+* The `bulkInsert.TimeSeriesFor` interface provides similar functionality to the [session.TimeSeriesFor](../../../../document-extensions/timeseries/client-api/session/append),  
+  but without the overhead associated with the _Session_, resulting in significantly improved performance.
+
+* In this page:  
+  * [Usage](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#usage)  
+  * [Examples](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#examples)
+      * [Append single entry](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-single-entry)
+      * [Append multiple entries](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-entries)
+      * [Append multiple values per entry](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-values-per-entry)
+      * [Append multiple time series](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-time-series) 
+  * [Syntax](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#syntax)
+
+{NOTE/}
+
+{PANEL: Usage}
+
+**Flow**:
+
+* Call `store.BulkInsert` to create a `BulkInsertOperation` instance.
+* Call `TimeSeriesFor` on that instance and pass it:
+    * The document ID  
+      (An exception will be thrown if the specified document does Not exist).
+    * The time series name  
+      (Appending entries to a time series that doesn't yet exist yet will create the time series).
+* To append an entry, call `Append` and pass it:
+    * The entry's Timestamp
+    * The entry's Value or Values
+    * The entry's Tag (optional)
+
+**Note**:
+
+* To append multiple entries, call `Append` as many times as needed.
+* Ensure there is at least a 1-millisecond interval between each timestamp.
+* The client converts all timestamps to **UTC** before sending the batch to the server.
+* Multiple time series can be appended in the same `BulkInsertOperation`. See this [example](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-time-series) below.
+
+{PANEL/}
+
+{PANEL: Examples}
+
+{NOTE: }
+<a id="append-single-entry" /> __Append single entry__:
+
+---
+In this example, we append a single entry with a single value to time series "HeartRates". 
+{CODE timeseries_region_Use-BulkInsert-To-Append-single-entry@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-entries" /> __Append multiple entries__:
+
+---
+In this example, we append 100 entries with a single value to time series "HeartRates". 
+{CODE timeseries_region_Use-BulkInsert-To-Append-100-Entries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-values-per-entry" /> __Append multiple values per entry__:
+
+---
+In this example, we append multiple values per entry in time series "HeartRates".
+{CODE BulkInsert-overload-2-Two-HeartRate-Sets@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}  
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-time-series" /> __Append multiple time series__:
+
+---
+In this example, we append multiple time series in different documents in the same batch.
+{CODE timeseries_region_Use-BulkInsert-To-Append-multiple-timeseries@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+
+{NOTE/}
+
+{PANEL/}
+
+{PANEL: Syntax}
+
+**`BulkInsert.TimeSeriesFor`**
+
+{CODE-BLOCK: JSON}
+public TimeSeriesBulkInsert TimeSeriesFor(string id, string name)
+{CODE-BLOCK/}
+
+| Parameter   | Type     | Description      |
+|-------------|----------|------------------|
+| **id**      | `string` | Document ID      |
+| **name**    | `string` | Time Series Name |
+
+**`TimeSeriesFor.Append`** overloads:
+
+{CODE Append-Operation-Definition-1@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+{CODE Append-Operation-Definition-2@DocumentExtensions\TimeSeries\TimeSeriesTests.cs /}
+
+| Parameter     | Type                  | Description               |
+|---------------|-----------------------|---------------------------|
+| **timestamp** | `DateTime`            | TS-entry's timestamp      |
+| **value**     | `double`              | A single value            |
+| **values**    | `ICollection<double>` | Multiple values           |
+| **tag**       | `string`              | TS-entry's tag (optional) |
+
+{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/...ocument-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown b/...ocument-extensions/timeseries/client-api/bulk-insert/append-in-bulk.js.markdown
@@ -0,0 +1,124 @@
+# Append Time Series with Bulk Insert
+
+---
+
+{NOTE: }
+
+* `bulkInsert` is RavenDB's high-performance data insertion operation.  
+
+* The `bulkInsert.timeSeriesFor` interface provides similar functionality to the [session.timeSeriesFor](../../../../document-extensions/timeseries/client-api/session/append),  
+  but without the overhead associated with the _Session_, resulting in significantly improved performance.
+
+* In this page:  
+  * [Usage](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#usage)  
+  * [Examples](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#examples)
+      * [Append single entry](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-single-entry)
+      * [Append multiple entries](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-entries)
+      * [Append multiple values per entry](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-values-per-entry)
+      * [Append multiple time series](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-time-series) 
+  * [Syntax](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#syntax)
+
+{NOTE/}
+
+{PANEL: Usage}
+
+**Flow**:
+
+* Call `documentStore.bulkInsert` to create a `BulkInsertOperation` instance.
+* Call `timeSeriesFor` on that instance and pass it:
+    * The document ID  
+      (An exception will be thrown if the specified document does Not exist).
+    * The time series name  
+      (Appending entries to a time series that doesn't yet exist yet will create the time series).
+* To append an entry, call `append` and pass it:
+    * The entry's Timestamp
+    * The entry's Value or Values
+    * The entry's Tag (optional)
+
+**Note**:
+
+* To append multiple entries, call `append` as many times as needed.
+* Ensure there is at least a 1-millisecond interval between each timestamp.
+* The client converts all timestamps to **UTC** before sending the batch to the server.
+* Multiple time series can be appended in the same `BulkInsertOperation`. See this [example](../../../../document-extensions/timeseries/client-api/bulk-insert/append-in-bulk#append-multiple-time-series) below.
+
+{PANEL/}
+
+{PANEL: Examples}
+
+{NOTE: }
+<a id="append-single-entry" /> __Append single entry__:
+
+---
+In this example, we append a single entry with a single value to time series "HeartRates". 
+{CODE:nodejs append_1@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-entries" /> __Append multiple entries__:
+
+---
+In this example, we append 100 entries with a single value to time series "HeartRates". 
+{CODE:nodejs append_2@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-values-per-entry" /> __Append multiple values per entry__:
+
+---
+In this example, we append multiple values per entry in time series "HeartRates".
+{CODE:nodejs append_3@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+{NOTE/}
+
+{NOTE: }
+<a id="append-multiple-time-series" /> __Append multiple time series__:
+
+---
+In this example, we append multiple time series in different documents in the same batch.
+{CODE:nodejs append_4@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+{NOTE/}
+
+{PANEL/}
+
+{PANEL: Syntax}
+
+**`bulkInsert.timeSeriesFor`**
+
+{CODE:nodejs syntax_1@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+| Parameter   | Type     | Description      |
+|-------------|----------|------------------|
+| **id**      | `string` | Document ID      |
+| **name**    | `string` | Time Series Name |
+
+**`timeSeriesFor.Append`** overloads:
+
+{CODE:nodejs syntax_2@documentExtensions\timeSeries\client-api\appendWithBulkInsert.js /}
+
+| Parameter     | Type       | Description               |
+|---------------|------------|---------------------------|
+| **timestamp** | `Date`     | TS-entry's timestamp      |
+| **value**     | `number`   | A single value            |
+| **values**    | `number[]` | Multiple values           |
+| **tag**       | `string`   | TS-entry's tag (optional) |
+
+{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/...t-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown b/...t-extensions/timeseries/client-api/operations/append-and-delete.dotnet.markdown
@@ -24,21 +24,25 @@
 
 {PANEL: Usage}
 
+**Flow**:
+
 * Prepare the Append and Delete operations:
     * Create an instance of `TimeSeriesOperation.AppendOperation` to define an Append action.
     * Create an instance of ` TimeSeriesOperation.DeleteOperation` fo define a Delete action.
-
 * Create an instance of `TimeSeriesOperation` and pass it the the time series name.
     * Call `TimeSeriesOperation.Append` to add the Append operation.
     * Call `TimeSeriesOperation.Delete` to add the Delete operation.
-
 * Create a `TimeSeriesBatchOperation` instance and pass it:  
    * The document ID
    * The `TimeSeriesOperation` object
-
 * Execute the `TimeSeriesBatchOperation` operation by calling `store.Operations.Send`
-   * All the added Append and Delete operations will be executed in a single-node transaction.
-   * Delete actions are executed **before** Append actions. As seen in [this example](../../../../document-extensions/timeseries/client-api/operations/append-and-delete#append--delete-entries-in-the-same-batch).
+
+**Note**:
+
+* All the added Append and Delete operations will be executed in a single-node transaction.
+* Delete actions are executed **before** Append actions. As seen in [this example](../../../../document-extensions/timeseries/client-api/operations/append-and-delete#append--delete-entries-in-the-same-batch).
+* Appending entries to a time series that doesn't yet exist yet will create the time series.
+* An exception will be thrown if the specified document does Not exist.
 
 {PANEL/}
 

diff --git a/...ument-extensions/timeseries/client-api/operations/append-and-delete.js.markdown b/...ument-extensions/timeseries/client-api/operations/append-and-delete.js.markdown
@@ -24,21 +24,25 @@
 
 {PANEL: Usage}
 
+**Flow**:
+
 * Prepare the Append and Delete operations:
     * Create an instance of `TimeSeriesOperation.AppendOperation` to define an Append action.
     * Create an instance of ` TimeSeriesOperation.DeleteOperation` fo define a Delete action.
-
 * Create an instance of `TimeSeriesOperation` and pass it the the time series name.
     * Call `TimeSeriesOperation.append` to add the Append operation.
     * Call `TimeSeriesOperation.delete` to add the Delete operation.
-
 * Create a `TimeSeriesBatchOperation` instance and pass it:  
    * The document ID
    * The `TimeSeriesOperation` object
-
 * Execute the `TimeSeriesBatchOperation` operation by calling `store.operations.send`
+
+**Note**:
+
    * All the added Append and Delete operations will be executed in a single-node transaction.
    * Delete actions are executed **before** Append actions. As seen in [this example](../../../../document-extensions/timeseries/client-api/operations/append-and-delete#append--delete-entries-in-the-same-batch).
+   * Appending entries to a time series that doesn't yet exist yet will create the time series.
+   * An exception will be thrown if the specified document does Not exist.
 
 {PANEL/}