SensorWave Shell

Shell interactivo (REPL) para la base de datos de series temporales SensorWave.

Descripción

SensorWave Shell proporciona una interfaz de línea de comandos tipo SQL para interactuar con bases de datos SensorWave, permitiendo:

• Crear y gestionar series temporales
• Insertar y consultar datos
• Administrar reglas del motor de reglas
• Operaciones locales sin necesidad de configuración de red
• Consultas globales a través del despachador en la nube

Modos de Operación

El shell soporta dos modos de operación:

Modo Edge (Local)

Conexión directa a una base de datos local con acceso completo a todas las operaciones:

• Crear, modificar y eliminar series
• Insertar datos
• Consultar datos
• Gestionar reglas

swshell -db ./mi_base_datos

Modo Despachador (Nube)

Conexión al despachador para consultas globales distribuidas. En este modo solo están disponibles operaciones de lectura:

• Consultar datos (SELECT)
• Listar series (LIST SERIES)
• Describir series (DESCRIBE)
• Listar nodos conectados (LIST NODES)
• Ver estado (STATUS)

swshell -dispatcher http://despachador:8080

Nota: Los comandos de escritura (CREATE, DROP, INSERT) no están disponibles en modo despachador.

Instalación

Requisitos

• Go 1.21 o superior

Desde código fuente

git clone https://github.com/cbiale/sensorwave-shell.git
cd sensorwave-shell
go build -o swshell ./cmd/swshell

Con go install

go install github.com/cbiale/sensorwave-shell/cmd/swshell@latest

Uso

Iniciar el shell

# Sin conexión (modo interactivo)
swshell

# Modo edge: conectar a base de datos local
swshell ./mi_base_datos
swshell -db ./datos

# Modo despachador: conectar a la nube
swshell -dispatcher http://despachador:8080

Opciones de línea de comandos

Opción	Descripción
-db <path>	Ruta a la base de datos local (modo edge)
-dispatcher <url>	URL del despachador (modo nube, solo lectura)
-version	Mostrar versión
-help	Mostrar ayuda

Comandos

Conexión

-- Conectar a base de datos local (modo edge)
USE ./mi_base_datos

-- Conectar a base de datos con tags iniciales
USE ./mi_base_datos TAGS nombre=invernadero,zona=norte

-- Conectar al despachador (modo nube)
CONNECT http://despachador:8080

-- Desconectar del despachador
DISCONNECT

Tags de Base de Datos

Los tags permiten asociar metadatos a la base de datos (nombre, ubicación, zona, etc.). Estos tags se sincronizan automáticamente con S3 cuando está configurado.

-- Ver tags actuales de la base de datos
SHOW TAGS

-- Establecer tags de la base de datos
SET TAGS nombre=invernadero,ubicacion=sala1,zona=norte

-- Actualizar tags (reemplaza todos los existentes)
SET TAGS nombre=sensor_nuevo,ubicacion=exterior

-- Eliminar todos los tags
SET TAGS NONE

Nota: Los tags se persisten en PebbleDB y se mantienen entre reinicios.

Series

-- Crear una serie
CREATE SERIES sensor01/temperatura TYPE Real COMPRESSION Xor BLOCK_COMPRESSION LZ4

-- Crear serie con tags
CREATE SERIES sensor01/temperatura TYPE Real TAGS ubicacion=sala1,tipo=DHT22

-- Listar todas las series
LIST SERIES

-- Listar series por patrón
LIST SERIES sensor01/*

-- Ver detalles de una serie
DESCRIBE sensor01/temperatura

-- Eliminar una serie
DROP SERIES sensor01/temperatura

Tipos de datos soportados

Tipo	Descripción
Boolean	Valores true/false
Integer	Números enteros (int64)
Real	Números de punto flotante (float64)
Text	Cadenas de texto

Algoritmos de compresión

Nivel 1 (valores):

Algoritmo	Descripción	Tipos compatibles
SinCompresion	Sin compresión	Todos
DeltaDelta	Delta-of-delta	Integer, Real
Xor	XOR (Gorilla)	Real
RLE	Run-Length Encoding	Todos
Bits	Compresión de bits	Integer
Diccionario	Codificación por diccionario	Text

Nivel 2 (bloques):

Algoritmo	Descripción
Ninguna	Sin compresión
LZ4	Rápido, compresión moderada
ZSTD	Mejor compresión, más lento
Snappy	Muy rápido, compresión baja
Gzip	Compatible, compresión moderada

Inserción de datos

-- Insertar con timestamp automático (now)
INSERT INTO sensor01/temperatura VALUES (23.5)

-- Insertar con timestamp específico
INSERT INTO sensor01/temperatura VALUES (now, 23.5)
INSERT INTO sensor01/temperatura VALUES ('now-1h', 22.0)
INSERT INTO sensor01/temperatura VALUES (1704067200, 21.5)

-- Insertar diferentes tipos
INSERT INTO motor01/estado VALUES (true)
INSERT INTO contador/total VALUES (42)
INSERT INTO dispositivo/status VALUES ('activo')

Consulta de datos

-- Consultar datos (últimas 24 horas por defecto)
SELECT * FROM sensor01/temperatura

-- Consultar con rango de tiempo
SELECT * FROM sensor01/temperatura WHERE time > now-1h
SELECT * FROM sensor01/temperatura WHERE time > now-24h AND time < now

-- Limitar resultados
SELECT * FROM sensor01/temperatura LIMIT 100

-- Último punto
SELECT LAST FROM sensor01/temperatura

-- Múltiples agregaciones
SELECT AVG, MAX, MIN, COUNT FROM sensor/temp WHERE time > 'now-1h'

-- Con GROUP BY (downsampling)
SELECT AVG, MAX, MIN FROM sensor/temp WHERE time > 'now-24h' GROUP BY 1h

Agregaciones disponibles

Agregación	Descripción
AVG	Promedio
MAX	Máximo
MIN	Mínimo
SUM	Suma
COUNT	Cantidad de puntos

Formatos de timestamp

Formato	Ejemplo
now	Momento actual
now-Xh	X horas atrás
now-Xd	X días atrás
Unix segundos	1704067200
Unix milisegundos	1704067200000
Unix nanosegundos	1704067200000000000
ISO 8601	2024-01-01T12:00:00
Fecha/hora	2024-01-01 12:00:00

Reglas

-- Listar reglas
LIST RULES

-- Crear una regla
CREATE RULE alerta_temp
  WHEN AVG(sensor/temp) > 30 WINDOW 5m
  THEN LOG 'temperatura_alta'

-- Crear regla con múltiples condiciones
CREATE RULE regla_critica
  WHEN AVG(sensor/temp) > 30 WINDOW 5m
  AND COUNT(sensor/temp) > 10 WINDOW 5m
  THEN LOG 'condicion_multiple'

-- Crear regla con acción de publicación
CREATE RULE control_ventilador
  WHEN AVG(*/temp) > 28 WINDOW 5m
  THEN PUBLICAR_MQTT 'actuadores/{serie_0}/ventilador' WITH comando=encender

-- Eliminar una regla
DROP RULE alerta_temperatura

-- Habilitar motor de reglas
ENABLE RULES

-- Deshabilitar motor de reglas
DISABLE RULES

Nodos (solo modo despachador)

-- Listar nodos conectados al despachador
LIST NODES

Sistema

-- Ver estado del sistema
STATUS

-- Cambiar base de datos (modo edge)
USE ./otra_base_datos

-- Conectar al despachador (modo nube)
CONNECT http://despachador:8080

-- Desconectar del despachador
DISCONNECT

-- Limpiar pantalla
CLEAR

-- Ayuda
HELP
HELP create
HELP select

-- Salir
EXIT
QUIT
\q

Consultas Globales y Nodos No Disponibles

Cuando se conecta al despachador, las consultas se distribuyen a todos los nodos edge registrados. Si algún nodo no responde (por problemas de red, mantenimiento, etc.), el shell muestra una advertencia indicando qué nodos no estuvieron disponibles:

sensorwave(dispatcher)> SELECT * FROM sensor/* WHERE time > now-1h

Serie          │ Tiempo                    │ Valor
───────────────┼───────────────────────────┼───────
nodo1/sensor/t │ 2026-01-05 10:30:00       │ 25.3
nodo2/sensor/t │ 2026-01-05 10:30:00       │ 23.1

⚠ Advertencia: Los siguientes nodos no respondieron: nodo3, nodo4

Esto permite identificar problemas de conectividad y saber que los resultados pueden estar incompletos.

Características

• Modo dual: Conexión a base de datos local (edge) o despachador (nube)
• Autocompletado: Presione TAB para autocompletar comandos
• Historial: Las flechas arriba/abajo navegan el historial de comandos
• Colores: Salida con colores para mejor legibilidad
• Formato tabla: Resultados mostrados en tablas formateadas
• Advertencias: Indicación de nodos no disponibles en consultas globales

Dependencias

• SensorWave - Base de datos de series temporales
• readline - Biblioteca readline para Go
• color - Colores en terminal
• tablewriter - Tablas ASCII

Licencia

MIT License

Autor

Claudio Omar Biale - Universidad de Buenos Aires