MiroxQL-Formeln (API-Referenz)

Eine MiroxQL-Formel verbindet Tagesmetriken des Legacy-Exports zu einer berechneten Spalte, zum Beispiel eine Performance Ratio aus einer Energie und einem Zielwert.

MiroxQL oder Metriken?

Formel-Routen

Alle Pfade folgen auf https://service.mirox.io/api/v1/export/metric/formula. Die Routen brauchen eine Anmeldung oder ein API-Token der Gruppe Voller Zugriff; ein Token Metric Export erreicht sie nicht. Das Lesen steht den Mitgliedern der Organisation offen, das Schreiben den Organisationsrollen Admin, Moderator, Asset Manager (Technisch) und Asset Manager (Kaufmännisch).

Formeln, die Mirox mitliefert, lassen sich weder ändern noch löschen.

Felder einer Formel

{
  "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

Eine ID muss frei sein. 409 metric_id_taken bedeutet, dass eine Formel oder eine Metrik Ihrer Organisation oder eine Metrik von Mirox die ID bereits trägt. Das gilt auch, wenn Sie eine bestehende Formel ändern, deren ID inzwischen vergeben ist; das Deaktivieren mit active=false bleibt möglich.

Skalierung und Nachkommastellen

Rechnen Sie in Basiseinheiten und rechnen Sie mit scale um. Die Tagesmetriken werden in Basiseinheiten ausgewertet (Wh, W, Wh/m²), eine Summe von Energien mit scale=0.001 wird also in kWh exportiert. scale und digits gelten nur für den exportierten Wert. Eine Formel, die eine andere Formel liest, erhält deren unskaliertes, ungerundetes Ergebnis.

Berechnungsebene

Syntax

Referenzen

Eine Metrik wird mit @ und ihrer ID gelesen. Die IDs sind die Legacy-Metrik-IDs und die IDs anderer Formeln.

@energy_grid_daily
@gti_sensor_daily

Ein Wert der Anlagenkonfiguration wird mit $ und seinem Pfad gelesen:

GET /config-fields beantwortet die aktuelle Liste.

Operatoren

Ein Vergleich antwortet mit 1 oder 0. Eine Division durch null antwortet mit 0. Eine Metrik ohne Daten zählt als 0.

Operationen werden in dieser Reihenfolge ausgewertet, die höchste zuerst: Klammern, Funktionen, * / %, + -, < <= > >=, == !=, &&, ||.

Beispiele

Spezifischer Ertrag:

@energy_grid_daily / $park.peak_production_w

Einstrahlung vom Sensor, oder aus dem Wettermodell, wo der Sensor keinen Wert hat:

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Anteil der Abschaltverluste:

(@energy_shutdown_grid_daily + @energy_shutdown_external_daily) / (@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily) * 100

Regeln

• Eine Formel liest mindestens eine Metrik.
• Klammern sind ausgeglichen, und zwei Operatoren folgen nicht aufeinander, außer !.
• Eine Formel darf nicht von sich selbst abhängen, weder direkt noch über andere Formeln.
• Eine Formel arbeitet auf Tageswerten. Sie kann keine Werte innerhalb eines Tages lesen, und sie kann nicht auf frühere Zeilen zurückblicken.

Eine Formel auf Metriken umstellen

Eine Formel und eine Metrik sind in verschiedenen Sprachen geschrieben, eine Formel wird also neu geschrieben, nicht umgewandelt. In den meisten Fällen ist die Metrik kürzer, weil sie angibt, was in einem 15-Minuten-Intervall geschieht, und den Rest ihrer Verdichtung überlässt.

1. Öffnen Sie Daten-Export ▸ Glossar und klicken Sie auf Neue Metrik.
2. Beschreiben Sie die Größe dem Assistenten im Editor oder schreiben Sie den Ausdruck selbst. Die Seitenleiste listet die Serien, aus denen Sie aufbauen können.
3. Wählen Sie die Verdichtung, die zur Formel passt:

4. Prüfen Sie die Vorschau an einer Anlage und verwenden Sie die Metrik danach in einem Bericht oder exportieren Sie sie.

Die Performance Ratio, die erwartete Erzeugung und der spezifische Ertrag brauchen keine eigene Metrik. Die Sammlung hat sie: plant.pr_weather, plant.pr_pyranometer, plant.expected_weather, plant.expected_pyranometer, plant.specific_yield.

Verwandte Funktionen

• Metriken — der Nachfolger: Größen, die Ihre Organisation selbst definiert
• Metric Export — Metriken in jeder Schrittweite exportieren
• Legacy-Export-API — die Vorlagen und Links, die Formeln auswerten
• Umstieg auf den Metric Export — die berechneten Spalten und ihre Entsprechungen
• API-Tokens — ein Token Voller Zugriff für die Formel-Routen