Esta página describe Calíope 1.7, la versión que estoy construyendo ahora mismo. La 1.6 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.
Una consulta guardada con su salida definida y sus parámetros declarados.
Dónde está: Espacio de Trabajo › Herramientas › Reportes
Un reporte no es un fragmento. Un fragmento es texto que se pega en el editor; un reporte es un artefacto que se ejecuta: guarda las columnas que espera, cómo se presentan, qué parámetros pide y de qué fuente sale.
Por eso ejecutarlo dos veces da lo mismo, y por eso cuando lo que llega no coincide con lo declarado se te dice arriba en vez de dibujarse una tabla distinta en silencio.
Vale con bases relacionales, con MongoDB y con Redis.
Un reporte puede ser varias sentencias, siempre que la última sea el SELECT que produce la tabla.
Dónde está: Espacio de Trabajo › Herramientas › Reportes
No todo reporte sale de una sola consulta. Puedes fijar una variable de sesión, construir una tabla temporal en varias pasadas, indexarla y leerla al final. El guion entero corre sobre una sola conexión, así que la tabla temporal creada en la primera sentencia sigue existiendo en la última.
Lo que puedes usar antes del SELECT final: SET y USE para la sesión, CREATE TEMPORARY TABLE, y escribir en tablas que haya creado este mismo reporte — INSERT, UPDATE, DELETE, índices, ALTER. Las lecturas intermedias también valen.
Lo que no: escribir en una tabla real, CREATE TABLE sin TEMPORARY, SET GLOBAL, PREPARE, EXECUTE y CALL. Es una lista cerrada, y lo que queda fuera se rechaza, diciendo el número de sentencia, antes de ejecutar nada.
SELECT … INTO una tabla real también queda fuera: en varios motores crea esa tabla.
SQL Server
En SQL Server una tabla temporal es la que empieza por # (CREATE TABLE #t, SELECT … INTO #t, DROP TABLE #t), sin TEMPORARY. Créala sin parámetros y llénala después con un INSERT: los valores atados viajan por sp_executesql, y una temporal creada dentro desaparece al terminar esa sentencia. Calíope lo dice antes de ejecutar nada.
ClickHouse
En ClickHouse la tabla temporal se crea con CREATE TEMPORARY TABLE y vive en la memoria del servidor. Por HTTP cada sentencia es una petición independiente, así que Calíope abre para cada ejecución del reporte una sesión del servidor propia, y al acabar retira la temporal. La temporal de la primera sentencia existe en la última y nadie más la ve. La cuenta necesita el permiso CREATE TEMPORARY TABLE; con una de sólo lectura el reporte falla en la primera sentencia, y el mensaje lo dice.
Oracle
En Oracle cada sentencia del reporte se confirma al acabar, y eso decide cómo se escribe la temporal. Una GLOBAL TEMPORARY TABLE necesita ON COMMIT PRESERVE ROWS: con el ON COMMIT DELETE ROWS por omisión llega vacía al SELECT final. Una privada (CREATE PRIVATE TEMPORARY TABLE ora$ptt_…) necesita ON COMMIT PRESERVE DEFINITION: con la de por omisión desaparece en la segunda sentencia. Al acabar, Calíope vacía y borra la temporal en la misma conexión, también si el reporte falla, así que la global no se queda en tu esquema. En Oracle no hay SET ni USE: el reporte corre en el esquema de la cuenta, y una tabla de otro esquema se escribe con él delante (demo.pedidos).
El motivo es una promesa: un reporte nunca toca tus datos. Es lo que hace que se pueda programar uno a las tres de la mañana.
En una conexión con una etiqueta de entorno de solo lectura, un reporte puede crear sus tablas temporales; nada más.
Palabras clave: lote, tabla temporal, varias sentencias, guion, preparación
Se declaran con tipo y valor por omisión, y viajan aparte de la consulta.
Dónde está: Reportes › Declarar parámetros
Se declaran en «Declarar parámetros», en la barra de la herramienta: cada uno con su nombre, su tipo, si es obligatorio y con qué valor llega puesto. En el texto se escriben como «:nombre» en SQL y como "$$nombre" en el JSON de MongoDB.
Escribirlos en el texto no los declara. Por ahí no: un marcador sin declarar hace que el reporte falle al validar. Lo que sí hace la hoja es ofrecerte los que la consulta ya usa, para darlos de alta con el nombre exacto.
Un parámetro es un valor, no un trozo de consulta. Nunca se pega dentro del texto: viaja atado por separado, así que nada de lo que escribas ahí puede romper la consulta ni cambiar lo que hace.
La contrapartida es que no se puede parametrizar el nombre de una tabla, ni una lista IN(…) de longitud variable con un solo marcador. Para la lista está el tipo «lista», que expande tantos marcadores como valores; para el nombre de tabla no hay soporte, y es a propósito.
Palabras clave: parámetro, binding, inyección, lista
Qué columnas se ven, en qué orden, con qué título y con qué formato.
Dónde está: Reportes › Salida
Es lo que convierte una consulta guardada en un reporte. Puedes ocultar columnas, reordenarlas, ponerles tu propio título, elegir el formato (miles, dos decimales, porcentaje, moneda, fecha, bytes) y su alineación.
Al pie puedes añadir agregados por columna: suma, promedio, mínimo, máximo y conteo. Los nulos no cuentan: un promedio se divide entre los valores presentes, no entre las filas.
El orden que eliges aquí es de presentación y no reescribe tu consulta.
CSV, TSV, JSON, Markdown, HTML, XML, texto, Excel y PDF paginado.
Dónde está: Reportes › Exportar
Se exporta lo que declara la salida: las columnas visibles, en su orden, con sus títulos y sus formatos. Un PDF que dice «Importe» y un CSV que dijera «total_eur» no serían el mismo reporte.
Una columna sin formato declarado se exporta a CSV, TSV, JSON, XML y Excel con su valor exacto —todos los decimales, sin separador de miles, y la fecha como 2020-01-01—, porque la leerá otro programa; en el PDF, el HTML, el Markdown y el Texto sale como se ve en pantalla. Un formato que declares se exporta siempre.
El PDF va paginado, con la cabecera repetida en cada página y su numeración; los agregados y los avisos van en la última.
Todo sale por el panel de guardado del sistema: Calíope no escribe en ninguna carpeta que no hayas elegido tú.
Diario, semanal, laborables, mensual o cada N horas — con un límite que conviene saber.
Dónde está: Reportes › Programar
Lo programado sólo corre con Calíope abierta. No hay un servicio en segundo plano, ni un demonio, ni un agente de lanzamiento: en el Mac corre con la app abierta, y en el iPad, sólo en primer plano — a un reporte no se le concede ninguna ventana de fondo.
Si la app está cerrada a la hora prevista, la ejecución se anota en el historial como omitida, con su motivo, y se reintenta en la siguiente. No se disparan de golpe todas las que se hayan perdido.
Sin nadie delante se usan los valores por omisión de cada parámetro. Un parámetro obligatorio sin valor no se inventa: la ejecución se anota como omitida.
Sólo se programan los reportes de un servidor relacional: en una sesión de MongoDB o de Redis el botón no está.
Apple Vision Pro: como en el iPad, sólo en primer plano.
Qué corrió, cuándo, con qué valores y en qué equipo.
Dónde está: Reportes › Historial
Cada ejecución deja su fila: pase lo que pase, incluidas las canceladas y las omitidas. Se guarda con qué parámetros corrió, cuántas filas devolvió, cuánto tardó, qué equipo la ejecutó y —cuando hay dos direcciones posibles— por cuál se conectó.
Los reportes y los respaldos tienen el mismo historial y dos ámbitos estancos: desde Reportes no se ve ni una fila de respaldo, y al revés igual.
Las filas de más de 180 días se borran solas. El historial se queda en este aparato: no viaja a iCloud.
Si el historial mismo no se pudo escribir —el disco lleno, por ejemplo—, el pie te lo dice: entonces faltan filas, y lo que ves no es todo lo que corrió.
En la hoja de salida se enciende un gráfico de barras, líneas o sectores: una columna da los rótulos y las columnas numéricas, los valores.
Dónde está: Espacio de Trabajo › Herramientas › Reportes
En la hoja de salida de un reporte, la sección Gráfico enciende un gráfico con «Dibujar un gráfico». Elige su Tipo —barras, líneas o sectores—, la Columna de etiqueta que da los rótulos, y una o más columnas numéricas para los valores. Si ninguna columna del resultado es numérica, la hoja lo dice.
El gráfico se dibuja encima de la tabla. Si tiene que dejar series fuera, lo avisa, y VoiceOver lo lee como un resumen.