querying-influxdb-18
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.
When & Why to Use This Skill
This Claude skill enables seamless read-only interaction with InfluxDB 1.8 time-series databases via the HTTP API. It simplifies complex data retrieval by automating InfluxQL queries for schema exploration, statistical analysis, and data integrity verification, making it an essential tool for developers and SREs managing legacy time-series data.
Use Cases
- Schema Exploration: Automatically discover available databases, measurements, field keys, and tag keys to understand the data structure without manual documentation.
- Data Integrity Auditing: Detect gaps in time-series data by using time-grouping and fill(0) functions to identify periods of missing metrics.
- Statistical Reporting: Generate comprehensive summaries including mean, median, standard deviation, and min/max values for specific metrics over custom time ranges.
- Performance Troubleshooting: Quickly identify and retrieve data points that exceed specific thresholds or fall outside of expected ranges to diagnose system anomalies.
- Trend Analysis: Aggregate high-frequency data into hourly or daily averages to analyze long-term patterns and system behavior trends.
| 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:
-Gespecifica método GET--data-urlencodecodifica correctamente la querydb=especifica la base de datos objetivoq=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:
nsnanosegundosusoµmicrosegundosmsmilisegundosssegundosmminutoshhorasddíaswsemanas
Funciones de agregación
COUNT(campo)- cuenta puntos no nulosMEAN(campo)- promedio aritméticoSUM(campo)- suma totalMIN(campo)- valor mínimoMAX(campo)- valor máximoMEDIAN(campo)- medianaSTDDEV(campo)- desviación estándarSPREAD(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 measurementsin WHERE - Usa LIMIT para exploración -
LIMIT 100al 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
erroren 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
epochpara 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-urlencodepara 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