Lenguaje de consulta MiroxQL

MiroxQL (Mirox Query Language) es la forma canónica de definir métricas calculadas personalizadas en la plataforma Mirox. Escribes una fórmula corta que combina tus métricas de exportación existentes en una nueva métrica, y esta queda disponible en todos los lugares donde se utilizan las métricas de exportación: el acceso programático a tus datos se realiza a través de MiroxQL y la API de exportación de métricas, no mediante ninguna integración de datos sin procesar independiente.

Resumen

MiroxQL es un lenguaje de expresiones sencillo para definir métricas calculadas personalizadas basadas en métricas existentes. Te permite crear indicadores de rendimiento a medida, combinar múltiples fuentes de datos e implementar lógica de negocio personalizada sin escribir código.

Abrir en Mirox: crea y gestiona tus fórmulas en el editor de fórmulas, en Exportación de datos ▸ Métricas. En la página de Exportación de datos, abre la pestaña Métricas para añadir una métrica personalizada y escribir su fórmula MiroxQL.

Conceptos clave

Referencias a métricas

Todas las referencias a métricas en MiroxQL deben llevar como prefijo el símbolo @:

@energy_grid_daily
@gti_sensor_daily
@availability_technical

Los ID de métrica deben corresponder a métricas de exportación válidas y disponibles en el sistema. Consulta Métricas de exportación disponibles para ver la lista completa.

Referencias a la configuración

Los valores de configuración del parque pueden referenciarse usando el prefijo $ con notación de punto:

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

Esto permite que las fórmulas utilicen valores configurados como la potencia instalada, la ubicación y los detalles de construcción de la planta. Los campos de configuración disponibles son:

Estos son los mismos campos que muestra la lista de campos de configuración del editor de fórmulas, de modo que puedes confirmar el conjunto actual directamente en la aplicación.

Tipos de datos

MiroxQL trabaja con valores numéricos:

• Enteros: 1000, 42, 365
• Decimales: 0.85, 3.14, 99.5
• Resultados: todos los cálculos devuelven números en coma flotante

Operaciones admitidas

Operaciones aritméticas

División por cero: devuelve automáticamente 0 en lugar de generar un error.

Operaciones de comparación

Operaciones lógicas

Expresiones condicionales

El operador ternario permite la lógica condicional:

condition ? value_if_true : value_if_false

Ejemplo: usar los datos del sensor si están disponibles; de lo contrario, usar los datos meteorológicos

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Funciones

Precedencia de operadores

Las operaciones se evalúan en el siguiente orden (de mayor a menor prioridad):

1. Paréntesis ()
2. Funciones max(), min()
3. Multiplicación, división, módulo *, /, %
4. Suma, resta +, -
5. Comparación <, <=, >, >=
6. Igualdad ==, !=
7. Y lógico &&
8. O lógico ||

Usa paréntesis para anular la precedencia: (@a + @b) * @c

Creación de métricas personalizadas

Las fórmulas MiroxQL pueden utilizarse para crear métricas personalizadas que se calculan bajo demanda y quedan disponibles para exportar junto con las métricas estándar. Cada métrica personalizada requiere varios parámetros de configuración:

Configuración de la métrica

ID de métrica (metric_id):

• Identificador único de la métrica
• Debe comenzar con una letra o un guion bajo
• Puede contener letras, números y guiones bajos
• Ejemplo: pr_weather_corrected, specific_yield_normalized

Nombre (name):

• Nombre de visualización legible
• Se utiliza en exportaciones e informes
• Ejemplo: "Performance Ratio (corregido por meteorología)"

Descripción (description):

• Explicación opcional de lo que calcula la métrica
• Ayuda a otros usuarios a entender la finalidad de la métrica

Unidad (unit):

• Unidad de medida de la métrica
• Ejemplo: kWh, %, Wh/W, kWh/m²

Fórmula (formula):

• La expresión MiroxQL que calcula el valor de la métrica
• Debe referenciar al menos una métrica existente con el prefijo @
• Ejemplo: (@energy_grid_daily + @energy_shutdown_grid_daily) / @energy_report * 100

Parámetros de escala y dígitos

Formula: @energy_grid_daily + @energy_shutdown_grid_daily
Unit: kWh
Scale: 0.001  # Divide el resultado entre 1000 durante la exportación

Escala (scale):

• Factor de escala aplicado al resultado durante la exportación
• Valor predeterminado: 1.0 (sin escalado)
• Valores habituales:
  • 0.001 - Convertir Wh a kWh
  • 0.000001 - Convertir Wh a MWh
  • 100 - Convertir un ratio a porcentaje
• Fórmula aplicada: exported_value = calculated_value * scale

Dígitos (digits):

• Número de decimales para el redondeo en las exportaciones
• Rango: 0-10, valor predeterminado: 2
• Se aplica únicamente durante la exportación, no durante el cálculo

Periodos de cálculo y métodos de agregación

El sistema admite dos métodos de agregación para las métricas personalizadas, que pueden configurarse durante la exportación por API.

Agregación diaria (predeterminada):

La fórmula se ejecuta una vez al día utilizando valores de métrica diarios. Los resultados diarios se suman o se promedian para el periodo de exportación. Esto es ideal para sumas de energía y cálculos de rendimiento diarios.

Ejemplo - Fórmula de suma de energía:

Formula: @energy_grid_daily + @energy_shutdown_grid_daily

Para una exportación mensual:

1. Día 1: 1000 + 50 = 1050 kWh
2. Día 2: 1100 + 45 = 1145 kWh
3. ... (continúa para todos los días)
4. Total mensual: suma de todos los resultados diarios = 1050 + 1145 + ...

Agregación por periodo:

Las métricas base se agregan primero al periodo (totales semanales/mensuales) y luego la fórmula se ejecuta una sola vez sobre estos valores agregados. Esto es ideal para los ratios de rendimiento y los cálculos de eficiencia a lo largo de periodos.

Ejemplo - Fórmula de performance ratio:

Formula: @energy_grid_daily / @energy_report * 100

Para una exportación mensual:

1. Energía mensual de red: suma de todos los valores diarios de @energy_grid_daily
2. Energía objetivo mensual: suma de todos los valores diarios de @energy_report
3. PR mensual: monthly_grid_energy / monthly_target_energy * 100

Ejemplo de métrica personalizada

Ejemplo completo de una definición de métrica personalizada:

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

Esto crea una métrica que:

• Calcula en Wh (unidad sin procesar)
• Exporta en kWh (escalado por 0.001)
• Redondea a 2 decimales en las exportaciones
• Mantiene la precisión completa para las fórmulas dependientes

Ejemplos de fórmulas

Cálculos básicos

Energía total incluyendo pérdidas

@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily

Rendimiento específico (Wh por vatio instalado)

@energy_grid_daily / $park.peak_production_w

Performance Ratio (real vs. objetivo)

(@energy_grid_daily / @energy_target) * 100

Lógica condicional

Irradiancia validada (preferir sensor, recurrir a meteorología)

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Indicador de uso de datos meteorológicos

@gti_sensor_daily > 0 ? 0 : 100

Disponibilidad limitada (nunca superar el 100 %)

min(@availability_calculated, 100)

Validación compleja

Datos de sensor validados (con comprobación de calidad)

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

Esta fórmula:

1. Comprueba si existen datos del sensor (@gti_sensor_daily > 0)
2. Valida que el sensor es razonable en comparación con la meteorología (al menos el 20 % del valor meteorológico)
3. Usa el sensor si es válido; de lo contrario, usa los datos meteorológicos

Objetivos de producción

Producción teórica a partir de la meteorología

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

Esto calcula la producción esperada en función de:

• Irradiancia meteorológica (convertida de Wh/m² a kWh/m²)
• Potencia instalada
• Eficiencia del sistema supuesta (0,85 o 85 %)

Producción con ajuste por pérdidas

max(@energy_grid_daily - @losses_noncompensable, 0)

Garantiza que el resultado nunca sea negativo mediante max().

Performance ratios

Performance Ratio (corregido por pérdidas)

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

Índice de rendimiento del informe

(@pr_actual_corrected / @pr_report) * 100

Análisis de pérdidas

Pérdidas compensables totales

@energy_shutdown_grid_daily + @energy_shutdown_external_daily

Porcentaje de pérdidas

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

Pérdidas no compensables

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

Buenas prácticas

Diseño de fórmulas

1. Mantén las fórmulas simples: divide los cálculos complejos en varias métricas
2. Usa nombres significativos: nombra las métricas calculadas con claridad (pr_weather_based, no calc1)
3. Documenta las suposiciones: anota los factores de eficiencia, las conversiones o la lógica especial
4. Maneja los casos límite: usa lógica condicional para evitar la división por cero o los valores negativos
5. Valida los resultados: prueba las fórmulas con datos conocidos antes de implementarlas

Dependencias entre métricas

Al usar métricas calculadas en otras fórmulas:

1. Evita las dependencias circulares: la métrica A no puede depender de la métrica B si B depende de A
2. Construye de forma jerárquica: métricas base → cálculos intermedios → métricas finales
3. Reutiliza componentes: crea métricas intermedias reutilizables para cálculos comunes

Conversiones de unidades

Ten en cuenta las unidades al combinar métricas:

# Convertir kWh/m² a Wh/m² multiplicando por 1000
(@gti_sensor_daily * 1000)

# Convertir Wh a kWh dividiendo entre 1000
(@production_wh / 1000)

# Normalizar la energía por la potencia instalada (Wh por vatio)
@energy_grid_daily / $park.peak_production_w

Datos nulos/ausentes

MiroxQL trata los datos ausentes como 0. Para manejar los datos ausentes de forma explícita:

# Comprobar si existen datos antes de usarlos
@metric > 0 ? @metric : @fallback_metric

# Indicar cuándo faltan datos
@metric > 0 ? 1 : 0

Validación de fórmulas

Requisitos de sintaxis

Las fórmulas válidas deben:

• Referenciar al menos una métrica (con el prefijo @) o un valor de configuración (con el prefijo $)
• Tener los paréntesis equilibrados
• No tener operadores consecutivos (excepto con !)
• Usar una sintaxis de operadores válida

Errores comunes

Integración con plantillas de exportación

Las métricas calculadas que usan MiroxQL pueden incluirse en plantillas de exportación:

1. Define la fórmula: crea una métrica personalizada con una fórmula MiroxQL
2. Añádela a una plantilla: incluye el ID de la métrica en una plantilla de exportación
3. Exporta los datos: la métrica se calcula bajo demanda durante la exportación

Para la gestión de plantillas, consulta API de exportación de métricas - Sistema de plantillas.

Casos de uso

Monitorización del rendimiento

Crea KPI adaptados a tus necesidades específicas:

• Performance ratios personalizados
• Métricas de disponibilidad ajustadas
• Categorización de pérdidas

Cumplimiento contractual

Implementa cálculos específicos del contrato:

• Garantías de rendimiento con exclusiones
• Pérdidas compensables frente a no compensables
• Objetivos de producción ajustados

Análisis de cartera

Agrega y normaliza entre parques:

• Rendimiento específico normalizado
• Comparaciones ajustadas por meteorología
• Comparativas de eficiencia (benchmarking)

Inteligencia operativa

Obtén información accionable:

• Indicadores de calidad de los datos
• Puntuaciones de salud del sistema
• Indicadores de detección de anomalías

Limitaciones

Consideraciones de rendimiento

• Las fórmulas se evalúan para cada periodo de tiempo de la exportación
• Las fórmulas muy complejas pueden afectar al rendimiento de la exportación
• Las dependencias recursivas aumentan el tiempo de cálculo

Alcance del cálculo

• Las fórmulas operan sobre valores agregados diarios
• No pueden acceder a granularidad inferior a la diaria
• No pueden realizar cálculos de retrospectiva (lookback) ni de ventana móvil
• No pueden acceder a datos históricos más allá de la fila actual

Disponibilidad de los datos

• Las métricas calculadas requieren que todas las métricas dependientes estén disponibles
• Las métricas base ausentes dan lugar a métricas calculadas incompletas
• Los valores de configuración deben estar establecidos en la configuración del parque

Documentación relacionada

• API de exportación de métricas - Métricas y plantillas de exportación
• Informes - Uso de métricas calculadas en informes
• Generación de informes externos - Flujos de trabajo automatizados
• Arquitectura de recopilación de métricas - Comprender las métricas sin procesar