Leer cada valor bruto de un año sería lento y no cabría en un gráfico. Por eso Hermetry resume las lecturas numéricas por minuto, por hora y por día, y lee el resumen que corresponde a la ventana que pides. Esta página explica los resúmenes, cómo se elige la resolución y qué devuelve cada función de agregación.
Los resúmenes
Para cada clave numérica de cada dispositivo, el almacén guarda cinco cifras por intervalo:
| Cifra | Significado |
|---|---|
| sum | La suma de los valores del intervalo |
| count | Cuántos valores llegaron al intervalo |
| min | El valor más pequeño |
| max | El valor más grande |
| last | El valor con la marca de tiempo más reciente del intervalo |
| Nivel | Intervalo | Se conserva durante |
|---|---|---|
| Agregados de 1 minuto | 1 minuto | Tu clase de retención, como máximo 31 días |
| Agregados horarios | 1 hora | Tu clase de retención completa |
| Agregados diarios | 1 día, de medianoche a medianoche UTC | Tu clase de retención completa |
Todos los intervalos están alineados a UTC. Los resúmenes por minuto los calcula un proceso que se ejecuta cada minuto; los agregados horarios y diarios se derivan de ellos. Una lectura que llega después de que se resumiera su minuto vuelve a calcular ese minuto, de modo que las lecturas tardías se incluyen. Una lectura recién almacenada puede tardar uno o dos minutos en aparecer en los resúmenes; las lecturas brutas (ventanas de hasta 24 horas) la ven de inmediato.
Los valores de texto, true/false y JSON no se resumen. Consulta Números, texto y valores verdadero/falso.
Qué resolución lee una ventana
Con el intervalo auto (el predeterminado para gráficos y la API):
| Duración de la ventana | Resolución |
|---|---|
| Hasta 24 horas | Valores brutos, cada lectura |
| Hasta 10.000 minutos (unos 6,9 días, así que una ventana completa de 7 días ya lee horas) | 1 minuto |
| Hasta 10.000 horas (unos 416 días) | 1 hora |
| Más largas | 1 día |
Una ventana puede contener como máximo 10.000 intervalos en la resolución elegida. Si pides una resolución fija que necesitaría más (por ejemplo 1m durante 30 días), la API responde 400 con el código range_too_large. Pide un intervalo más grueso o una ventana más corta.
Una ventana que retrocede más allá de lo que conserva un nivel devuelve nada para la parte que falta. Por ejemplo, con la clase de 365 días, los intervalos 1m anteriores a 31 días ya no existen; pide 1h en su lugar.
Las funciones de agregación
Cada intervalo devuelve un valor, calculado a partir de sus cinco cifras:
| Función | Valor por intervalo | Úsala para |
|---|---|---|
avg (predeterminada) | sum / count | Temperaturas, niveles, presiones |
min | El valor más pequeño | Nivel más bajo, punto más frío |
max | El valor más grande | Picos, «si ocurrió» en claves 0/1 |
last | El último valor | Lecturas de contadores, estados, consignas |
sum | La suma de los valores | Valores que ya son cantidades por intervalo (litros en este intervalo, eventos como 1) |
count | El número de lecturas | Tasa de envío, completitud de los datos |
increase | Cuánto subió un contador | Contadores de energía y agua, totales de pulsos |
avg es un promedio simple de las lecturas del intervalo, no ponderado por tiempo. Un dispositivo que informa con más frecuencia en algunos periodos pesa más en esos periodos.
Cuando se lee una ventana bruta (hasta 24 horas), la agregación no se aplica: obtienes todos los valores almacenados. Por eso, los gráficos que muestran puntos brutos y un resumen juntos pueden mostrar más detalle del último día que de los días anteriores.
increase, para contadores
Los contadores solo crecen (kWh, m³, pulsos) hasta que se reinician desde cero. increase los convierte en consumo por intervalo:
- El valor de cada intervalo es su
lastmenos ellastdel intervalo anterior. - Si el valor bajó (el contador se reinició), el
lastdel intervalo se toma como la subida, contando desde cero. - El primer intervalo de la ventana cuenta lo que subió dentro de él: su
lastmenos sumin.
Ejemplo con intervalos horarios de un contador de energía:
| Hora | last | increase |
|---|---|---|
| 08:00 | 1,200.0 | 4,0 (primer intervalo: last 1.200,0 – min 1.196,0) |
| 09:00 | 1,212.5 | 12.5 |
| 10:00 | 1,221.0 | 8.5 |
| 11:00 | 3.0 | 3,0 (el contador se reinició) |
Notas:
- Una subida a través de un hueco se cuenta en el primer intervalo después del hueco.
- Un contador que se reinicia y luego supera su valor anterior dentro de un mismo intervalo no se detecta como reinicio.
- Usa
increasesobre el contador bruto, nunca sobre una clave que ya es una cantidad por intervalo; para esa usasum.
Uso de los resúmenes
| Dónde | Cómo se elige |
|---|---|
| Tarjetas de gráfico del panel | El ajuste Agregación de la tarjeta y la ventana temporal del panel. Consulta Tarjetas de gráfico y Fuentes de datos y parámetros. |
| La pestaña Telemetría del dispositivo | Siempre avg, con la ventana que elijas. Consulta La pestaña Telemetría del dispositivo. |
| La API | bucket y agg en GET /api/telemetry/series. Consulta La API de historial. |
| Flujos | El bloque Estadísticas calcula cifras sobre una ventana de mensajes dentro del propio flujo. Consulta Contadores, estadísticas y watchdogs. |
Días y meses locales
Los agregados diarios son días UTC. Para un total diario en otra zona horaria, lee intervalos 1h y suma tú mismo las horas de cada día local; para zonas con desfase de media hora, lee intervalos 1m (hasta 31 días atrás). Consulta el ejemplo en La API de historial.