MiroxQL Formulas (API Reference)
A MiroxQL formula combines daily metrics of the legacy export into a calculated column, for example a performance ratio from an energy and a target.
The Formula Editor Was Retired From the App
Formulas are no longer created or edited in Mirox itself. This page is the reference of the API, which stays fully usable:
- Existing formulas keep being evaluated wherever they are used: in legacy export templates and on the legacy export links.
- Formulas can still be listed, created, changed and deleted through the API described here.
- The successor for figures you define yourself is Metrics. A metric is evaluated on the 15-minute values of a plant, can be reported per component, appears in reports, and can be exported at every step with the Metric Export.
Open in Mirox
Data Export ▸ Glossary — define a new figure as a metric of your organization.
MiroxQL or Metrics?
| MiroxQL formula | Metric | |
|---|---|---|
| Works on | daily values of a plant | the 15-minute values of a plant |
| Reports per component | no | yes |
| Used in | legacy export templates | reports, the Metric Export and its templates |
| Finest step | day | 15 minutes |
| Edited in | the API | the app, with live validation and an assistant, and the API |
Formula Routes
All paths follow https://service.mirox.io/api/v1/export/metric/formula. The routes need a login or an API token of the group Full Access; a Metric Export token does not reach them. Reading is open to the members of the organization, writing to the organization roles Admin, Moderator, Asset Manager (Technical) and Asset Manager (Commercial).
| Request | Purpose |
|---|---|
GET (no further path) | List the formulas of your organization and the formulas Mirox ships. Parameters: page, limit, include_system (default true), only_active (default false), search. |
GET /{org_uid}/{metric_id} | Read one formula. org_uid is system for a formula Mirox ships. |
GET /{org_uid}/{metric_id}/references | The templates and formulas that use the formula. |
GET /config-fields | The plant configuration values a formula can read. |
POST /validate | Check the text of a formula. The answer lists the metrics and configuration values it reads. |
POST /test | Evaluate a formula on values you send. |
POST /preview | Evaluate a formula on the data of plants, with park or portfolio, year and quarter, month, week or day, and resolution. |
POST /{org_uid} | Create a formula in your organization. |
PUT /{org_uid}/{metric_id} | Change a formula. |
DELETE /{org_uid}/{metric_id} | Delete a formula. |
Formulas Mirox ships cannot be changed or deleted.
Fields of a Formula
| Field | Values | Default | Meaning |
|---|---|---|---|
metric_id | lowercase letters, digits and underscores, starting with a letter; up to 100 characters | required | The id other formulas and templates use. |
name | up to 100 characters | required | The column name. |
description | up to 1000 characters | empty | What the formula calculates. |
unit | up to 50 characters | required | The unit of the result, for example kWh or %. |
formula | text | required | The expression. It must read at least one metric. |
scale | number | 1.0 | The result is multiplied by this factor when it is exported. |
digits | 0 to 10 | 2 | The decimals of the exported value. |
calculation_level | daily, period | period | When the formula runs. See Calculation level. |
aggregation_method | sum, average | average | How daily results become a period value, with calculation_level=daily. |
active | true, false | true | Only when changing a formula. An inactive formula is not evaluated. |
{
"metric_id": "energy_total_incl_losses",
"name": "Total Energy Including Losses",
"description": "Sum of grid energy and all shutdown losses",
"unit": "kWh",
"scale": 0.001,
"digits": 2,
"formula": "@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily",
"calculation_level": "daily",
"aggregation_method": "sum"
}
Ids
An id must be free. 409 metric_id_taken means that a formula or a metric of your organization, or a metric of Mirox, already has the id. This also applies when you change an existing formula whose id is taken in the meantime; deactivating it with active=false stays possible.
Scale and Digits
Calculate in base units and convert with scale. The daily metrics are evaluated in base units (Wh, W, Wh/m²), so a sum of energies with scale=0.001 is exported in kWh. scale and digits apply to the exported value only. A formula that reads another formula receives its unscaled, unrounded result.
Calculation Level
calculation_level | How a monthly value is formed | Use it for |
|---|---|---|
daily | The formula runs for every day. The daily results are added (sum) or averaged (average). | sums of energy |
period | The metrics are rolled up to the month first. The formula runs once on the monthly values. | ratios such as a performance ratio |
Syntax
References
A metric is read with @ and its id. The ids are the legacy metric ids and the ids of other formulas.
@energy_grid_daily
@gti_sensor_daily
A value of the plant configuration is read with $ and its path:
| Reference | Description | Unit |
|---|---|---|
$park.peak_production_w | Total peak power | W |
$park.latitude | Geographic latitude | ° |
$park.longitude | Geographic longitude | ° |
$park.self_consumption | Self-consumption factor (0.0 to 1.0) | ratio |
$park.information.string_peak_power_w | Total peak power of all strings | W |
$park.information.inverter_max_power_w | Maximum inverter power | W |
$park.information.inverter_total | Number of inverters | — |
$park.information.gak_total | Number of combiner boxes | — |
$park.information.strings_total | Number of strings | — |
$park.information.modules_total | Number of modules | — |
GET /config-fields answers the current list.
Operators
| Kind | Operators | Example |
|---|---|---|
| Arithmetic | + - * / % | @energy_grid_daily / $park.peak_production_w |
| Comparison | == != < <= > >= | @gti_sensor_daily > 0 |
| Logic | && || ! | @gti_sensor_daily > 0 && @energy_grid_daily > 0 |
| Condition | condition ? a : b | @gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily |
| Functions | max(a, b), min(a, b) | max(@energy_grid_daily, 0) |
A comparison answers 1 or 0. A division by zero answers 0. A metric without data counts as 0.
Operations are evaluated in this order, highest first: parentheses, functions, * / %, + -, < <= > >=, == !=, &&, ||.
Examples
Specific yield:
@energy_grid_daily / $park.peak_production_w
Irradiation from the sensor, or from the weather model where the sensor has no value:
@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily
Share of the shutdown losses:
(@energy_shutdown_grid_daily + @energy_shutdown_external_daily) / (@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily) * 100
Rules
- A formula reads at least one metric.
- Parentheses are balanced, and two operators do not follow each other, except
!. - A formula must not depend on itself, directly or through other formulas.
- A formula works on daily values. It cannot read values within a day, and it cannot look back over earlier rows.
Moving a Formula to Metrics
A formula and a metric are written in different languages, so a formula is rewritten, not converted. In most cases the metric is shorter, because it states what happens in one 15-minute interval and leaves the rest to its Fold.
- Open Data Export ▸ Glossary and click New metric.
- Describe the figure to the assistant in the editor, or write the expression yourself. The side panel lists the series you can build from.
- Choose the Fold that matches the formula:
| Formula | Fold of the metric |
|---|---|
A sum of energies, calculation_level=daily with sum | Sum |
| An average | Average |
A ratio of two sums, calculation_level=period | Ratio, or Weighted mean |
| A share of time in which a condition holds | Ratio with an expression that answers 1 or 0 |
- Check the preview on a plant, then use the metric in a report or export it.
The performance ratio, the expected production and the specific yield need no metric of your own. The collection has them: plant.pr_weather, plant.pr_pyranometer, plant.expected_weather, plant.expected_pyranometer, plant.specific_yield.
Related Features
- Metrics — the successor: figures your organization defines itself
- Metric Export — export metrics at every step
- Legacy Export API — the templates and links that evaluate formulas
- Migrating to the Metric Export — the calculated columns and their counterparts
- API Tokens — a Full Access token for the formula routes