MiroxQL Query Language

MiroxQL (Mirox Query Language) ist die kanonische Methode, um eigene berechnete Metriken auf der Mirox-Plattform zu definieren. Du schreibst eine kurze Formel, die deine vorhandenen Export-Metriken zu einer neuen Metrik kombiniert, und sie wird überall dort verfügbar, wo Export-Metriken verwendet werden — der programmatische Zugriff auf deine Daten läuft über MiroxQL und die Export-Metrik-API, nicht über eine separate Rohdaten-Integration.

Überblick

MiroxQL ist eine einfache Ausdruckssprache zum Definieren eigener berechneter Metriken auf Basis vorhandener Metriken. Sie ermöglicht es dir, maßgeschneiderte Leistungskennzahlen zu erstellen, mehrere Datenquellen zu kombinieren und eigene Geschäftslogik umzusetzen, ohne Code zu schreiben.

Was ist MiroxQL?

MiroxQL ermöglicht es dir, vorhandene Export-Metriken in neue berechnete Metriken zu transformieren und zu kombinieren. Alle Berechnungen werden serverseitig durchgeführt, was Konsistenz gewährleistet und die Notwendigkeit einer Nachbearbeitung beseitigt.

MiroxQL ist ein Markenname für die Metrik-Formel-Funktion

„MiroxQL" ist der Präsentationsname für die Funktion zur Definition eigener Metrik-Formeln. Es gibt keinen Endpunkt, der buchstäblich MiroxQL heißt — deine Formeln werden über die Metrik-Formel-API unter /v1/export/metric/formula erstellt und verwaltet und werden überall dort verfügbar, wo Export-Metriken verwendet werden.

In Mirox öffnen: Erstelle und verwalte deine Formeln im Formel-Editor unter Datenexport ▸ Metriken. Öffne auf der Seite Datenexport den Reiter Metriken, um eine eigene Metrik hinzuzufügen und ihre MiroxQL-Formel zu schreiben.

Schlüsselkonzepte

Metrik-Referenzen

Alle Metrik-Referenzen in MiroxQL müssen mit dem Symbol @ vorangestellt werden:

@energy_grid_daily
@gti_sensor_daily
@availability_technical

Die Metrik-IDs müssen gültigen, im System verfügbaren Export-Metriken entsprechen. Die vollständige Liste findest du unter Verfügbare Export-Metriken.

Konfigurations-Referenzen

Park-Konfigurationswerte können mit dem Präfix $ in Punktnotation referenziert werden:

$park.peak_production_w
$park.latitude
$park.information.inverter_max_power_w

Dadurch können Formeln konfigurierte Werte wie installierte Leistung, Standort und Anlagendetails verwenden. Die verfügbaren Konfigurationsfelder sind:

Referenz	Beschreibung	Einheit
`$park.peak_production_w`	Gesamte Spitzenleistung	W
`$park.latitude`	Geografische Breite	°
`$park.longitude`	Geografische Länge	°
`$park.self_consumption`	Eigenverbrauchsfaktor (0.0 bis 1.0)	Verhältnis
`$park.information.string_peak_power_w`	Gesamtspitzenleistung aller Strings	W
`$park.information.inverter_max_power_w`	Maximale Wechselrichterleistung	W
`$park.information.inverter_total`	Anzahl der Wechselrichter	—
`$park.information.gak_total`	Anzahl der Generatoranschlusskästen (GAKs)	—
`$park.information.strings_total`	Anzahl der Strings	—
`$park.information.modules_total`	Anzahl der Solarmodule	—

Dies sind dieselben Felder, die in der Konfigurationsfeldliste des Formel-Editors angezeigt werden, sodass du den aktuellen Stand direkt in der App überprüfen kannst.

Datentypen

MiroxQL arbeitet mit numerischen Werten:

Ganzzahlen: 1000, 42, 365
Dezimalzahlen: 0.85, 3.14, 99.5
Ergebnisse: Alle Berechnungen liefern Gleitkommazahlen

Unterstützte Operationen

Arithmetische Operationen

Operator	Beschreibung	Beispiel	Ergebnis
`+`	Addition	`@energy_grid_daily + @energy_shutdown_grid_daily`	Summe der Werte
`-`	Subtraktion	`@production_actual - @energy_grid_daily`	Differenz
`*`	Multiplikation	`@specific_yield * 1000`	Skalierter Wert
`/`	Division	`@energy_grid_daily / $park.peak_production_w`	Verhältnis
`%`	Modulo	`@value % 100`	Rest

Division durch Null: Liefert automatisch 0, anstatt einen Fehler auszulösen.

Vergleichsoperationen

Operator	Beschreibung	Beispiel	Ergebnis
`==`	Gleich	`@gti_weather_daily == 0`	Boolescher Wert (1 oder 0)
`!=`	Ungleich	`@gti_sensor_daily != 0`	Boolescher Wert
`<`	Kleiner als	`@availability_technical < 95`	Boolescher Wert
`<=`	Kleiner oder gleich	`@temperature <= 25`	Boolescher Wert
`>`	Größer als	`@gti_sensor_daily > 0`	Boolescher Wert
`>=`	Größer oder gleich	`@pr_actual >= @pr_target`	Boolescher Wert

Logische Operationen

Operator	Beschreibung	Beispiel	Ergebnis
`&&`	Logisches UND	`@gti_sensor_daily > 0 && @energy_grid_daily > 0`	Beide müssen wahr sein
`\|\|`	Logisches ODER	`@gti_sensor_daily == 0 \|\| @gti_weather_daily == 0`	Mindestens eines wahr
`!`	Logisches NICHT	`!(@availability_technical < 95)`	Invertiert booleschen Wert

Bedingte Ausdrücke

Der ternäre Operator ermöglicht bedingte Logik:

condition ? value_if_true : value_if_false

Beispiel: Verwende Sensordaten, falls verfügbar, andernfalls Wetterdaten

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Funktionen

Funktion	Beschreibung	Beispiel	Ergebnis
`max(a, b)`	Liefert das Maximum zweier Werte	`max(@energy_grid_daily, 0)`	Größerer Wert
`min(a, b)`	Liefert das Minimum zweier Werte	`min(@availability, 100)`	Kleinerer Wert

Operator-Rangfolge

Operationen werden in der folgenden Reihenfolge ausgewertet (höchste bis niedrigste):

Klammern ()
Funktionen max(), min()
Multiplikation, Division, Modulo *, /, %
Addition, Subtraktion +, -
Vergleich <, <=, >, >=
Gleichheit ==, !=
Logisches UND &&
Logisches ODER ||

Verwende Klammern, um die Rangfolge zu überschreiben: (@a + @b) * @c

Eigene Metriken erstellen

MiroxQL-Formeln können verwendet werden, um eigene Metriken zu erstellen, die bei Bedarf berechnet und neben den Standardmetriken für den Export bereitgestellt werden. Jede eigene Metrik erfordert mehrere Konfigurationsparameter:

Metrik-Konfiguration

Metrik-ID (metric_id):

Eindeutiger Bezeichner für die Metrik
Muss mit einem Buchstaben oder Unterstrich beginnen
Darf Buchstaben, Zahlen und Unterstriche enthalten
Beispiel: pr_weather_corrected, specific_yield_normalized

Name (name):

Menschenlesbarer Anzeigename
Wird in Exporten und Berichten verwendet
Beispiel: „Performance Ratio (wetterkorrigiert)"

Beschreibung (description):

Optionale Erläuterung, was die Metrik berechnet
Hilft anderen Nutzern, den Zweck der Metrik zu verstehen

Einheit (unit):

Maßeinheit für die Metrik
Beispiel: kWh, %, Wh/W, kWh/m²

Formel (formula):

Der MiroxQL-Ausdruck, der den Metrikwert berechnet
Muss mindestens eine vorhandene Metrik mit @-Präfix referenzieren
Beispiel: (@energy_grid_daily + @energy_shutdown_grid_daily) / @energy_report * 100

Parameter Scale und Digits

Rohwerte und Skalierungsfaktoren

Berechne Formeln immer in Rohwerten (nicht umgerechnet in Kilo, Mega usw.) und verwende den Parameter scale, um beim Export umzurechnen. Dies ist entscheidend, wenn Formeln von anderen Formelergebnissen abhängen.

Beispiel: Berechne Energie in Wh (roh) und setze dann scale=0.001, um in kWh zu exportieren.

Formel: @energy_grid_daily + @energy_shutdown_grid_daily
Einheit: kWh
Scale: 0.001  # Teilt das Ergebnis beim Export durch 1000

Der Skalierungsfaktor wird nur beim Datenexport angewendet, nicht bei der Formelberechnung. Dadurch wird sichergestellt, dass abhängige Formeln unskalierte Werte erhalten und präzise Berechnungen durchführen können.

Scale (scale):

Skalierungsfaktor, der beim Export auf das Ergebnis angewendet wird
Standard: 1.0 (keine Skalierung)
Übliche Werte:
- 0.001 - Umrechnung von Wh in kWh
- 0.000001 - Umrechnung von Wh in MWh
- 100 - Umrechnung eines Verhältnisses in Prozent
Angewendete Formel: exported_value = calculated_value * scale

Digits (digits):

Anzahl der Dezimalstellen für die Rundung in Exporten
Bereich: 0-10, Standard: 2
Wird nur beim Export angewendet, nicht bei der Berechnung

Rundung nur beim Export

Der Parameter digits steuert die Rundung nur für den Datenexport, nicht für Formelberechnungen. Interne Berechnungen verwenden stets die volle Genauigkeit, um kumulative Rundungsfehler zu vermeiden.

Beispiel: Eine Formel, die @energy_grid_daily / $park.peak_production_w berechnet, könnte 0.003456789 ergeben. Mit digits=4 wird sie als 0.0035 exportiert, aber andere Formeln, die diese Metrik referenzieren, verwenden weiterhin den vollständig genauen Wert 0.003456789.

Berechnungszeiträume und Aggregationsmethoden

Das System unterstützt zwei Aggregationsmethoden für eigene Metriken, die beim API-Export konfiguriert werden können.

Tägliche Aggregation (Standard):

Die Formel wird einmal pro Tag mit den täglichen Metrikwerten ausgeführt. Die täglichen Ergebnisse werden dann für den Exportzeitraum summiert oder gemittelt. Dies eignet sich ideal für Energiesummen und tägliche Performance-Berechnungen.

Beispiel – Formel für Energiesumme:

Formel: @energy_grid_daily + @energy_shutdown_grid_daily

Für einen Monatsexport:

Tag 1: 1000 + 50 = 1050 kWh
Tag 2: 1100 + 45 = 1145 kWh
... (wird für alle Tage fortgesetzt)
Monatssumme: Summe aller Tagesergebnisse = 1050 + 1145 + ...

Periodenaggregation:

Basismetriken werden zuerst zum Zeitraum aggregiert (Wochen-/Monatssummen), dann wird die Formel einmal auf diesen aggregierten Werten ausgeführt. Dies eignet sich ideal für Performance Ratios und Effizienzberechnungen über Zeiträume.

Beispiel – Formel für Performance Ratio:

Formel: @energy_grid_daily / @energy_report * 100

Für einen Monatsexport:

Monatliche Netzeinspeisung: Summe aller täglichen @energy_grid_daily-Werte
Monatliche Zielenergie: Summe aller täglichen @energy_report-Werte
Monatliche PR: monthly_grid_energy / monthly_target_energy * 100

Wahl der Aggregationsmethode

Verwende die tägliche Aggregation, um täglich zu berechnen und die Ergebnisse zu summieren/mitteln (z. B. Energiesummen). Verwende die Periodenaggregation, um auf Basis von Periodensummen zu berechnen (z. B. monatliche Performance Ratios). Die Aggregationsmethode wird bei der API-Export-Konfiguration festgelegt.

Beispiel für eine eigene Metrik

Vollständiges Beispiel einer Definition einer eigenen Metrik:

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

Dies erstellt eine Metrik, die:

in Wh (Rohwert) rechnet
in kWh exportiert (mit 0.001 skaliert)
in Exporten auf 2 Dezimalstellen rundet
die volle Genauigkeit für abhängige Formeln beibehält

Formelbeispiele

Grundlegende Berechnungen

Gesamtenergie inklusive Verluste

@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily

Spezifischer Ertrag (Wh pro installiertem Watt)

@energy_grid_daily / $park.peak_production_w

Performance Ratio (Ist vs. Ziel)

(@energy_grid_daily / @energy_target) * 100

Bedingte Logik

Validierte Einstrahlung (Sensor bevorzugen, Rückfall auf Wetter)

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Indikator für die Verwendung von Wetterdaten

@gti_sensor_daily > 0 ? 0 : 100

Gedeckelte Verfügbarkeit (überschreitet nie 100 %)

min(@availability_calculated, 100)

Komplexe Validierung

Validierte Sensordaten (mit Qualitätsprüfung)

@gti_sensor_daily > 0 && (@gti_weather_daily == 0 || (@gti_sensor_daily / @gti_weather_daily) >= 0.2) ? @gti_sensor_daily : @gti_weather_daily

Diese Formel:

Prüft, ob Sensordaten vorhanden sind (@gti_sensor_daily > 0)
Validiert, ob der Sensor im Vergleich zum Wetter plausibel ist (mindestens 20 % des Wetterwerts)
Verwendet den Sensor, falls gültig, andernfalls die Wetterdaten

Produktionsziele

Theoretische Produktion aus Wetterdaten

(@gti_weather_daily / 1000) * $park.peak_production_w * 0.85

Dies berechnet die erwartete Produktion auf Basis von:

Wettereinstrahlung (umgerechnet von Wh/m² in kWh/m²)
installierter Leistung
angenommenem Systemwirkungsgrad (0.85 bzw. 85 %)

Produktion mit Verlustanpassung

max(@energy_grid_daily - @losses_noncompensable, 0)

Stellt mit max() sicher, dass das Ergebnis nie negativ ist.

Performance Ratios

Performance Ratio (verlustkorrigiert)

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

Report Performance Index

(@pr_actual_corrected / @pr_report) * 100

Verlustanalyse

Gesamte kompensierbare Verluste

@energy_shutdown_grid_daily + @energy_shutdown_external_daily

Verlustanteil in Prozent

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

Nicht kompensierbare Verluste

max(@energy_target - @energy_grid_daily - @energy_shutdown_grid_daily - @energy_shutdown_external_daily, 0)

Best Practices

Formelgestaltung

Halte Formeln einfach: Zerlege komplexe Berechnungen in mehrere Metriken
Verwende aussagekräftige Namen: Benenne berechnete Metriken klar (pr_weather_based, nicht calc1)
Dokumentiere Annahmen: Vermerke Wirkungsgradfaktoren, Umrechnungen oder Sonderlogik
Behandle Randfälle: Verwende bedingte Logik, um Division durch Null oder negative Werte zu vermeiden
Validiere Ergebnisse: Teste Formeln mit bekannten Daten, bevor du sie einsetzt

Metrik-Abhängigkeiten

Wenn du berechnete Metriken in anderen Formeln verwendest:

Vermeide zirkuläre Abhängigkeiten: Metrik A kann nicht von Metrik B abhängen, wenn B von A abhängt
Baue hierarchisch auf: Basismetriken → Zwischenberechnungen → Endmetriken
Wiederverwende Komponenten: Erstelle wiederverwendbare Zwischenmetriken für häufige Berechnungen

Einheitenumrechnungen

Achte auf die Einheiten, wenn du Metriken kombinierst:

# Umrechnung von kWh/m² in Wh/m² durch Multiplikation mit 1000
(@gti_sensor_daily * 1000)

# Umrechnung von Wh in kWh durch Division durch 1000
(@production_wh / 1000)

# Normierung der Energie auf die installierte Leistung (Wh pro Watt)
@energy_grid_daily / $park.peak_production_w

Null-/Fehlende Daten

MiroxQL behandelt fehlende Daten als 0. Um fehlende Daten explizit zu behandeln:

# Prüfe, ob Daten vorhanden sind, bevor du sie verwendest
@metric > 0 ? @metric : @fallback_metric

# Kennzeichne, wenn Daten fehlen
@metric > 0 ? 1 : 0

Formelvalidierung

Syntaxanforderungen

Gültige Formeln müssen:

mindestens eine Metrik (mit @-Präfix) oder einen Konfigurationswert (mit $-Präfix) referenzieren
ausgeglichene Klammern haben
keine aufeinanderfolgenden Operatoren enthalten (außer mit !)
gültige Operatorsyntax verwenden

Häufige Fehler

Fehler	Ursache	Lösung
Fehlendes `@`-Präfix	`energy_grid_daily + 100`	Präfix hinzufügen: `@energy_grid_daily + 100`
Unausgeglichene Klammern	`(@a + @b`	Klammern schließen: `(@a + @b)`
Ungültige Metrik-ID	`@nonexistent_metric`	Gültige Metrik-ID verwenden
Aufeinanderfolgende Operatoren	`@a + * @b`	Überzähligen Operator entfernen: `@a * @b`
Fehlender Konfigurationswert	`$park.missing_value`	Sicherstellen, dass die Konfiguration existiert

Integration mit Export-Vorlagen

Berechnete Metriken, die MiroxQL verwenden, können in Export-Vorlagen aufgenommen werden:

Definiere die Formel: Erstelle eine eigene Metrik mit einer MiroxQL-Formel
Füge sie zur Vorlage hinzu: Nimm die Metrik-ID in eine Export-Vorlage auf
Exportiere Daten: Die Metrik wird beim Export bei Bedarf berechnet

Zur Verwaltung von Vorlagen siehe Export-Metrik-API – Vorlagensystem.

Anwendungsfälle

Performance-Monitoring

Erstelle KPIs, die auf deine spezifischen Bedürfnisse zugeschnitten sind:

eigene Performance Ratios
angepasste Verfügbarkeitsmetriken
Verlustkategorisierung

Vertragliche Konformität

Setze vertragsspezifische Berechnungen um:

Leistungsgarantien mit Ausschlüssen
kompensierbare vs. nicht kompensierbare Verluste
angepasste Produktionsziele

Portfolio-Analyse

Aggregiere und normiere über Parks hinweg:

normierter spezifischer Ertrag
wetterbereinigte Vergleiche
Effizienz-Benchmarking

Operative Erkenntnisse

Leite handlungsrelevante Erkenntnisse ab:

Datenqualitätsindikatoren
Systemzustandswerte
Markierungen zur Anomalieerkennung

Einschränkungen

Performance-Überlegungen

Formeln werden für jeden Zeitraum im Export ausgewertet
Sehr komplexe Formeln können die Export-Performance beeinträchtigen
Rekursive Abhängigkeiten erhöhen die Berechnungszeit

Berechnungsumfang

Formeln arbeiten mit täglich aggregierten Werten
Können nicht auf untertägige Granularität zugreifen
Können keine Rückblick- oder gleitenden Fensterberechnungen durchführen
Können nicht auf historische Daten über die aktuelle Zeile hinaus zugreifen

Datenverfügbarkeit

Berechnete Metriken erfordern, dass alle abhängigen Metriken verfügbar sind
Fehlende Basismetriken führen zu unvollständigen berechneten Metriken
Konfigurationswerte müssen in der Park-Konfiguration gesetzt sein