Linguagem de Consulta MiroxQL

A MiroxQL (Mirox Query Language) é a forma canónica de definir métricas calculadas personalizadas na plataforma Mirox. Escreve uma fórmula curta que combina as suas métricas de exportação existentes numa nova métrica, e esta fica disponível em todos os locais onde se usam métricas de exportação — o acesso programático aos seus dados é feito através da MiroxQL e da API de Exportação de Métricas, e não através de qualquer integração separada de dados em bruto.

Visão Geral

A MiroxQL é uma linguagem de expressões simples para definir métricas calculadas personalizadas com base em métricas existentes. Permite criar indicadores de desempenho à medida, combinar várias fontes de dados e implementar lógica de negócio personalizada sem escrever código.

Abrir na Mirox: crie e faça a gestão das suas fórmulas no editor de fórmulas em Exportação de Dados ▸ Métricas. Na página de Exportação de Dados, abra o separador Métricas para adicionar uma métrica personalizada e escrever a respetiva fórmula MiroxQL.

Conceitos-Chave

Referências a Métricas

Todas as referências a métricas na MiroxQL têm de ser prefixadas com o símbolo @:

@energy_grid_daily
@gti_sensor_daily
@availability_technical

Os IDs das métricas têm de corresponder a métricas de exportação válidas disponíveis no sistema. Consulte Métricas de Exportação Disponíveis para a lista completa.

Referências a Configurações

Os valores de configuração do parque podem ser referenciados com o prefixo $ e notação por pontos:

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

Isto permite que as fórmulas utilizem valores configurados, como a potência instalada, a localização e os detalhes de construção da central. Os campos de configuração disponíveis são:

Estes são os mesmos campos divulgados pela lista de campos de configuração do editor de fórmulas, pelo que pode confirmar o conjunto atual diretamente na aplicação.

Tipos de Dados

A MiroxQL trabalha com valores numéricos:

• Inteiros: 1000, 42, 365
• Decimais: 0.85, 3.14, 99.5
• Resultados: Todos os cálculos devolvem números de vírgula flutuante

Operações Suportadas

Operações Aritméticas

Divisão por Zero: Devolve automaticamente 0 em vez de gerar um erro.

Operações de Comparação

Operações Lógicas

Expressões Condicionais

O operador ternário permite lógica condicional:

condition ? value_if_true : value_if_false

Exemplo: Usar os dados do sensor se disponíveis, caso contrário usar os dados meteorológicos

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Funções

Precedência de Operadores

As operações são avaliadas pela seguinte ordem (da mais alta para a mais baixa):

1. Parênteses ()
2. Funções max(), min()
3. Multiplicação, Divisão, Módulo *, /, %
4. Adição, Subtração +, -
5. Comparação <, <=, >, >=
6. Igualdade ==, !=
7. E lógico (AND) &&
8. OU lógico (OR) ||

Use parênteses para anular a precedência: (@a + @b) * @c

Criar Métricas Personalizadas

As fórmulas MiroxQL podem ser usadas para criar métricas personalizadas calculadas a pedido e disponibilizadas para exportação juntamente com as métricas padrão. Cada métrica personalizada requer vários parâmetros de configuração:

Configuração da Métrica

ID da Métrica (metric_id):

• Identificador único da métrica
• Tem de começar por uma letra ou um sublinhado
• Pode conter letras, números e sublinhados
• Exemplo: pr_weather_corrected, specific_yield_normalized

Nome (name):

• Nome de apresentação legível
• Utilizado em exportações e relatórios
• Exemplo: "Performance Ratio (Corrigido pela Meteorologia)"

Descrição (description):

• Explicação opcional do que a métrica calcula
• Ajuda outros utilizadores a compreender o objetivo da métrica

Unidade (unit):

• Unidade de medida da métrica
• Exemplo: kWh, %, Wh/W, kWh/m²

Fórmula (formula):

• A expressão MiroxQL que calcula o valor da métrica
• Tem de referenciar pelo menos uma métrica existente com o prefixo @
• Exemplo: (@energy_grid_daily + @energy_shutdown_grid_daily) / @energy_report * 100

Parâmetros de Escala e Dígitos

Formula: @energy_grid_daily + @energy_shutdown_grid_daily
Unit: kWh
Scale: 0.001  # Divides result by 1000 during export

Escala (scale):

• Fator de escala aplicado ao resultado durante a exportação
• Predefinição: 1.0 (sem escala)
• Valores comuns:
  • 0.001 - Converter Wh em kWh
  • 0.000001 - Converter Wh em MWh
  • 100 - Converter rácio em percentagem
• Fórmula aplicada: exported_value = calculated_value * scale

Dígitos (digits):

• Número de casas decimais para arredondamento nas exportações
• Intervalo: 0-10, predefinição: 2
• Aplicado apenas durante a exportação, não durante o cálculo

Períodos de Cálculo e Métodos de Agregação

O sistema suporta dois métodos de agregação para métricas personalizadas, que podem ser configurados durante a exportação via API.

Agregação Diária (Predefinição):

A fórmula é executada uma vez por dia usando valores diários das métricas. Os resultados diários são depois somados ou calculados em média para o período de exportação. Isto é ideal para somas de energia e cálculos de desempenho diários.

Exemplo - Fórmula de soma de energia:

Formula: @energy_grid_daily + @energy_shutdown_grid_daily

Para uma exportação mensal:

1. Dia 1: 1000 + 50 = 1050 kWh
2. Dia 2: 1100 + 45 = 1145 kWh
3. ... (continua para todos os dias)
4. Total mensal: Soma de todos os resultados diários = 1050 + 1145 + ...

Agregação por Período:

As métricas de base são primeiro agregadas ao período (totais semanais/mensais) e depois a fórmula é executada uma vez sobre estes valores agregados. Isto é ideal para performance ratios e cálculos de eficiência ao longo de períodos.

Exemplo - Fórmula de performance ratio:

Formula: @energy_grid_daily / @energy_report * 100

Para uma exportação mensal:

1. Energia mensal injetada na rede: Soma de todos os valores diários de @energy_grid_daily
2. Energia-alvo mensal: Soma de todos os valores diários de @energy_report
3. PR mensal: monthly_grid_energy / monthly_target_energy * 100

Exemplo de Métrica Personalizada

Exemplo completo de uma definição 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"
}

Isto cria uma métrica que:

• Calcula em Wh (unidade em bruto)
• Exporta em kWh (escalada por 0.001)
• Arredonda a 2 casas decimais nas exportações
• Mantém a precisão total para fórmulas dependentes

Exemplos de Fórmulas

Cálculos Básicos

Energia Total Incluindo Perdas

@energy_grid_daily + @energy_shutdown_grid_daily + @energy_shutdown_external_daily

Produção Específica (Wh por Watt instalado)

@energy_grid_daily / $park.peak_production_w

Performance Ratio (Real vs. Alvo)

(@energy_grid_daily / @energy_target) * 100

Lógica Condicional

Irradiância Validada (Preferir Sensor, Recorrer à Meteorologia)

@gti_sensor_daily > 0 ? @gti_sensor_daily : @gti_weather_daily

Indicador de Utilização de Dados Meteorológicos

@gti_sensor_daily > 0 ? 0 : 100

Disponibilidade Limitada (Nunca Excede 100%)

min(@availability_calculated, 100)

Validação Complexa

Dados de Sensor Validados (Com Verificação de Qualidade)

@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. Verifica se existem dados de sensor (@gti_sensor_daily > 0)
2. Valida se o sensor é razoável face à meteorologia (pelo menos 20% do valor meteorológico)
3. Usa o sensor se for válido, caso contrário usa os dados meteorológicos

Alvos de Produção

Produção Teórica a partir da Meteorologia

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

Isto calcula a produção esperada com base em:

• Irradiância meteorológica (convertida de Wh/m² para kWh/m²)
• Potência instalada
• Eficiência assumida do sistema (0.85 ou 85%)

Produção com Ajuste de Perdas

max(@energy_grid_daily - @losses_noncompensable, 0)

Garante que o resultado nunca é negativo, usando max().

Performance Ratios

Performance Ratio (Corrigido por Perdas)

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

Índice de Desempenho do Relatório

(@pr_actual_corrected / @pr_report) * 100

Análise de Perdas

Total de Perdas Compensáveis

@energy_shutdown_grid_daily + @energy_shutdown_external_daily

Percentagem de Perdas

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

Perdas Não Compensáveis

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

Boas Práticas

Conceção de Fórmulas

1. Mantenha as Fórmulas Simples: Divida cálculos complexos em várias métricas
2. Use Nomes Significativos: Nomeie as métricas calculadas de forma clara (pr_weather_based, e não calc1)
3. Documente Pressupostos: Registe fatores de eficiência, conversões ou lógica especial
4. Trate Casos Limite: Use lógica condicional para evitar divisão por zero ou valores negativos
5. Valide os Resultados: Teste as fórmulas com dados conhecidos antes da implementação

Dependências de Métricas

Ao usar métricas calculadas noutras fórmulas:

1. Evite Dependências Circulares: A Métrica A não pode depender da Métrica B se B depender de A
2. Construa Hierarquicamente: Métricas de base → cálculos intermédios → métricas finais
3. Reutilize Componentes: Crie métricas intermédias reutilizáveis para cálculos comuns

Conversões de Unidades

Tenha atenção às unidades ao combinar métricas:

# Convert kWh/m² to Wh/m² by multiplying by 1000
(@gti_sensor_daily * 1000)

# Convert Wh to kWh by dividing by 1000
(@production_wh / 1000)

# Normalize energy by installed capacity (Wh per Watt)
@energy_grid_daily / $park.peak_production_w

Dados Nulos/em Falta

A MiroxQL trata os dados em falta como 0. Para tratar explicitamente os dados em falta:

# Check if data exists before using it
@metric > 0 ? @metric : @fallback_metric

# Indicate when data is missing
@metric > 0 ? 1 : 0

Validação de Fórmulas

Requisitos de Sintaxe

As fórmulas válidas têm de:

• Referenciar pelo menos uma métrica (com o prefixo @) ou um valor de configuração (com o prefixo $)
• Ter parênteses equilibrados
• Não ter operadores consecutivos (exceto com !)
• Usar sintaxe de operador válida

Erros Comuns

Integração com Modelos de Exportação

As métricas calculadas com MiroxQL podem ser incluídas em modelos de exportação:

1. Definir a Fórmula: Crie uma métrica personalizada com uma fórmula MiroxQL
2. Adicionar ao Modelo: Inclua o ID da métrica num modelo de exportação
3. Exportar Dados: A métrica é calculada a pedido durante a exportação

Para a gestão de modelos, consulte API de Exportação de Métricas - Sistema de Modelos.

Casos de Uso

Monitorização de Desempenho

Crie KPIs adaptados às suas necessidades específicas:

• Performance ratios personalizados
• Métricas de disponibilidade ajustadas
• Categorização de perdas

Conformidade Contratual

Implemente cálculos específicos do contrato:

• Garantias de desempenho com exclusões
• Perdas compensáveis vs. não compensáveis
• Alvos de produção ajustados

Análise de Portefólio

Agregue e normalize entre parques:

• Produção específica normalizada
• Comparações ajustadas pela meteorologia
• Benchmarking de eficiência

Inteligência Operacional

Obtenha informações acionáveis:

• Indicadores de qualidade dos dados
• Pontuações de saúde do sistema
• Sinalizadores de deteção de anomalias

Limitações

Considerações de Desempenho

• As fórmulas são avaliadas para cada período de tempo na exportação
• Fórmulas muito complexas podem afetar o desempenho da exportação
• As dependências recursivas aumentam o tempo de cálculo

Âmbito de Cálculo

• As fórmulas operam sobre valores agregados diariamente
• Não conseguem aceder a granularidade infradiária
• Não conseguem efetuar cálculos de lookback ou de janela móvel
• Não conseguem aceder a dados históricos para além da linha atual

Disponibilidade de Dados

• As métricas calculadas requerem que todas as métricas dependentes estejam disponíveis
• A ausência de métricas de base resulta em métricas calculadas incompletas
• Os valores de configuração têm de estar definidos na configuração do parque

Documentação Relacionada

• API de Exportação de Métricas - Métricas de exportação e modelos
• Relatórios - Usar métricas calculadas em relatórios
• Geração Externa de Relatórios - Fluxos de trabalho automatizados
• Arquitetura de Recolha de Métricas - Compreender as métricas em bruto