Revised `AggregationConfig` Syntax Documentation

[thomas-nicolai-frequenz]

What's needed?

This proposed change suggest to update the AggregationConfig message documentation in the Reporting API to include detailed explanations and examples of the COALESCE function. This enhancement will guide users on handling missing data in aggregation formulas by providing fallbacks or default values when component data is unavailable.

Proposed solution

 // Message defining the aggregation configuration for a custom formula within a specific microgrid.
 //
 // The AggregationConfig allows clients to specify how metrics should be aggregated across
 // microgrid components. It serves as the configuration guideline for any aggregation operation.
 //
 // !!! example
 //    To calculate the total voltage across three components in series with IDs 1, 2, and 3, the
 //     configuration could look like:
 //     {
 //       microgrid_id: 42,
 //       metric: DC_VOLTAGE_V,
 //       aggregation_formula: "#1 + #2 + #3"
 //     }
 //
 message AggregationConfig {
   // ID of the microgrid for which the formula is being specified.
   uint64 microgrid_id = 1;

   // The metric that is to be aggregated using the specified formula.
   //
   // !!! caution
   //     Ensure the chosen metric is supported by all relevant microgrid components.
   //     Failure to meet these conditions might result in an aggregation error.
   frequenz.api.common.v1.metrics.Metric metric = 2;

   // The formula used for aggregating the component metric for this microgrid.
   //
-   // !!! info
-  //     Two types of aggregation formulas are supported:
-  //     1. Aggregate functions: These are standard aggregation functions like `sum()` and `mean()`.
-  //        Example: `sum(#1,#2)`, `mean(#3,#4)`
-  //
-  //     2. Dedicated formulas: These support basic math operators while concatenating microgrid
-  //        component IDs.
-  //        Example: `#1 + #2 - #3`, `(#3 * #2) /# 1`
+   // !!! info "Aggregation Formula"
+   //     The formula supports basic arithmetic operations (`+`, `-`, `*`, `/`) and standard functions. 
+   //     Component IDs are referenced using a `#` prefix.
+   //
+  //       Supported Arithmetic Operators:
+  //
+  //       - Addition (`+`)
+  //       - Subtraction (`-`)
+  //       - Multiplication (`*`)
+  //       - Division (`/`)
+  //
+  //        Supported Functions:
+  //
+  //         - `sum(a, b, ...)`: Returns the sum of the arguments.
+  //         - `mean(a, b, ...)`: Returns the average of the arguments.
+  //         - `min(a, b, ...)`: Returns the minimum value among the arguments.
+  //         - `max(a, b, ...)`: Returns the maximum value among the arguments.
+  //         - `coalesce(a, b, ...)`: Returns the first non-null argument.
+  //
+  // !!! example
+  //
+  //     Calculating the Sum
+  //
+  //         `sum(#1, #2, #3)`
+  //
+  //     Custom Formula Calculation:
+  //
+  //         `(#1 * 0.5) + (#2 * 0.5)`
+  //
+  //     Using `coalesce` for Fallbacks:
+  //
+  //         `coalesce(#1, #2)`
+  //
+  //         If both `#1` and `#2` are unavailable, returns null.
+  //
+  //     Minimum and Maximum:
+  //
+  //         `min(#1, #2, #3)`
+  //         `max(#1, #2, #3)`
+  //
+  //     Using `coalesce` to Handle Missing Data:
+  //
+  //       The `coalesce` function returns the first non-null value among its arguments.
+  //       It can provide fallbacks or default values when component data is missing.
+  //
+  //       Examples:
+  //
+  //         - Without Default Value (Fallback):
+  //
+  //           `coalesce(#101, #102)`
+  //
+  //           If both components are unavailable, the result is `null`.
+  //
+  //       - With Default Value:
+  //
+  //           `coalesce(#101, #102, 0)`
+  //
+  //           If both components are unavailable, returns `0` as the default value.
+  //
+  //     Using Functions with Expressions:
+  //
+  //       - Complex Expression:
+  //
+  //           ```
+  //           max(0, #5) - (
+  //               coalesce(max(0, #12), max(0, #13)) +
+  //               coalesce(max(0, #9), max(0, #11) + max(0, #10))
+  //           )
+  //           ```
+  //
   string aggregation_formula = 3;
 }

Use cases

In microgrid systems, aggregating metrics from various components is essential for comprehensive analysis and decision-making. However, data from some components may be missing due to outages, maintenance, or communication issues. The COALESCE function allows users to define fallback strategies within their aggregation formulas to handle such missing data gracefully.

Alternatives and workarounds

No response

Additional context

No response

[cwasicki]

LGTM.

• // - avg(a, b, ...): Returns the average of the arguments.

I would say mean is more common than avg.

[thomas-nicolai-frequenz]

I would say mean is more common than avg.

But thats just terminology right?