diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_output.md b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_output.md new file mode 100644 index 0000000000..b3b15f8f3d --- /dev/null +++ b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_output.md @@ -0,0 +1,25 @@ +#### Output: + +```json +{ + "mergedData": { + "timeWindow": { + "startTs": 1741356332086, + "endTs": 1741357232086 + }, + "values": [{ + "ts": 1741357047945, + "values": [76.0, 46.0, 1023.0] + }, { + "ts": 1741357056144, + "values": [76.0, 46.0, 1026.0] + }, { + "ts": 1741357063689, + "values": [77.0, 46.0, 1026.0] + }, { + "ts": 1741357147391, + "values": [77.0, 46.0, 1025.0] + }] + } +} +``` diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_usage.md b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_usage.md new file mode 100644 index 0000000000..89d3f0c84f --- /dev/null +++ b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_all_usage.md @@ -0,0 +1,5 @@ +#### Usage: + +```javascript +var mergedData = temperature.mergeAll([humidity, pressure], { ignoreNaN: true }); +``` diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_input.md b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_input.md new file mode 100644 index 0000000000..f41b4ae2da --- /dev/null +++ b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_input.md @@ -0,0 +1,48 @@ +#### Assuming the following arguments and their values: + +```json +{ + "humidity": { + "timeWindow": { + "startTs": 1741356332086, + "endTs": 1741357232086 + }, + "values": [{ + "ts": 1741356882759, + "value": 43 + }, { + "ts": 1741356918779, + "value": 46 + }] + }, + "pressure": { + "timeWindow": { + "startTs": 1741356332086, + "endTs": 1741357232086 + }, + "values": [{ + "ts": 1741357047945, + "value": 1023 + }, { + "ts": 1741357056144, + "value": 1026 + }, { + "ts": 1741357147391, + "value": 1025 + }] + }, + "temperature": { + "timeWindow": { + "startTs": 1741356332086, + "endTs": 1741357232086 + }, + "values": [{ + "ts": 1741356874943, + "value": 76 + }, { + "ts": 1741357063689, + "value": 77 + }] + } +} +``` diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_output.md b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_output.md new file mode 100644 index 0000000000..545ef9994c --- /dev/null +++ b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_output.md @@ -0,0 +1,25 @@ +#### Output: + +```json +{ + "mergedData": { + "timeWindow": { + "startTs": 1741356332086, + "endTs": 1741357232086 + }, + "values": [{ + "ts": 1741356874943, + "values": [76.0, "NaN"] + }, { + "ts": 1741356882759, + "values": [76.0, 43.0] + }, { + "ts": 1741356918779, + "values": [76.0, 46.0] + }, { + "ts": 1741357063689, + "values": [77.0, 46.0] + }] + } +} +``` diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_usage.md b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_usage.md new file mode 100644 index 0000000000..a126196ee9 --- /dev/null +++ b/ui-ngx/src/assets/help/en_US/calculated-field/examples/merge-functions/merge_usage.md @@ -0,0 +1,5 @@ +#### Usage: + +```javascript +var mergedData = temperature.merge(humidity, { ignoreNaN: false }); +``` diff --git a/ui-ngx/src/assets/help/en_US/calculated-field/expression_fn.md b/ui-ngx/src/assets/help/en_US/calculated-field/expression_fn.md index f46923ebd3..373c50e2c6 100644 --- a/ui-ngx/src/assets/help/en_US/calculated-field/expression_fn.md +++ b/ui-ngx/src/assets/help/en_US/calculated-field/expression_fn.md @@ -1,9 +1,8 @@ ## Calculated Field TBEL Script Function -The **calculate()** function is a user-defined script that enables custom calculations using [TBEL](\${siteBaseUrl}/docs\${docPlatformPrefix}/user-guide/tbel/) on telemetry and attribute data. +The **calculate()** function is a user-defined script that enables custom calculations using [TBEL](${siteBaseUrl}/docs${docPlatformPrefix}/user-guide/tbel/) on telemetry and attribute data. It receives arguments configured in the calculated field setup, along with an additional `ctx` object that provides access to all arguments. - ### Function Signature ```javascript @@ -18,8 +17,6 @@ There are three types of arguments supported in the calculated field configurati These arguments are single values and may be of type: boolean, int64 (long), double, string, or JSON. -Attribute and Latest telemetry are single value arguments that may be one of: boolean, int64 (long), double, string and JSON. - **Example: Convert Temperature from Fahrenheit to Celsius** ```javascript @@ -95,25 +92,24 @@ for(var i = 0; i < temperature.values.size; i++) { sum += temperature.values[i].value; } // use built-in function to calculate the sum -sum = t.sum(); +sum = temperature.sum(); ``` ##### Built-in Methods for Rolling Arguments Time series rolling arguments support built-in functions for calculations. These functions accept an optional `ignoreNaN` boolean parameter. -| Method | Default Behavior (`ignoreNaN = true`) | Alternative (`ignoreNaN = false`) | -|------------|-----------------------------------------------------|---------------------------------------------| -| `max()` | Returns the highest value, ignoring NaN values. | Returns NaN if any NaN values exist. | -| `min()` | Returns the lowest value, ignoring NaN values. | Returns NaN if any NaN values exist. | -| `mean()` | Computes the average value, ignoring NaN values. | Returns NaN if any NaN values exist. | -| `std()` | Calculates the standard deviation, ignoring NaN. | Returns NaN if any NaN values exist. | -| `median()` | Returns the median value, ignoring NaN values. | Returns NaN if any NaN values exist. | -| `count()` | Counts values, ignoring NaN values. | Counts all values, including NaN. | -| `last()` | Returns the most recent value, skipping NaN values. | Returns the last value, even if it is NaN. | -| `first()` | Returns the oldest value, skipping NaN values. | Returns the first value, even if it is NaN. | -| `sum()` | Computes the total sum, ignoring NaN values. | Returns NaN if any NaN values exist. | - +| Method | Default Behavior (`ignoreNaN = true`) | Alternative (`ignoreNaN = false`) | +|-----------------|-----------------------------------------------------|---------------------------------------------| +| `max()` | Returns the highest value, ignoring NaN values. | Returns NaN if any NaN values exist. | +| `min()` | Returns the lowest value, ignoring NaN values. | Returns NaN if any NaN values exist. | +| `mean(), avg()` | Computes the average value, ignoring NaN values. | Returns NaN if any NaN values exist. | +| `std()` | Calculates the standard deviation, ignoring NaN. | Returns NaN if any NaN values exist. | +| `median()` | Returns the median value, ignoring NaN values. | Returns NaN if any NaN values exist. | +| `count()` | Counts values, ignoring NaN values. | Counts all values, including NaN. | +| `last()` | Returns the most recent value, skipping NaN values. | Returns the last value, even if it is NaN. | +| `first()` | Returns the oldest value, skipping NaN values. | Returns the first value, even if it is NaN. | +| `sum()` | Computes the total sum, ignoring NaN values. | Returns NaN if any NaN values exist. | Usage example: @@ -141,7 +137,7 @@ function calculate(ctx, altitude, temperature) { var airDensity = pressure / (287.05 * temperatureK); return { - "airDensity": airDensity + "airDensity": toFixed(airDensity, 2) }; } ``` @@ -150,123 +146,16 @@ function calculate(ctx, altitude, temperature) { Time series rolling arguments can be **merged** to align timestamps across multiple datasets. -| Method | Description | Parameters | Returns | -|:-----------------------------|:--------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------| -| `merge(other, settings)` | Merges with another rolling argument. Aligns timestamps and filling missing values with the previous available value. | | Merged object with timeWindow and aligned values. | -| `mergeAll(others, settings)` | Merges with multiple rolling arguments. Aligns timestamps and filling missing values with the previous available value. | | Merged object with timeWindow and aligned values.| +| Method | Description | Returns | Example | +|:-----------------------------|:--------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `merge(other, settings)` | Merges with another rolling argument. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. |

| +| `mergeAll(others, settings)` | Merges multiple rolling arguments. Aligns timestamps and filling missing values with the previous available value. | Merged object with `timeWindow` and aligned values. |

| -Assuming the following arguments and their values: - -```json -{ - "humidity": { - "timeWindow": { - "startTs": 1741356332086, - "endTs": 1741357232086 - }, - "values": [{ - "ts": 1741356882759, - "value": 43 - }, { - "ts": 1741356918779, - "value": 46 - }] - }, - "pressure": { - "timeWindow": { - "startTs": 1741356332086, - "endTs": 1741357232086 - }, - "values": [{ - "ts": 1741357047945, - "value": 1023 - }, { - "ts": 1741357056144, - "value": 1026 - }, { - "ts": 1741357147391, - "value": 1025 - }] - }, - "temperature": { - "timeWindow": { - "startTs": 1741356332086, - "endTs": 1741357232086 - }, - "values": [{ - "ts": 1741356874943, - "value": 76 - }, { - "ts": 1741357063689, - "value": 77 - }] - } -} -``` - -**Usage:** - -```javascript -var mergedData = temperature.merge(humidity, { ignoreNaN: false }); -``` - -**Output:** - -```json -{ - "mergedData": { - "timeWindow": { - "startTs": 1741356332086, - "endTs": 1741357232086 - }, - "values": [{ - "ts": 1741356874943, - "values": [76.0, "NaN"] - }, { - "ts": 1741356882759, - "values": [76.0, 43.0] - }, { - "ts": 1741356918779, - "values": [76.0, 46.0] - }, { - "ts": 1741357063689, - "values": [77.0, 46.0] - }] - } -} -``` - -**Usage:** - -```javascript -var mergedData = temperature.mergeAll([humidity, pressure], { ignoreNaN: true }); -``` - -**Output:** - -```json -{ - "mergedData": { - "timeWindow": { - "startTs": 1741356332086, - "endTs": 1741357232086 - }, - "values": [{ - "ts": 1741357047945, - "values": [76.0, 46.0, 1023.0] - }, { - "ts": 1741357056144, - "values": [76.0, 46.0, 1026.0] - }, { - "ts": 1741357063689, - "values": [77.0, 46.0, 1026.0] - }, { - "ts": 1741357147391, - "values": [77.0, 46.0, 1025.0] - }] - } -} -``` +##### Parameters +| Parameter | Description | +|:---------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `other` or `others` | Another rolling argument or array of rolling arguments to merge with. | +| `settings`(optional) | Configuration object that supports: | **Example: Freezer temperature analysis**