Esta página describe Calíope 1.8, la versión que estoy construyendo ahora mismo. La 1.7 está en la App Store para Mac, iPad, iPhone, Apple Watch, Apple TV y Apple Vision Pro. El changelog dice en qué versión llegó cada función.
Añade un botón «Abrir en Calíope» a cada tema. Sólo funciona con la app instalada.
Cómo buscar en Query DSL, SQL, ES|QL o PPL, cómo se pagina, qué enseñan las agregaciones y «explicar», y por qué la Consulta sólo lee.
Dónde está: Espacio de Trabajo › Herramientas › Consulta
Aplica a:ElasticsearchOpenSearch
La Consulta manda al clúster lo que escribes, por la sesión abierta. Ejecutar (⌘↩) la ejecuta y Detener (⌘.) deja de esperar la respuesta: lo que el servidor ya empezó puede terminar igual. Mientras corre, la búsqueda sale en Actividad con su tiempo transcurrido, y también se detiene desde ahí.
El lenguaje
El selector de lenguaje de la barra enseña sólo los lenguajes del producto de la sesión. Los dos tienen Query DSL —el cuerpo JSON de _search— y SQL.
Elasticsearch
Elasticsearch tiene además ES|QL, su lenguaje de tuberías: FROM demo_productos | WHERE precio > 40 | LIMIT 10.
OpenSearch
OpenSearch tiene además PPL, su lenguaje de tuberías: source=demo_productos | where precio > 40 | head 10.
Query DSL
El cuerpo va entero a _search de los índices escritos en Índices: vacío son todos, y varios van separados por comas. Elegir un índice los lista. El menú Página: 50 dice cuántos documentos trae cada página (50 si no lo cambias), salvo que el cuerpo lleve su propio size, que manda. Un JSON roto lo rechaza el servidor, y el error dice dónde está la errata: la línea y la columna, o el byte del cuerpo.
Las páginas y el total Siguiente página pide la siguiente. Si la búsqueda ordena (sort), va por search_after, que sigue desde el último documento recibido y no tiene límite. Si no ordena, va por from, que el servidor corta en 10 000 documentos, y la vista lo avisa. El servidor deja de contar en 10 000 y el total sale como «10 000 o más»; Total exacto le pide contarlos todos (track_total_hits), a costa de tiempo.
Lo que se ve Documentos enseña cada documento plegado en una línea, con su puntuación; ábrelo para ver su _source entero. Tabla pone los campos en columnas, con los objetos anidados aplanados. Si el cuerpo lleva aggs, Agregaciones salen debajo, como árbol. Explicar, en cada documento, le pregunta al servidor por qué casa con la búsqueda (_explain) y enseña cómo calculó su puntuación.
SQL, ES|QL y PPL
En estos lenguajes el índice va dentro de la consulta (FROM, source=), y la respuesta es una tabla. La cabecera de cada columna lleva el tipo que declara el servidor, que no siempre coincide entre lenguajes ni entre productos. Si la licencia del clúster no incluye un lenguaje, lo dice el servidor; la licencia básica de Elasticsearch trae SQL y ES|QL.
Elasticsearch
Traducir a Query DSL, en SQL, le pide a Elasticsearch el Query DSL equivalente (_sql/translate) y lo abre en Query DSL, con el índice del FROM ya puesto.
OpenSearch
OpenSearch no traduce SQL a Query DSL: sólo da el plan de su motor. Por eso, con OpenSearch, la barra no trae Traducir a Query DSL.
Sólo lee
La Consulta no escribe: el cuerpo de Query DSL va siempre a _search, SQL, ES|QL y PPL sólo consultan, y un DELETE escrito en SQL no se envía. No hay aquí borrado ni actualización por consulta (_delete_by_query, _update_by_query).
Qué enseña cada pestaña de un índice, qué se puede escribir y cómo, adónde va el registro de lentas y por qué no hay reindexado.
Dónde está: Espacio de Trabajo › Herramientas › Índices
Aplica a:ElasticsearchOpenSearch
La pestaña tiene tres secciones, en el selector de la barra: Índices, Plantillas y Pipelines. Recargar vuelve a leer la que se ve.
Índices
A la izquierda, los índices del clúster con su salud —un glifo y su nombre, nunca sólo un color—, sus documentos y su tamaño. Los de sistema (los que empiezan por punto y los que el servidor oculta) van plegados en su grupo. La cifra de documentos de la lista es la de Lucene, que cuenta aparte cada objeto de un campo nested; los que devuelve una búsqueda están en Estadísticas. Elige un índice y a la derecha sale su detalle, en pestañas que se leen al abrirlas:
- Campos: el mapping como árbol, cada campo con su tipo, sus parámetros y sus subcampos.
- Ajustes: los ajustes escritos en el índice (no los de omisión), con el umbral de lentas delante.
- Shards: cada shard, primario o réplica, con su estado, su nodo y, si no tiene nodo, el motivo.
- Alias: los alias que apuntan al índice.
- Documentos: una muestra de los documentos, de 25 en 25.
- Estadísticas: los documentos de primer nivel junto a los de Lucene, el tamaño y los contadores de actividad, que suman desde que el índice se abrió en su nodo.
Los documentos
La muestra va en el orden en que el índice los guarda y dice el total exacto. Sólo recorre los primeros 10 000 (index.max_result_window): más allá la pantalla lo dice, y para recorrer un índice entero está la Consulta, que pagina con search_after.
Lo que se escribe Nuevo índice…, en la barra, abre el JSON de un índice nuevo, con un shard, sin réplicas y el mapping vacío. Borrar índice…, en el detalle, pregunta nombrando el índice y cuántos documentos tiene; en uno de sistema no aparece. En Documentos, Nuevo documento… crea un documento con el _id que escribas —si ya existe, el servidor lo rechaza y no lo sustituye— o con uno del servidor si lo dejas vacío. Editar documento… sustituye el documento entero: un campo que quites en la hoja desaparece. Y sólo si nadie lo cambió desde que lo leíste; si no, el servidor lo rechaza y no pisa el cambio del otro. Borrar documento… pregunta nombrando su _id. Todo pasa por la protección de la conexión, y con la etiqueta de solo lectura nada de esto aparece.
El registro de lentas Editar umbral de lentas…, en Ajustes, fija a partir de cuánto se escribe una búsqueda lenta en el registro: la fase de consulta y la de recuperación, cada una en aviso e info. Se escribe un tiempo con su unidad (500ms, 2s); -1 lo apaga, y vacío vuelve al de omisión, que no registra nada.
OpenSearch
En OpenSearch la hoja trae además el nivel del registro (index.search.slowlog.level).
El registro no lo guarda Calíope: lo escribe el servidor. En una instalación de paquete va a su directorio de registros (path.logs), a un archivo <clúster>_index_search_slowlog; en un contenedor, a la salida del contenedor (docker logs).
Plantillas y Pipelines
Son del clúster, no de un índice, y sólo se leen. Cada fila resume la plantilla (sus patrones, su prioridad y de qué plantillas se compone) o el pipeline (su descripción y cuántos procesadores tiene); ábrela para ver su JSON entero. Las plantillas antiguas (_template) también salen, marcadas como tales. Las que el servidor declara suyas y las que empiezan por punto van plegadas en su grupo. Calíope no las edita: se cambian por la API.
Lo que no hace
No hay reindexado (_reindex) ni cambio de tipo de un campo existente: el servidor no cambia el tipo de un campo que ya tiene datos, y copiar un índice en otro es un trabajo largo del servidor que se lanza por la API.
Qué quieren decir verde, amarillo y rojo, cómo se cuentan los nodos, qué son los papeles y cómo leer por qué un shard no tiene nodo.
Dónde está: Espacio de Trabajo › Herramientas › Clúster
Aplica a:ElasticsearchOpenSearch
La pestaña lee el clúster al abrirla y con Actualizar; no se refresca sola, porque el clúster no avisa de sus cambios.
La salud
Arriba va la salud con su glifo y su nombre, nunca sólo un color:
- green: todos los shards, primarios y réplicas, tienen nodo.
- yellow: todos los primarios tienen nodo, pero alguna réplica no. Los datos se leen y se escriben enteros; lo que falta es la copia que daría la réplica si un nodo cayera.
- red: algún primario no tiene nodo, y los documentos de ese shard no se pueden leer ni escribir.
Debajo, cuántos nodos responden de los que el clúster espera. La cuenta sale de los nodos que la sesión ha visto y de la configuración de votación del clúster, así que un nodo que cayó antes de conectar también se cuenta: se nombra por su identificador, porque su nombre no lo dice nadie. Luego el master (_cat/master) y los shards: activos, relocalizando, inicializando y sin asignar. Al caer un nodo, sus réplicas esperan un minuto a que vuelva (index.unassigned.node_left.delayed_timeout) antes de copiarse en otro, y la cifra lo dice entre paréntesis.
Nodos
Una fila por nodo con sus papeles, heap, RAM, CPU, carga, disco, shards y versión. En Papeles van las letras de node.role: m master, d datos, i ingesta, r cliente remoto, l aprendizaje automático, t transformación, v sólo voto, y los niveles de datos h caliente, w templado, c frío, f congelado y s contenido. La leyenda va escrita bajo la tabla, y en el Mac con el puntero encima se leen enteras.
Shards con problemas
Los shards que no están activos: primero los sin asignar, los primarios antes que las réplicas y los índices del usuario antes que los de sistema. El primero sin asignar se explica con POST /_cluster/allocation/explain: Motivo (por ejemplo NODE_LEFT, el nodo se fue), ¿Se puede asignar? y lo que decide cada nodo. Explicación del servidor es el texto del servidor tal cual, en inglés. Un caso frecuente: con dos nodos, un índice de dos réplicas no tiene sitio para la segunda, porque un nodo no guarda dos copias del mismo shard (same_shard), y el clúster sigue en amarillo hasta que vuelva el tercero.
Tareas del clúster en cola y Recuperaciones en curso
Las tareas del clúster que esperan turno (_cat/pending_tasks) y las copias de shards que están en marcha (_cat/recovery).
Si una parte no se pudo leer, lleva su aviso y las demás se enseñan igual. La pestaña sólo lee: no reasigna shards ni cambia ajustes del clúster.
Qué mide cada tarjeta, por qué el aviso del heap sale al 75 %, por qué las tasas son diferencias entre dos lecturas y qué quiere decir un rechazo en un thread pool.
Dónde está: Espacio de Trabajo › Herramientas › Nodo
Aplica a:ElasticsearchOpenSearch
La pestaña lee el nodo al abrirla y, mientras está delante, cada 5 s; al cambiar de pestaña deja de leer. Mientras se lee sola, Actividad lo enseña como «Nodo de búsqueda, cada 5 s». Actualizar lo lee en el momento.
Nodo
Por omisión es el nodo que contesta a la sesión. Si el clúster tiene más de uno, el selector deja elegir otro.
Las tarjetas
- Heap de la JVM: lo ocupado sobre el máximo. Desde el 75 % lleva aviso con glifo y texto: es el umbral en el que Elastic aconseja investigar la presión de memoria, porque por encima la JVM pasa más tiempo recolectando y los circuit breakers, que cortan una petición antes de que el nodo se quede sin memoria, están más cerca de saltar.
- Recolecciones de basura: las de la generación joven y las de la vieja, con el tiempo que llevan; que las viejas crezcan deprisa es la señal de un heap que no da abasto.
- CPU: la de la máquina y, debajo, la del proceso del nodo.
- Disco: lo ocupado es el total menos lo disponible. Desde el 85 % lleva aviso: es el umbral bajo de disco del clúster (cluster.routing.allocation.disk.watermark.low), y por encima el clúster deja de asignar réplicas a ese nodo.
- Consultas por segundo y Documentos indexados por segundo: la primera, con la latencia media de las consultas del intervalo.
Las tasas son diferencias
El servidor sólo da contadores acumulados desde que arrancó el nodo. Una tasa es la diferencia entre dos lecturas dividida por el tiempo que pasó entre ellas según el reloj del nodo, así que la primera lectura dice «Hace falta una segunda lectura» y la cifra llega con la siguiente. Debajo va el total desde el arranque.
Thread pools
Cada pool con sus hilos, los activos, la cola, los rechazados y los completados. Cuando la cola de un pool se llena, el nodo rechaza la petición siguiente con un 429 en vez de esperar. Los pools con rechazos se destacan con un glifo, y los que no tienen actividad van plegados. Rechazos y completados se cuentan desde el arranque: una cifra alta puede ser antigua, y lo que importa es si crece entre lecturas.
Ficha del nodo
La versión, los papeles, la dirección, el sistema operativo, los procesadores, la JVM, el heap máximo, las rutas y los plugins.
Hilos calientes
Con Leer hilos calientes el nodo muestrea medio segundo y devuelve los tres hilos que más CPU gastaron. Es el texto del servidor tal cual, en inglés; con el nodo quieto sólo trae la cabecera.
La pestaña sólo lee: no cambia ajustes del nodo.
Palabras clave: elasticsearch, opensearch, nodo, jvm, heap, gc, recolección de basura, cpu, disco, watermark, consultas por segundo, indexación, thread pool, rechazos, rejected, 429, hilos calientes, hot threads, plugins
Tareas: lo que corre en el clúster y cómo cancelarlo
Qué enseña el árbol de tareas, cada cuánto se relee, qué tareas se pueden cancelar y qué contesta el servidor al cancelar.
Dónde está: Espacio de Trabajo › Herramientas › Tareas
Aplica a:ElasticsearchOpenSearch
La pestaña lee las tareas del clúster (GET /_tasks?detailed=true&group_by=parents) al abrirla y, mientras está delante, cada 3 s; al cambiar de pestaña deja de leer. Mientras se lee sola, Actividad lo enseña como «Tareas de búsqueda, cada 3 s». Actualizar las lee en el momento.
El árbol
Cada tarea madre lleva debajo sus hijas, ordenadas por lo que llevan corriendo. Cada fila dice la acción, la descripción, el nodo por su nombre (si no se sabe, su identificador) y cuánto lleva. En un delete by query, un update by query o un reindex dice además cuántos documentos lleva de cuántos.
El filtro
Casa con la acción o la descripción, sin distinguir mayúsculas, y una madre se queda si casa alguna de sus hijas.
Lo que no se ofrece para cancelar
- Pedir la lista también es una tarea del servidor: sale marcada «esta lista».
- Las persistentes («persistente, del clúster») las marca cancelables el servidor, pero son del propio clúster y no se ofrecen.
- Las que el servidor no marca cancelables, las que ya tienen la cancelación pedida y, en una conexión de solo lectura, todas.
Cancelar tarea
Antes se confirma: la alerta nombra la acción, la descripción y el nodo, y Dejarla correr la deja seguir. Cancelar pide al servidor que la detenga en cuanto pueda; lo que ya hizo no se deshace. El servidor contesta siempre con éxito y la pantalla dice lo que pasó: que la marcó cancelada, que la tarea ya había terminado o que su nodo ya no está en el clúster.
Qué enseña la pestaña de un repositorio y de sus instantáneas, cómo se crea una, cómo se sigue hasta que acaba y cómo se restaura.
Dónde está: Espacio de Trabajo › Herramientas › Instantáneas
Aplica a:ElasticsearchOpenSearch
La pestaña lee los repositorios de instantáneas del servidor (GET /_snapshot) y, del elegido, sus instantáneas (GET /_snapshot/<repositorio>/_all).
Repositorio
Si el servidor tiene más de uno, se elige en la barra. Debajo van su tipo y sus ajustes; un ajuste que nombra una credencial sale tapado (••••). Sin ningún repositorio, la pantalla lo dice: un repositorio se registra en el servidor (PUT /_snapshot/<nombre>), y uno de tipo fs necesita que su carpeta esté en path.repo de cada nodo, en la configuración del servidor. Calíope no registra repositorios.
Las instantáneas
Van de la más reciente a la más antigua. Cada una dice su estado con glifo y palabras («Completa», «En curso», «Parcial: algún shard falló», «Fallida»), cuándo empezó, cuánto duró, sus shards y sus índices, y el fallo de cada shard que falló.
Crear instantánea
Abre una hoja con el nombre y los índices. El nombre propuesto lleva la fecha y la hora (snapshot-AAAA.MM.DD-HHMMSS); va en minúsculas y sin espacios, o el servidor lo rechaza y la hoja enseña su motivo. Los índices van separados por comas y admiten comodines; vacío son todos los del clúster. Un índice que no existe se salta, y el estado global (plantillas y ajustes del clúster) no entra. Crear pasa por el guarda de escritura de la conexión: en una de solo lectura el botón no aparece.
La hoja se cierra en cuanto el servidor acepta la petición, y Actividad sigue la instantánea como «Instantánea de búsqueda», con los shards hechos como avance. No tiene «Detener»: parar sería dejarla a medias. El final lo confirma la lista de instantáneas, porque OpenSearch tarda un instante en darla por terminada. Si a los diez minutos sigue en curso, la pantalla lo dice y Actualizar enseña después cómo acabó.
Restaurar…
Lo tiene cada instantánea completa, salvo en una conexión de solo lectura. Su hoja elige los índices (todos, al empezar), el patrón del nombre y el nombre nuevo, y la casilla Incluir el estado global. El servidor nunca restaura sobre un índice abierto con el mismo nombre: lo rechaza con snapshot_restore_exception, y la hoja enseña su texto. Por eso la hoja propone otro nombre: (.+) → restored_$1 trae demo_logs como restored_demo_logs, al lado del que tienes; con el patrón vacío cada uno vuelve con su nombre, y eso sólo vale si ese índice está cerrado o ya no existe. El estado global (plantillas, ajustes persistentes) empieza apagado: restaurarlo sustituye el de ahora. Restaurar pasa por el guarda de escritura de la conexión, espera a que el servidor termine (POST /_snapshot/<repositorio>/<nombre>/_restore?wait_for_completion=true) y dice después qué índices volvieron.
Qué enseña cada sección, qué se puede crear, cambiar y borrar, por qué una clave de API sólo se ve una vez y qué cambia en OpenSearch.
Dónde está: Espacio de Trabajo › Herramientas › Usuarios y roles
Aplica a:ElasticsearchOpenSearch
La pestaña lee los usuarios y los roles del servidor al abrirla; Actualizar los vuelve a leer. Las secciones se eligen en la barra.
Usuarios
Cada usuario lleva sus roles y, si toca, una marca: «tú» es el usuario con el que estás conectado, «reservado» lo creó el servidor y no se toca, y «desactivado» no puede entrar. Ni el propio ni uno reservado se ofrecen para borrar ni para cambiar roles: quitártelos a ti te dejaría fuera.
Nuevo usuario abre una hoja con el nombre, la contraseña y los roles. Si ya hay un usuario con ese nombre, la hoja lo dice y no lo sustituye. La contraseña viaja al servidor y no se guarda en Calíope, y el registro de comandos la tapa. Elasticsearch exige al menos seis caracteres; OpenSearch rechaza la débil o la que se parece al nombre, y la hoja enseña su motivo.
Cambiar roles… cambia sólo los roles: la contraseña y el resto del usuario quedan como estaban. Borrar usuario pide confirmación nombrando el usuario y el servidor, y no se deshace. Todo lo que escribe pasa por el guarda de escritura de la conexión: en una de solo lectura los botones no aparecen.
Roles
Los roles con sus privilegios de clúster y de índices, para leer. Los reservados van marcados.
Elasticsearch
Claves de API
Las claves de API vigentes que son tuyas; las invalidadas y las caducadas no se listan. Nueva clave pide un nombre y una Caducidad: sin caducidad, un día, una semana, 30 días, 90 días o un año. La clave se enseña una sola vez, con Copiar: el servidor no la vuelve a dar y Calíope no la guarda. Va en la cabecera Authorization: ApiKey <clave>. Invalidar clave la deja sin efecto en cuanto el servidor lo confirma, y no se deshace.
OpenSearch
En OpenSearch
Los usuarios y los roles son los del plugin de seguridad (_plugins/_security/api/…). Los roles de un usuario salen de los mappings de rol (rolesmapping) que lo nombran a él o a uno de sus roles de backend (backend_roles). Los que tiene por un rol de backend salen en la lista, pero en la hoja de Cambiar roles… van marcados y apagados: se quitan en el servidor, no aquí. Cambiar roles reescribe el mapping de cada rol tocando sólo su lista de usuarios, y borrar un usuario lo saca también de los mappings, porque el servidor no lo hace solo. No hay sección de claves de API: los API tokens de OpenSearch 3 vienen apagados y son de administración, no del usuario.
Sin seguridad
Si el servidor no tiene la seguridad activada (en OpenSearch, sin el plugin de seguridad), la pestaña lo dice y no enseña listas ni botones: cualquiera que llegue al servidor entra sin credencial.
Palabras clave: elasticsearch, opensearch, usuarios, roles, seguridad, security, _security, claves de api, api key, apikey, contraseña, reservado, rolesmapping, internalusers, backend_roles, plugin de seguridad
Qué es un reporte de búsqueda: el SQL del producto con parámetros :nombre, o un cuerpo de Query DSL sobre unos índices, leído página a página hasta el techo.
Dónde está: Espacio de Trabajo › Herramientas › Reportes
Aplica a:ElasticsearchOpenSearch
En una sesión de Elasticsearch u OpenSearch, Nuevo reporte crea un reporte de búsqueda, que nace en SQL con SELECT * FROM demo_productos LIMIT 100. Forma lo cambia entre SQL y Query DSL; cambiar de forma empieza de cero, porque un SELECT no es un cuerpo JSON.
SQL
El SQL del producto: una sola sentencia que lee. Un INSERT, un DELETE o dos sentencias se rechazan antes de mandar nada. Un parámetro se escribe :nombre y se declara con Declarar parámetros; viaja como valor, nunca dentro del texto, y una lista se expande a un marcador por valor (IN (:ids)). Un nombre con símbolos se cita como lo cita el producto: con comillas dobles en Elasticsearch ("@timestamp") y con acento grave en OpenSearch, donde las comillas dobles son una cadena. OpenSearch no admite un parámetro vacío —el reporte lo rechaza antes de mandar nada— y una fecha con hora le llega como texto en UTC.
Query DSL
Un cuerpo de búsqueda JSON y, en Índices, los índices separados por comas (vacío: todos). No lleva parámetros: el cuerpo viaja tal como está escrito, y size, from, search_after, pit y scroll se ignoran, porque el recorrido lo pone el reporte.
Lo que se lee
Cada vez que pulsas Ejecutar, Calíope lee todas las páginas, de 1000 en 1000, hasta el techo de filas del reporte, y si se recortó lo dice. Detener lo para entre una página y la siguiente. El SQL sigue el cursor del servidor y lo cierra al acabar. La Query DSL sigue search_after si el cuerpo ordena; si no ordena, Calíope ordena por _doc y no pasa de 10 000 documentos: más allá pide un sort. Las columnas del SQL son las de la respuesta, con su tipo; las de la Query DSL son _index, _id y los campos del documento aplanados (cliente.nombre; una lista es una celda), con el tipo del mapping.
Lo demás
Lo que lee un reporte no queda en el Registro de comandos: es una lectura de la herramienta, no una búsqueda hecha en Consulta. Exportar y Historial funcionan como en cualquier reporte. Un reporte de búsqueda sólo se ejecuta en una sesión de Elasticsearch u OpenSearch, no admite un guion de varias sentencias, y se programa con Programar como cualquier otro: el programador abre su propia conexión desde el perfil.