name	querying-influxdb-18
description	Ejecuta consultas de lectura (queries) en InfluxDB 1.8 mediante la API HTTP usando curl. Permite verificar datos, detectar errores, crear resúmenes estadísticos y analizar valores en bases de datos de series temporales. Usa exclusivamente operaciones SELECT y SHOW en InfluxQL. Configura IP y puerto de forma flexible. No requiere autenticación.

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

Identificadores (nombres de mediciones, campos, tags con caracteres especiales o palabras reservadas) van entre comillas dobles: "measurement_name", "field-with-dash"
Valores de strings y tags van entre comillas simples: WHERE location = 'us-west'
El SELECT debe incluir al menos un campo (no puede ser solo tags)
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

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

Manejo de errores

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

Codificación de URLs

Siempre usa --data-urlencode - maneja automáticamente caracteres especiales
Escapa comillas en shell cuando sea necesario
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

querying-influxdb-18

Install Skill

SKILL.md