Querying Influxdb 18

Consultas InfluxDB 1.8

Este skill permite ejecutar consultas de lectura en InfluxDB versión 1.8 usando la API HTTP mediante curl. Solo operaciones de lectura - sin escritura.

Configuración básica

La instancia de InfluxDB se accede mediante:

• URL base: http://IP:PUERTO (configurable)
• Puerto por defecto: 8086
• Endpoint: /query
• Autenticación: No requerida en esta configuración

Estructura de comandos curl

Todas las consultas usan este formato base:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=CONSULTA_INFLUXQL"

Elementos clave:

• -G especifica método GET
• --data-urlencode codifica correctamente la query
• db= especifica la base de datos objetivo
• q= contiene la consulta InfluxQL

Parámetros opcionales útiles

Agrega estos parámetros a la URL según necesidad:

• pretty=true - Formatea JSON legible (útil para debugging)
• epoch=s - Timestamps en segundos Unix (opciones: ns, us, ms, s, m, h)
• chunked=true - Transmite resultados grandes en bloques

Ejemplo con parámetros:

curl -G 'http://192.168.1.100:8086/query?db=mydb&pretty=true&epoch=s' \
  --data-urlencode "q=SELECT * FROM cpu LIMIT 10"

Flujo de trabajo recomendado

Cuando el usuario solicite información de InfluxDB, sigue este proceso:

1. Obtener configuración

Pregunta al usuario por la IP, puerto y nombre de base de datos si no están especificados.

2. Explorar esquema

Ejecuta estos comandos para entender la estructura:

# Listar bases de datos disponibles
curl -G 'http://IP:PUERTO/query' \
  --data-urlencode "q=SHOW DATABASES"

# Listar mediciones en una DB
curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SHOW MEASUREMENTS"

# Ver campos y tipos de una medición
curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SHOW FIELD KEYS FROM nombre_medicion"

# Ver tags disponibles
curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SHOW TAG KEYS FROM nombre_medicion"

3. Consultar datos

Una vez comprendido el esquema, ejecuta las consultas apropiadas.

Consultas comunes por caso de uso

Verificación de datos

Contar puntos totales:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT COUNT(*) FROM medicion"

Ver datos más recientes:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT * FROM medicion ORDER BY time DESC LIMIT 10"

Verificar rango temporal de datos:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT FIRST(*), LAST(*) FROM medicion"

Detección de errores y gaps

Detectar intervalos sin datos (usar fill(0) para identificar gaps):

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT COUNT(campo) FROM medicion WHERE time > now() - 24h GROUP BY time(5m) fill(0)"

Los intervalos con COUNT=0 indican ausencia de datos.

Identificar valores fuera de rango:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT * FROM medicion WHERE campo > 100 AND time > now() - 1h"

Resúmenes estadísticos

Resumen completo de un campo:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT COUNT(valor) AS puntos, MEAN(valor) AS promedio, MEDIAN(valor) AS mediana, STDDEV(valor) AS desviacion, MIN(valor) AS minimo, MAX(valor) AS maximo FROM medicion WHERE time > now() - 24h"

Promedios por hora:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT MEAN(valor) FROM medicion WHERE time > now() - 7d GROUP BY time(1h)"

Máximos y mínimos diarios:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT MIN(temp), MAX(temp) FROM sensores WHERE time > now() - 30d GROUP BY time(1d)"

Análisis de valores

Valores por encima/debajo de umbral:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT * FROM medicion WHERE valor > 80 AND time > now() - 1h"

Distribución por tags:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT MEAN(valor) FROM medicion WHERE time > now() - 24h GROUP BY ubicacion"

Tendencias temporales con múltiples métricas:

curl -G 'http://IP:PUERTO/query?db=NOMBRE_DB' \
  --data-urlencode "q=SELECT MEAN(valor) AS promedio, MIN(valor) AS min, MAX(valor) AS max FROM medicion WHERE time > now() - 24h GROUP BY time(1h), region"

Sintaxis InfluxQL esencial

Filtros temporales

Formato absoluto (RFC3339):

WHERE time >= '2024-01-01T00:00:00Z' AND time < '2024-01-02T00:00:00Z'

Formato relativo (recomendado):

WHERE time > now() - 1h   -- última hora
WHERE time > now() - 24h  -- últimas 24 horas
WHERE time > now() - 7d   -- últimos 7 días

Unidades de tiempo:

• ns nanosegundos
• us o µ microsegundos
• ms milisegundos
• s segundos
• m minutos
• h horas
• d días
• w semanas

Funciones de agregación

• COUNT(campo) - cuenta puntos no nulos
• MEAN(campo) - promedio aritmético
• SUM(campo) - suma total
• MIN(campo) - valor mínimo
• MAX(campo) - valor máximo
• MEDIAN(campo) - mediana
• STDDEV(campo) - desviación estándar
• SPREAD(campo) - rango (max - min)

GROUP BY time()

Agrupa datos en intervalos temporales:

GROUP BY time(5m)   -- intervalos de 5 minutos
GROUP BY time(1h)   -- intervalos de 1 hora
GROUP BY time(1d)   -- intervalos de 1 día

Con fill() para manejar gaps:

GROUP BY time(10m) fill(0)        -- llenar con 0
GROUP BY time(10m) fill(previous) -- usar valor anterior
GROUP BY time(10m) fill(linear)   -- interpolación lineal
GROUP BY time(10m) fill(none)     -- omitir intervalos vacíos

Reglas de sintaxis importantes

1. Identificadores (nombres de mediciones, campos, tags con caracteres especiales o palabras reservadas) van entre comillas dobles: "measurement_name", "field-with-dash"

2. Valores de strings y tags van entre comillas simples: WHERE location = 'us-west'

3. El SELECT debe incluir al menos un campo (no puede ser solo tags)

4. ORDER BY solo acepta time: ORDER BY time DESC

Formato de respuesta JSON

Las respuestas siguen esta estructura:

{
  "results": [
    {
      "statement_id": 0,
      "series": [
        {
          "name": "nombre_medicion",
          "columns": ["time", "campo1", "tag1"],
          "values": [
            ["2024-01-01T00:00:00Z", 45.2, "valor_tag"],
            ["2024-01-01T00:01:00Z", 46.1, "valor_tag"]
          ]
        }
      ]
    }
  ]
}

En caso de error:

{
  "results": [
    {
      "statement_id": 0,
      "error": "database not found: mydb"
    }
  ]
}

Códigos HTTP de respuesta

• 200 OK - Consulta ejecutada (revisar JSON para errores específicos)
• 400 Bad Request - Sintaxis de query inválida
• 404 Not Found - Base de datos no existe
• 500 Internal Server Error - Error del servidor

Importante: Un código 200 no garantiza éxito - siempre verifica el campo error en la respuesta JSON.

Mejores prácticas

Optimización de performance

1. Siempre especifica rangos temporales - evita SELECT * FROM measurement sin WHERE
2. Usa LIMIT para exploración - LIMIT 100 al investigar datos nuevos
3. Selecciona campos específicos - evita SELECT * cuando solo necesitas algunos campos
4. Usa agregaciones con GROUP BY time() en lugar de puntos individuales para visualización

Manejo de errores

1. Verifica existencia de DB primero con SHOW DATABASES
2. Explora esquema antes de consultar con SHOW MEASUREMENTS, SHOW FIELD KEYS
3. Valida respuestas - chequea tanto código HTTP como campo error en JSON
4. Usa pretty=true durante desarrollo para debugging más fácil

Codificación de URLs

1. Siempre usa --data-urlencode - maneja automáticamente caracteres especiales
2. Escapa comillas en shell cuando sea necesario
3. Para queries complejas considera guardarlas en archivos y usar @archivo.txt

Ejemplo completo de workflow

# 1. Verificar que InfluxDB responde
curl -I 'http://192.168.1.100:8086/ping'

# 2. Listar bases de datos
curl -G 'http://192.168.1.100:8086/query?pretty=true' \
  --data-urlencode "q=SHOW DATABASES"

# 3. Ver mediciones disponibles
curl -G 'http://192.168.1.100:8086/query?db=telegraf&pretty=true' \
  --data-urlencode "q=SHOW MEASUREMENTS"

# 4. Inspeccionar estructura de una medición
curl -G 'http://192.168.1.100:8086/query?db=telegraf' \
  --data-urlencode "q=SHOW FIELD KEYS FROM cpu"

curl -G 'http://192.168.1.100:8086/query?db=telegraf' \
  --data-urlencode "q=SHOW TAG KEYS FROM cpu"

# 5. Obtener muestra de datos
curl -G 'http://192.168.1.100:8086/query?db=telegraf&pretty=true' \
  --data-urlencode "q=SELECT * FROM cpu LIMIT 5"

# 6. Análisis estadístico
curl -G 'http://192.168.1.100:8086/query?db=telegraf&epoch=s' \
  --data-urlencode "q=SELECT COUNT(usage_idle), MEAN(usage_idle), MIN(usage_idle), MAX(usage_idle) FROM cpu WHERE time > now() - 1h"

# 7. Detectar gaps (fill(0) muestra intervalos sin datos)
curl -G 'http://192.168.1.100:8086/query?db=telegraf' \
  --data-urlencode "q=SELECT COUNT(usage_idle) FROM cpu WHERE time > now() - 1h GROUP BY time(1m) fill(0)"

Limitaciones y consideraciones

Versión específica

• Este skill es SOLO para InfluxDB 1.8 (no compatible con 2.x)
• InfluxDB 2.x usa API y sintaxis diferentes (Flux en lugar de InfluxQL)

Operaciones permitidas

• ✅ SELECT queries (lectura de datos)
• ✅ SHOW commands (exploración de esquema)
• ❌ INSERT/WRITE (escritura de datos)
• ❌ CREATE/DROP (administración de schema)
• ❌ DELETE (eliminación de datos)

Precisión temporal

• Timestamps se almacenan en UTC
• Precisión por defecto: nanosegundos
• Usa parámetro epoch para otras precisiones

Tipos de datos

• Funciones numéricas (MEAN, SUM, etc.): solo int64 y float64
• COUNT: funciona con todos los tipos
• Los campos pueden tener diferentes tipos entre shards (evitar)

Troubleshooting común

Error: "database not found"

• Verifica nombre exacto con SHOW DATABASES
• Nombres son case-sensitive

Error: "error parsing query"

• Revisa sintaxis InfluxQL
• Verifica comillas: dobles para identificadores, simples para valores
• Usa --data-urlencode para codificación correcta

Respuesta vacía con 200 OK

• Verifica que existan datos en el rango temporal
• Comprueba filtros WHERE (tags, valores)
• Usa SELECT COUNT(*) para verificar existencia de datos

Query muy lenta

• Reduce rango temporal con WHERE time
• Usa agregaciones con GROUP BY time() en lugar de puntos individuales
• Considera usar LIMIT

Referencias adicionales

Para referencia técnica completa de InfluxQL, consulta REFERENCE.md en esta carpeta (si existe).

Documentación oficial InfluxDB 1.8:

• API HTTP: https://docs.influxdata.com/influxdb/v1.8/tools/api/
• InfluxQL: https://docs.influxdata.com/influxdb/v1.8/query_language/

Versión del skill: 1.0 Compatible con: InfluxDB OSS 1.8.x Última actualización: Basado en documentación InfluxDB 1.8