Formules MiroxQL (référence API)

Une formule MiroxQL combine des métriques journalières de l'ancien export en une colonne calculée, par exemple un ratio de performance à partir d'une énergie et d'une cible.

MiroxQL ou Indicateurs ?

Routes de formules

Tous les chemins suivent https://service.mirox.io/api/v1/export/metric/formula. Les routes exigent une connexion ou un jeton d'API du groupe Accès complet ; un jeton Metric Export ne les atteint pas. La lecture est ouverte aux membres de l'organisation, l'écriture aux rôles d'organisation Admin, Modérateur, Gestionnaire d’actifs (technique) et Gestionnaire d’actifs (commercial).

Les formules fournies par Mirox ne peuvent être ni modifiées ni supprimées.

Champs d'une formule

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

Identifiants

Un identifiant doit être libre. 409 metric_id_taken signifie qu'une formule ou un indicateur de votre organisation, ou un indicateur de Mirox, porte déjà cet identifiant. Cela vaut aussi lorsque vous modifiez une formule existante dont l'identifiant a été pris entre-temps ; la désactiver avec active=false reste possible.

Échelle et décimales

Calculez en unités de base et convertissez avec scale. Les métriques journalières sont évaluées en unités de base (Wh, W, Wh/m²) ; une somme d'énergies avec scale=0.001 est donc exportée en kWh. scale et digits ne s'appliquent qu'à la valeur exportée. Une formule qui lit une autre formule reçoit son résultat non mis à l'échelle et non arrondi.

Niveau de calcul

Syntaxe

Références

Une métrique se lit avec @ et son identifiant. Les identifiants sont les anciens identifiants de métrique et les identifiants d'autres formules.

@energy_grid_daily
@gti_sensor_daily

Une valeur de la configuration de la centrale se lit avec $ et son chemin :

GET /config-fields répond la liste actuelle.

Opérateurs

Une comparaison répond 1 ou 0. Une division par zéro répond 0. Une métrique sans données compte pour 0.

Les opérations sont évaluées dans cet ordre, de la plus prioritaire à la moins prioritaire : parenthèses, fonctions, * / %, + -, < <= > >=, == !=, &&, ||.

Exemples

Productible spécifique :

@energy_grid_daily / $park.peak_production_w

Irradiation issue du capteur, ou du modèle météo lorsque le capteur n'a pas de valeur :

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Part des pertes par limitation :

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

Règles

• Une formule lit au moins une métrique.
• Les parenthèses sont équilibrées, et deux opérateurs ne se suivent pas, sauf !.
• Une formule ne doit pas dépendre d'elle-même, directement ou par l'intermédiaire d'autres formules.
• Une formule travaille sur des valeurs journalières. Elle ne peut pas lire de valeurs à l'intérieur d'un jour, ni revenir sur des lignes antérieures.

Transformer une formule en indicateur

Une formule et un indicateur sont écrits dans des langages différents : une formule se réécrit donc, elle ne se convertit pas. Dans la plupart des cas, l'indicateur est plus court, car il énonce ce qui se passe dans un intervalle de 15 minutes et laisse le reste à son Agrégation.

1. Ouvrez Export de données ▸ Glossaire et cliquez sur Nouvel indicateur.
2. Décrivez la grandeur à l'assistant dans l'éditeur, ou écrivez l'expression vous-même. Le panneau latéral liste les séries à partir desquelles vous pouvez construire.
3. Choisissez l'Agrégation qui correspond à la formule :

4. Vérifiez l'aperçu sur une centrale, puis utilisez l'indicateur dans un rapport ou exportez-le.

Le ratio de performance, la production attendue et le productible spécifique n'exigent pas d'indicateur de votre part. La collection les contient : plant.pr_weather, plant.pr_pyranometer, plant.expected_weather, plant.expected_pyranometer, plant.specific_yield.

Fonctionnalités associées

• Indicateurs — le successeur : les grandeurs que votre organisation définit elle-même
• Metric Export — exporter les indicateurs à chaque pas
• API de l'ancien export — les modèles et les liens qui évaluent les formules
• Migrer vers le Metric Export — les colonnes calculées et leurs équivalents
• Jetons d'API — un jeton Accès complet pour les routes de formules