Langage de requête MiroxQL

MiroxQL (Mirox Query Language) est la manière canonique de définir des métriques calculées personnalisées sur la plateforme Mirox. Vous écrivez une courte formule qui combine vos métriques d'export existantes en une nouvelle métrique, et celle-ci devient disponible partout où les métriques d'export sont utilisées — l'accès programmatique à vos données passe par MiroxQL et l'API d'export de métriques, et non par une intégration distincte de données brutes.

Vue d'ensemble

MiroxQL est un langage d'expression simple pour définir des métriques calculées personnalisées basées sur des métriques existantes. Il vous permet de créer des indicateurs de performance sur mesure, de combiner plusieurs sources de données et d'implémenter une logique métier personnalisée sans écrire de code.

Ouvrir dans Mirox : créez et gérez vos formules dans l'éditeur de formules sous Export de données ▸ Métriques. Sur la page Export de données, ouvrez l'onglet Métriques pour ajouter une métrique personnalisée et écrire sa formule MiroxQL.

Concepts clés

Références de métriques

Toutes les références de métriques dans MiroxQL doivent être préfixées par le symbole @ :

@energy_grid_daily
@gti_sensor_daily
@availability_technical

Les ID de métriques doivent correspondre à des métriques d'export valides disponibles dans le système. Consultez Métriques d'export disponibles pour la liste complète.

Références de configuration

Les valeurs de configuration d'un parc peuvent être référencées à l'aide du préfixe $ avec la notation par points :

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

Cela permet aux formules d'utiliser des valeurs configurées telles que la puissance installée, l'emplacement et les détails de construction de la centrale. Les champs de configuration disponibles sont :

Ce sont les mêmes champs proposés par la liste des champs de configuration de l'éditeur de formules, vous pouvez donc confirmer l'ensemble actuel directement dans l'application.

Types de données

MiroxQL fonctionne avec des valeurs numériques :

• Entiers : 1000, 42, 365
• Décimaux : 0.85, 3.14, 99.5
• Résultats : tous les calculs renvoient des nombres à virgule flottante

Opérations prises en charge

Opérations arithmétiques

Division par zéro : renvoie automatiquement 0 au lieu de générer une erreur.

Opérations de comparaison

Opérations logiques

Expressions conditionnelles

L'opérateur ternaire permet une logique conditionnelle :

condition ? value_if_true : value_if_false

Exemple : utiliser les données du capteur si disponibles, sinon utiliser les données météo

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Fonctions

Priorité des opérateurs

Les opérations sont évaluées dans l'ordre suivant (du plus élevé au plus bas) :

1. Parenthèses ()
2. Fonctions max(), min()
3. Multiplication, Division, Modulo *, /, %
4. Addition, Soustraction +, -
5. Comparaison <, <=, >, >=
6. Égalité ==, !=
7. ET logique &&
8. OU logique ||

Utilisez des parenthèses pour modifier la priorité : (@a + @b) * @c

Création de métriques personnalisées

Les formules MiroxQL peuvent être utilisées pour créer des métriques personnalisées qui sont calculées à la demande et rendues disponibles pour l'export aux côtés des métriques standard. Chaque métrique personnalisée nécessite plusieurs paramètres de configuration :

Configuration de la métrique

ID de métrique (metric_id) :

• Identifiant unique de la métrique
• Doit commencer par une lettre ou un trait de soulignement
• Peut contenir des lettres, des chiffres et des traits de soulignement
• Exemple : pr_weather_corrected, specific_yield_normalized

Nom (name) :

• Nom d'affichage lisible par l'humain
• Utilisé dans les exports et les rapports
• Exemple : « Performance Ratio (corrigé météo) »

Description (description) :

• Explication facultative de ce que calcule la métrique
• Aide les autres utilisateurs à comprendre l'objectif de la métrique

Unité (unit) :

• Unité de mesure de la métrique
• Exemple : kWh, %, Wh/W, kWh/m²

Formule (formula) :

• L'expression MiroxQL qui calcule la valeur de la métrique
• Doit référencer au moins une métrique existante avec le préfixe @
• Exemple : (@energy_grid_daily + @energy_shutdown_grid_daily) / @energy_report * 100

Paramètres d'échelle et de décimales

Formule : @energy_grid_daily + @energy_shutdown_grid_daily
Unité : kWh
Échelle : 0.001  # Divise le résultat par 1000 lors de l'export

Échelle (scale) :

• Facteur d'échelle appliqué au résultat lors de l'export
• Par défaut : 1.0 (aucune mise à l'échelle)
• Valeurs courantes :
  • 0.001 - Convertir Wh en kWh
  • 0.000001 - Convertir Wh en MWh
  • 100 - Convertir un ratio en pourcentage
• Formule appliquée : exported_value = calculated_value * scale

Décimales (digits) :

• Nombre de décimales pour l'arrondi dans les exports
• Plage : 0-10, par défaut : 2
• Appliqué uniquement lors de l'export, pas lors du calcul

Périodes de calcul et méthodes d'agrégation

Le système prend en charge deux méthodes d'agrégation pour les métriques personnalisées, qui peuvent être configurées lors de l'export via l'API.

Agrégation quotidienne (par défaut) :

La formule s'exécute une fois par jour en utilisant les valeurs quotidiennes des métriques. Les résultats quotidiens sont ensuite additionnés ou moyennés pour la période d'export. C'est idéal pour les sommes d'énergie et les calculs de performance quotidiens.

Exemple - Formule de somme d'énergie :

Formule : @energy_grid_daily + @energy_shutdown_grid_daily

Pour un export mensuel :

1. Jour 1 : 1000 + 50 = 1050 kWh
2. Jour 2 : 1100 + 45 = 1145 kWh
3. ... (se poursuit pour tous les jours)
4. Total mensuel : somme de tous les résultats quotidiens = 1050 + 1145 + ...

Agrégation par période :

Les métriques de base sont d'abord agrégées sur la période (totaux hebdomadaires/mensuels), puis la formule s'exécute une fois sur ces valeurs agrégées. C'est idéal pour les ratios de performance et les calculs d'efficacité sur des périodes.

Exemple - Formule de performance ratio :

Formule : @energy_grid_daily / @energy_report * 100

Pour un export mensuel :

1. Énergie réseau mensuelle : somme de toutes les valeurs quotidiennes @energy_grid_daily
2. Énergie cible mensuelle : somme de toutes les valeurs quotidiennes @energy_report
3. PR mensuel : monthly_grid_energy / monthly_target_energy * 100

Exemple de métrique personnalisée

Exemple complet d'une définition de métrique personnalisée :

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

Cela crée une métrique qui :

• Calcule en Wh (unité brute)
• Exporte en kWh (mise à l'échelle par 0,001)
• Arrondit à 2 décimales dans les exports
• Conserve la pleine précision pour les formules dépendantes

Exemples de formules

Calculs de base

Énergie totale incluant les pertes

@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily

Productible spécifique (Wh par watt installé)

@energy_grid_daily / $park.peak_production_w

Performance ratio (réel vs. cible)

(@energy_grid_daily / @energy_target) * 100

Logique conditionnelle

Irradiance validée (préférer le capteur, repli sur la météo)

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Indicateur d'utilisation des données météo

@gti_sensor_daily > 0 ? 0 : 100

Disponibilité plafonnée (ne jamais dépasser 100 %)

min(@availability_calculated, 100)

Validation complexe

Données de capteur validées (avec contrôle de qualité)

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

Cette formule :

1. Vérifie si les données du capteur existent (@gti_sensor_daily > 0)
2. Valide que le capteur est raisonnable par rapport à la météo (au moins 20 % de la valeur météo)
3. Utilise le capteur s'il est valide, sinon utilise les données météo

Cibles de production

Production théorique à partir de la météo

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

Ceci calcule la production attendue en fonction de :

• L'irradiance météo (convertie de Wh/m² en kWh/m²)
• La puissance installée
• L'efficacité système supposée (0,85 ou 85 %)

Production avec ajustement des pertes

max(@energy_grid_daily - @losses_noncompensable, 0)

Garantit que le résultat n'est jamais négatif grâce à max().

Ratios de performance

Performance ratio (corrigé des pertes)

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

Indice de performance du rapport

(@pr_actual_corrected / @pr_report) * 100

Analyse des pertes

Pertes compensables totales

@energy_shutdown_grid_daily + @energy_shutdown_external_daily

Pourcentage de pertes

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

Pertes non compensables

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

Bonnes pratiques

Conception des formules

1. Gardez les formules simples : décomposez les calculs complexes en plusieurs métriques
2. Utilisez des noms parlants : nommez clairement les métriques calculées (pr_weather_based, pas calc1)
3. Documentez les hypothèses : notez les facteurs d'efficacité, les conversions ou la logique particulière
4. Gérez les cas limites : utilisez la logique conditionnelle pour éviter la division par zéro ou les valeurs négatives
5. Validez les résultats : testez les formules avec des données connues avant le déploiement

Dépendances entre métriques

Lors de l'utilisation de métriques calculées dans d'autres formules :

1. Évitez les dépendances circulaires : la métrique A ne peut pas dépendre de la métrique B si B dépend de A
2. Construisez hiérarchiquement : métriques de base → calculs intermédiaires → métriques finales
3. Réutilisez les composants : créez des métriques intermédiaires réutilisables pour les calculs courants

Conversions d'unités

Soyez attentif aux unités lors de la combinaison de métriques :

# Convertir kWh/m² en Wh/m² en multipliant par 1000
(@gti_sensor_daily * 1000)

# Convertir Wh en kWh en divisant par 1000
(@production_wh / 1000)

# Normaliser l'énergie par la puissance installée (Wh par watt)
@energy_grid_daily / $park.peak_production_w

Données nulles/manquantes

MiroxQL traite les données manquantes comme 0. Pour gérer explicitement les données manquantes :

# Vérifier si les données existent avant de les utiliser
@metric > 0 ? @metric : @fallback_metric

# Indiquer lorsque les données sont manquantes
@metric > 0 ? 1 : 0

Validation des formules

Exigences de syntaxe

Les formules valides doivent :

• Référencer au moins une métrique (avec le préfixe @) ou une valeur de configuration (avec le préfixe $)
• Avoir des parenthèses équilibrées
• Ne pas avoir d'opérateurs consécutifs (sauf avec !)
• Utiliser une syntaxe d'opérateur valide

Erreurs courantes

Intégration avec les modèles d'export

Les métriques calculées utilisant MiroxQL peuvent être incluses dans les modèles d'export :

1. Définir la formule : créez une métrique personnalisée avec une formule MiroxQL
2. Ajouter au modèle : incluez l'ID de la métrique dans un modèle d'export
3. Exporter les données : la métrique est calculée à la demande lors de l'export

Pour la gestion des modèles, consultez API d'export de métriques - Système de modèles.

Cas d'usage

Supervision de la performance

Créez des KPI adaptés à vos besoins spécifiques :

• Ratios de performance personnalisés
• Métriques de disponibilité ajustées
• Catégorisation des pertes

Conformité contractuelle

Implémentez des calculs spécifiques aux contrats :

• Garanties de performance avec exclusions
• Pertes compensables vs. non compensables
• Cibles de production ajustées

Analyse de portefeuille

Agrégez et normalisez entre parcs :

• Productible spécifique normalisé
• Comparaisons ajustées à la météo
• Étalonnage de l'efficacité

Intelligence opérationnelle

Dégagez des informations exploitables :

• Indicateurs de qualité des données
• Scores de santé du système
• Indicateurs de détection d'anomalies

Limitations

Considérations de performance

• Les formules sont évaluées pour chaque période de l'export
• Les formules très complexes peuvent affecter la performance de l'export
• Les dépendances récursives augmentent le temps de calcul

Portée du calcul

• Les formules opèrent sur des valeurs agrégées quotidiennement
• Ne peuvent pas accéder à une granularité infra-journalière
• Ne peuvent pas effectuer de calculs rétrospectifs ou par fenêtre glissante
• Ne peuvent pas accéder aux données historiques au-delà de la ligne courante

Disponibilité des données

• Les métriques calculées nécessitent que toutes les métriques dépendantes soient disponibles
• L'absence de métriques de base entraîne des métriques calculées incomplètes
• Les valeurs de configuration doivent être définies dans la configuration du parc

Documentation connexe

• API d'export de métriques - Métriques d'export et modèles
• Rapports - Utilisation des métriques calculées dans les rapports
• Génération de rapports externes - Flux de travail automatisés
• Architecture de collecte des métriques - Comprendre les métriques brutes