Linguaggio di query MiroxQL

MiroxQL (Mirox Query Language) è il modo canonico per definire metriche calcolate personalizzate sulla piattaforma Mirox. Scrivi una breve formula che combina le tue metriche di esportazione esistenti in una nuova metrica, e questa diventa disponibile ovunque vengano utilizzate le metriche di esportazione — l'accesso programmatico ai tuoi dati passa attraverso MiroxQL e l'API di esportazione metriche, non attraverso alcuna integrazione separata di dati grezzi.

Panoramica

MiroxQL è un semplice linguaggio di espressioni per definire metriche calcolate personalizzate basate su metriche esistenti. Ti consente di creare indicatori di performance su misura, combinare più fonti di dati e implementare logiche di business personalizzate senza scrivere codice.

Apri in Mirox: crea e gestisci le tue formule nell'editor di formule sotto Esportazione dati ▸ Metriche. Nella pagina Esportazione dati, apri la scheda Metriche per aggiungere una metrica personalizzata e scrivere la sua formula MiroxQL.

Concetti chiave

Riferimenti alle metriche

Tutti i riferimenti alle metriche in MiroxQL devono essere preceduti dal simbolo @:

@energy_grid_daily
@gti_sensor_daily
@availability_technical

Gli ID delle metriche devono corrispondere a metriche di esportazione valide disponibili nel sistema. Consulta Metriche di esportazione disponibili per l'elenco completo.

Riferimenti alla configurazione

I valori di configurazione del parco possono essere referenziati usando il prefisso $ con la notazione a punti:

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

Questo consente alle formule di utilizzare valori configurati come capacità installata, posizione e dettagli costruttivi dell'impianto. I campi di configurazione disponibili sono:

Questi sono gli stessi campi proposti dall'elenco dei campi di configurazione dell'editor di formule, così puoi verificare direttamente nell'app l'insieme attuale.

Tipi di dati

MiroxQL lavora con valori numerici:

• Interi: 1000, 42, 365
• Decimali: 0.85, 3.14, 99.5
• Risultati: tutti i calcoli restituiscono numeri in virgola mobile

Operazioni supportate

Operazioni aritmetiche

Divisione per zero: restituisce automaticamente 0 invece di generare un errore.

Operazioni di confronto

Operazioni logiche

Espressioni condizionali

L'operatore ternario consente la logica condizionale:

condition ? value_if_true : value_if_false

Esempio: usa i dati del sensore se disponibili, altrimenti usa i dati meteorologici

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Funzioni

Precedenza degli operatori

Le operazioni vengono valutate nel seguente ordine (dalla più alta alla più bassa):

1. Parentesi ()
2. Funzioni max(), min()
3. Moltiplicazione, divisione, modulo *, /, %
4. Addizione, sottrazione +, -
5. Confronto <, <=, >, >=
6. Uguaglianza ==, !=
7. AND logico &&
8. OR logico ||

Usa le parentesi per modificare la precedenza: (@a + @b) * @c

Creazione di metriche personalizzate

Le formule MiroxQL possono essere utilizzate per creare metriche personalizzate calcolate su richiesta e rese disponibili per l'esportazione insieme alle metriche standard. Ogni metrica personalizzata richiede diversi parametri di configurazione:

Configurazione della metrica

ID metrica (metric_id):

• Identificatore univoco per la metrica
• Deve iniziare con una lettera o un trattino basso
• Può contenere lettere, numeri e trattini bassi
• Esempio: pr_weather_corrected, specific_yield_normalized

Nome (name):

• Nome visualizzato leggibile
• Utilizzato nelle esportazioni e nei report
• Esempio: "Performance Ratio (corretto per il meteo)"

Descrizione (description):

• Spiegazione opzionale di ciò che la metrica calcola
• Aiuta gli altri utenti a comprendere lo scopo della metrica

Unità (unit):

• Unità di misura per la metrica
• Esempio: kWh, %, Wh/W, kWh/m²

Formula (formula):

• L'espressione MiroxQL che calcola il valore della metrica
• Deve fare riferimento ad almeno una metrica esistente con il prefisso @
• Esempio: (@energy_grid_daily + @energy_shutdown_grid_daily) / @energy_report * 100

Parametri di scala e cifre

Formula: @energy_grid_daily + @energy_shutdown_grid_daily
Unit: kWh
Scale: 0.001  # Divide il risultato per 1000 durante l'esportazione

Scala (scale):

• Fattore di scala applicato al risultato durante l'esportazione
• Predefinito: 1.0 (nessuna scala)
• Valori comuni:
  • 0.001 - Converte Wh in kWh
  • 0.000001 - Converte Wh in MWh
  • 100 - Converte un rapporto in percentuale
• Formula applicata: exported_value = calculated_value * scale

Cifre (digits):

• Numero di cifre decimali per l'arrotondamento nelle esportazioni
• Intervallo: 0-10, predefinito: 2
• Applicato solo durante l'esportazione, non durante il calcolo

Periodi di calcolo e metodi di aggregazione

Il sistema supporta due metodi di aggregazione per le metriche personalizzate, configurabili durante l'esportazione tramite API.

Aggregazione giornaliera (predefinita):

La formula viene eseguita una volta al giorno utilizzando i valori giornalieri delle metriche. I risultati giornalieri vengono quindi sommati o mediati per il periodo di esportazione. Questo è ideale per le somme di energia e i calcoli di performance giornaliera.

Esempio - Formula di somma dell'energia:

Formula: @energy_grid_daily + @energy_shutdown_grid_daily

Per un'esportazione mensile:

1. Giorno 1: 1000 + 50 = 1050 kWh
2. Giorno 2: 1100 + 45 = 1145 kWh
3. ... (continua per tutti i giorni)
4. Totale mensile: somma di tutti i risultati giornalieri = 1050 + 1145 + ...

Aggregazione per periodo:

Le metriche di base vengono prima aggregate al periodo (totali settimanali/mensili), quindi la formula viene eseguita una volta su questi valori aggregati. Questo è ideale per i performance ratio e i calcoli di efficienza su periodi.

Esempio - Formula del performance ratio:

Formula: @energy_grid_daily / @energy_report * 100

Per un'esportazione mensile:

1. Energia di rete mensile: somma di tutti i valori giornalieri di @energy_grid_daily
2. Energia obiettivo mensile: somma di tutti i valori giornalieri di @energy_report
3. PR mensile: monthly_grid_energy / monthly_target_energy * 100

Esempio di metrica personalizzata

Esempio completo di una definizione di metrica personalizzata:

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

Questo crea una metrica che:

• Calcola in Wh (unità grezza)
• Esporta in kWh (scalata di 0.001)
• Arrotonda a 2 cifre decimali nelle esportazioni
• Mantiene la massima precisione per le formule dipendenti

Esempi di formule

Calcoli di base

Energia totale comprese le perdite

@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily

Resa specifica (Wh per Watt installato)

@energy_grid_daily / $park.peak_production_w

Performance Ratio (effettivo vs. obiettivo)

(@energy_grid_daily / @energy_target) * 100

Logica condizionale

Irraggiamento validato (preferisci il sensore, fallback sul meteo)

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Indicatore di utilizzo dei dati meteorologici

@gti_sensor_daily > 0 ? 0 : 100

Disponibilità limitata (mai superiore al 100%)

min(@availability_calculated, 100)

Validazione complessa

Dati del sensore validati (con controllo qualità)

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

Questa formula:

1. Verifica se esistono dati del sensore (@gti_sensor_daily > 0)
2. Valida che il sensore sia ragionevole rispetto al meteo (almeno il 20% del valore meteorologico)
3. Usa il sensore se valido, altrimenti usa i dati meteorologici

Obiettivi di produzione

Produzione teorica dal meteo

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

Questo calcola la produzione attesa in base a:

• Irraggiamento meteorologico (convertito da Wh/m² a kWh/m²)
• Capacità installata
• Efficienza di sistema presunta (0.85 o 85%)

Produzione con correzione delle perdite

max(@energy_grid_daily - @losses_noncompensable, 0)

Garantisce che il risultato non sia mai negativo usando max().

Performance ratio

Performance Ratio (corretto per le perdite)

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

Indice di performance del report

(@pr_actual_corrected / @pr_report) * 100

Analisi delle perdite

Perdite compensabili totali

@energy_shutdown_grid_daily + @energy_shutdown_external_daily

Percentuale di perdite

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

Perdite non compensabili

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

Best practice

Progettazione delle formule

1. Mantieni le formule semplici: suddividi i calcoli complessi in più metriche
2. Usa nomi significativi: assegna nomi chiari alle metriche calcolate (pr_weather_based, non calc1)
3. Documenta le assunzioni: annota fattori di efficienza, conversioni o logiche speciali
4. Gestisci i casi limite: usa la logica condizionale per evitare divisioni per zero o valori negativi
5. Valida i risultati: testa le formule con dati noti prima della distribuzione

Dipendenze tra metriche

Quando utilizzi metriche calcolate in altre formule:

1. Evita dipendenze circolari: la metrica A non può dipendere dalla metrica B se B dipende da A
2. Costruisci gerarchicamente: metriche di base → calcoli intermedi → metriche finali
3. Riutilizza i componenti: crea metriche intermedie riutilizzabili per i calcoli comuni

Conversioni di unità

Presta attenzione alle unità quando combini le metriche:

# Converti kWh/m² in Wh/m² moltiplicando per 1000
(@gti_sensor_daily * 1000)

# Converti Wh in kWh dividendo per 1000
(@production_wh / 1000)

# Normalizza l'energia per la capacità installata (Wh per Watt)
@energy_grid_daily / $park.peak_production_w

Dati nulli/mancanti

MiroxQL tratta i dati mancanti come 0. Per gestire esplicitamente i dati mancanti:

# Verifica se i dati esistono prima di usarli
@metric > 0 ? @metric : @fallback_metric

# Indica quando i dati sono mancanti
@metric > 0 ? 1 : 0

Validazione delle formule

Requisiti di sintassi

Le formule valide devono:

• Fare riferimento ad almeno una metrica (con prefisso @) o a un valore di configurazione (con prefisso $)
• Avere parentesi bilanciate
• Non avere operatori consecutivi (eccetto con !)
• Usare una sintassi degli operatori valida

Errori comuni

Integrazione con i modelli di esportazione

Le metriche calcolate che usano MiroxQL possono essere incluse nei modelli di esportazione:

1. Definisci la formula: crea una metrica personalizzata con una formula MiroxQL
2. Aggiungi al modello: includi l'ID della metrica in un modello di esportazione
3. Esporta i dati: la metrica viene calcolata su richiesta durante l'esportazione

Per la gestione dei modelli, consulta API di esportazione metriche - Sistema di modelli.

Casi d'uso

Monitoraggio delle performance

Crea KPI su misura per le tue esigenze specifiche:

• Performance ratio personalizzati
• Metriche di disponibilità corrette
• Categorizzazione delle perdite

Conformità contrattuale

Implementa calcoli specifici per il contratto:

• Garanzie di performance con esclusioni
• Perdite compensabili vs. non compensabili
• Obiettivi di produzione corretti

Analisi del portfolio

Aggrega e normalizza tra i parchi:

• Resa specifica normalizzata
• Confronti corretti per il meteo
• Benchmarking dell'efficienza

Intelligence operativa

Ricava insight utilizzabili:

• Indicatori di qualità dei dati
• Punteggi di salute del sistema
• Flag di rilevamento anomalie

Limitazioni

Considerazioni sulle performance

• Le formule vengono valutate per ogni periodo di tempo nell'esportazione
• Formule molto complesse possono influire sulle performance di esportazione
• Le dipendenze ricorsive aumentano il tempo di calcolo

Ambito di calcolo

• Le formule operano su valori aggregati giornalieri
• Non possono accedere a granularità inferiori al giorno
• Non possono eseguire calcoli con lookback o finestre mobili
• Non possono accedere a dati storici oltre la riga corrente

Disponibilità dei dati

• Le metriche calcolate richiedono che tutte le metriche dipendenti siano disponibili
• Le metriche di base mancanti producono metriche calcolate incomplete
• I valori di configurazione devono essere impostati nella configurazione del parco

Documentazione correlata

• API di esportazione metriche - Metriche di esportazione e modelli
• Report - Utilizzo delle metriche calcolate nei report
• Generazione di report esterni - Workflow automatizzati
• Architettura di raccolta delle metriche - Comprendere le metriche grezze