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.
Abre y consulta bases DuckDB de archivo local, sin servidor.
Dónde está: Espacio de Trabajo › Herramientas › Editor DuckDB
El Editor DuckDB es una herramienta autónoma para archivos .duckdb locales, con el mismo diseño que el Editor SQLite: Estructura, Datos, Ejecutar SQL, Diagrama ER —sólo con un archivo abierto—, Query Builder y Ajustes, y funciona sin conexión a ningún servidor.
También abre una base en memoria —sin archivo— desde Consultar archivo de datos…, para trabajar sobre un CSV, JSON o Parquet sin crear nada en disco.
Lo que Calíope no hace con DuckDB. No descarga extensiones —INSTALL, LOAD, UPDATE EXTENSIONS y los repositorios de extensiones (CREATE y DROP EXTENSION REPOSITORY) se rechazan antes de tocar el motor—: sólo están las cuatro que trae la app. Por lo mismo, no hay secretos de acceso remoto (CREATE SECRET) ni se puede hacer ATTACH de un archivo SQLite o de Postgres, que necesitan una extensión que no se enlaza. La configuración del motor queda cerrada al abrir: un SET de un ajuste del motor se rechaza —también threads y memory_limit, que sólo se cambian desde Ajustes; SET VARIABLE no, porque una variable no es configuración— y, como todo error al ejecutar, cancela los cambios sin guardar. Los dos SET que proponen los mensajes de DuckDB 2.0 son la excepción: Calíope los para antes y no cancelan nada. Lo que sí funciona es mover la base entera: Base entera y Guardar como… corren fuera de la transacción pendiente.
Palabras clave: duckdb, archivo, local, base de datos, analítica
Abre un archivo .duckdb existente o crea uno nuevo.
Dónde está: Espacio de Trabajo › Herramientas › Editor DuckDB
Usa Abrir… para elegir un archivo .duckdb existente, o Nueva base… para crear uno vacío. Los archivos recientes aparecen en la pantalla inicial. Una insignia Solo lectura aparece cuando un archivo no se puede modificar.
Si el archivo está fuera de la carpeta de Calíope, la primera vez se pide acceso a su carpeta: DuckDB necesita escribir un archivo .wal junto al .duckdb, y el sandbox de la app sólo lo permite dentro de una carpeta que el usuario haya elegido. Se recuerda para la próxima vez que se abra un archivo de la misma carpeta. ¿No tienes ningún archivo DuckDB a mano? En el estado vacío, Descargar base de ejemplo abre la página del sitio donde está la muestra pública —una tienda con 50 000 pedidos, hecha con Calíope—. La app no descarga nada: abre la página y decides tú.
También se abre desde fuera de Calíope. En el Mac, desde el Finder con Abrir con › Calíope, o con doble clic si Calíope es la app por omisión de ese tipo de archivo. En el iPad y el iPhone, compartiéndolo desde la app Archivos y eligiendo Calíope. Un archivo Parquet abierto así también llega aquí, en una base en memoria (mira Consultar archivo de datos…). Si la sesión que tienes delante no ofrece esta herramienta, el archivo se abre en Abrir sin conexión.
El formato del archivo. Una base nueva —la de Nueva base… y la que deja Guardar como… de una base en memoria— se crea en el formato de DuckDB 2.0. Ese formato lo abren DuckDB 2.0 y las versiones posteriores; no lo abren Calíope 1.7 ni ninguna herramienta con DuckDB 1.5 o anterior. Un archivo que ya existía conserva su formato: Calíope lo abre y lo modifica sin convertirlo, así que lo sigue abriendo la herramienta que lo creó. El formato no se elige al crear, y un archivo existente no se convierte. Para saber en qué formato está el archivo abierto, mira Estructura: bajo la barra, Formato del archivo dice DuckDB 2.0 o posterior en una base nueva y, por ejemplo, DuckDB 1.0 o posterior en una creada con DuckDB 1.5.
La sección Estructura muestra el árbol del esquema con las columnas y el DDL de cada objeto. DuckDB no tiene triggers, así que el árbol enseña tablas, vistas, índices, secuencias, tipos, macros y macros de tabla. Secuencias, tipos y macros se crean desde Ejecutar SQL —CREATE SEQUENCE, CREATE TYPE, CREATE MACRO, CREATE MACRO … AS TABLE—; desde aquí se ven y se borran. Si el archivo tiene más de un esquema, cada grupo lleva delante el nombre del suyo, y el comentario de un objeto (COMMENT ON) se enseña al pasar por encima. Usa Nuevo para crear tablas, índices o vistas, Añadir columna o Renombrar tabla sobre la tabla seleccionada, y Eliminar para borrar un objeto. Bajo la barra, Formato del archivo dice qué versiones de DuckDB abren el archivo: una base nueva pide DuckDB 2.0 o posterior, y una que ya existía conserva su formato.
Las vistas creadas por Consultar archivo de datos… llevan un icono distinto —un clip— y su tooltip enseña la ruta del archivo de origen.
Adjuntar base… abre otra base DuckDB junto a la que ya tienes y su contenido aparece en el árbol con el nombre de la base delante; se consulta escribiendo base.esquema.tabla. Va siempre en sólo lectura —escribir en ella pediría crear su archivo .wal al lado, que el sandbox no permite—, y Separar la quita. Un archivo SQLite no se puede adjuntar aquí: son dos motores distintos, y para eso está el Editor SQLite.
iPad y Apple Vision Pro: el panel de detalle también enseña el archivo de origen.
La sección Datos muestra las filas de una tabla por páginas, con el contador y las flechas a la derecha de la barra. Cuántas filas trae una página lo eliges en Ajustes › Editor de texto › Resultados › Filas por página —Ajustes, en el iPad—. Ordena pulsando la cabecera de una columna, acota columna a columna con Filtros, o escribe en el campo de búsqueda para mirar en todas a la vez.
Editar una celda
macOS: doble clic sobre ella. iPad: un solo toque. Intro confirma; Esc cancela.
Añadir y eliminar filas
Añadir fila abre un formulario con un renglón por columna. A diferencia de SQLite, DuckDB no autoasigna la clave primaria entera: cada columna obligatoria necesita su valor, incluida la clave. Para eliminar, selecciona la fila por su número y usa Eliminar fila.
Nada de esto toca el archivo hasta que pulsas Guardar cambios: lo editado queda en una transacción pendiente que Revertir cambios deshace entera.
Resaltado y autocompletado, con un tope de filas y un botón Detener.
La sección Ejecutar SQL usa el mismo campo de texto y la misma rejilla de resultados que el Editor SQL de servidor, sobre el archivo abierto y sin ninguna conexión de por medio.
El texto va resaltado. Pulsa Ejecutar, o ⌘↩, para correr el script entero; se dibuja el resultado de la última sentencia que devolvió filas. Un SELECT grande no se trae entero: se corta en Ajustes › Editor de texto › Resultados › Techo de filas —el mismo tope del Editor SQL—, y la rejilla dice cuántas de cuántas trajo.
Mientras una consulta corre, un botón Detener la interrumpe de verdad: el motor la corta a mitad de camino, no espera a que termine.
Si una sentencia falla, el script para ahí y el error sale donde irían los resultados. Un error de sintaxis o un nombre que no existe deja lo pendiente como estaba; uno que ocurre al ejecutar cancela los cambios sin guardar, y Calíope lo dice (tema Guardar y revertir cambios). Cuando hay un tema que explica el error —el SQL que DuckDB 2.0 ya no acepta está en Qué cambia con DuckDB 2.0—, Ver solución lo abre desde el propio error.
INSTALL y LOAD se rechazan: Calíope no descarga extensiones de DuckDB, así que una consulta que las necesite no se ejecuta, con el motivo explicado en el mensaje.
Lo que escriba en el archivo queda pendiente, igual que una edición en Datos: no toca el archivo hasta Guardar cambios.
Visual EXPLAIN
El botón Visual EXPLAIN, junto a Ejecutar, dibuja el plan que seguiría DuckDB —EXPLAIN (FORMAT JSON)— sin ejecutar nada, en la misma pestaña que el Editor SQL, con las filas que estima. Analiza lo seleccionado y, sin selección, la última sentencia del texto. Una tabla puede salir recorrida entera aunque tenga índice: DuckDB guarda mínimos y máximos por bloque y a menudo prefiere recorrer descartando bloques.
Fichas de funciones
Al pasar el puntero sobre una función en macOS, o al poner el cursor de texto en ella en el iPad, sale su ficha, la de DuckDB: sintaxis, retorno, parámetros y un ejemplo. Lo explica el tema Ayuda contextual de funciones SQL.
Apple Vision Pro: igual que en el iPad, y la ficha de la función cuelga encima de la cabecera, debajo de la ventana.
El SQL de DuckDB 1.5 que la 2.0 rechaza o contesta distinto, con su forma nueva.
DuckDB 2.0 contesta distinto a un poco de SQL que con DuckDB 1.5 funcionaba, y Calíope lleva DuckDB 2.0 desde la versión 1.8. Un script de antes puede dar ahora un error o, en un caso, otro resultado sin avisar. Cuando una consulta falla por uno de estos cambios, Ver solución, junto al error, abre este tema.
El arreglo es siempre reescribir la consulta. Los mensajes del motor proponen un SET para volver a lo de antes; en Calíope no sirve: la configuración de DuckDB va cerrada mientras hay un archivo abierto (tema Ajustes y mantenimiento). Calíope para ese SET antes de que llegue al motor y lo dice: no se ejecuta, y los cambios sin guardar siguen ahí.
Lambdas: lambda x: en vez de x ->
Una función lambda escrita con flecha ya no se acepta.
Antes:
SELECT list_transform([1, 2, 3], x -> x + 1);
Ahora:
SELECT list_transform([1, 2, 3], lambda x: x + 1);
Con la forma de antes, el motor contesta:
Binder Error: Deprecated lambda arrow (->) detected. Please transition to the new lambda syntax, i.e.., lambda x, i: x + i, before DuckDB's next release.
// y % entre cero dan error
La división entera //, el resto % y las funciones divide y mod devolvían NULL cuando el divisor era cero. Ahora la consulta falla y, como es un error al ejecutar, cancela los cambios sin guardar. / no cambia: sigue dando inf.
Antes (devolvía NULL):
SELECT 7 // 0;
Ahora, para seguir recibiendo NULL:
SELECT TRY(7 // 0);
SELECT 7 // NULLIF(0, 0);
El motor contesta:
Invalid Input Error: Division by zero in expression (7 // 0). Use TRY(...) to return NULL for this expression, or SET error_on_division_by_zero=false to return NULL for all divisions by zero.
~ casa una parte del texto, no el texto entero
Este cambio no da error: da otro resultado. texto ~ patrón era verdadero sólo si la expresión regular casaba con el texto entero; ahora basta con que case una parte, como en PostgreSQL. !~ cambia igual.
En CREATE TABLE … AS, una columna que sale de un NULL a secas quedaba de tipo INTEGER. Ahora queda de tipo "NULL" y no admite ningún otro valor. Las tablas que ya estaban creadas conservan su tipo.
Antes:
CREATE TABLE notas AS SELECT 1 AS id, NULL AS nota;
INSERT INTO notas VALUES (2, 5);
Ahora, con el tipo escrito:
CREATE TABLE notas AS SELECT 1 AS id, NULL::INTEGER AS nota;
INSERT INTO notas VALUES (2, 5);
Con la forma de antes, el INSERT falla:
Conversion Error: Unimplemented type for cast (INTEGER -> "NULL")
Una tabla que ya quedó así se arregla cambiando el tipo de la columna:
ALTER TABLE notas ALTER COLUMN nota TYPE INTEGER;
Qué errores cancelan los cambios sin guardar
Por sí solo, DuckDB 2.0 cancela la transacción abierta con cualquier error, también uno de sintaxis, y la sentencia siguiente contesta:
TransactionContext Error: Current transaction is aborted (please ROLLBACK)
Calíope no usa ese valor por omisión: abre cada archivo con la regla de DuckDB 1.5. Un error de sintaxis, o el nombre de una tabla, una columna o una función que no existe, no toca tus cambios sin guardar. Los errores que ocurren al ejecutar sí los cancelan, como antes —una restricción que no se cumple, un valor que no se puede convertir—, y ahora también la división entre cero, que antes no era un error. Calíope lo dice junto al error y hace el ROLLBACK por ti. Lo cuenta el tema Guardar y revertir cambios.
También cambia
EXPLAIN en texto se dibuja de otra forma: cajas de esquinas redondas y los operadores con su nombre en palabras. Visual EXPLAIN no cambia.
ALTER TABLE … ADD COLUMN admite ahora restricciones, como NOT NULL con un DEFAULT; DuckDB 1.5 las rechazaba.
Un archivo nuevo se crea en el formato de DuckDB 2.0, que las versiones anteriores no abren. Lo cuenta el tema Abrir o crear una base.
Las tablas del archivo y sus claves foráneas, dibujadas sin servidor.
La sección Diagrama ER dibuja las tablas del archivo abierto con sus columnas y las claves foráneas que declaran, sin conexión a ningún servidor. Sólo aparece con un archivo abierto: una base en memoria no la ofrece, porque no hay archivo donde guardar la disposición.
El selector de arriba lista la base del archivo —que se llama como el archivo— y las que adjuntaste; si una base tiene tablas en más de un esquema, cada esquema es una entrada (tienda.main, tienda.ventas). + BD trae una segunda al lado.
Funciona como el Diagrama ER de una conexión: zoom, Disposición automática, exportar como PNG o PDF, imprimir en el Mac y el CREATE TABLE de una tabla desde su menú. Después de un cambio de estructura, un ATTACH o un DETACH, el diagrama vuelve a leer solo.
Sólo lee. No ofrece Nueva relación FK… ni el arrastre con ⌃: DuckDB no añade una clave foránea a una tabla que ya existe (rechaza ALTER TABLE … ADD CONSTRAINT … FOREIGN KEY). Para relacionar dos tablas, la foránea se declara al crear la tabla (REFERENCES en Ejecutar SQL).
Guardar layout guarda dónde dejaste cada tabla por archivo y sólo en este aparato: no viaja por iCloud ni entra en el respaldo de ajustes, porque la ruta del archivo es distinta en cada aparato. Se conservan las de los archivos que usaste más recientemente, y las más viejas se borran solas. Si el sistema cambia la ruta del archivo, su disposición se pierde, igual que su entrada en los recientes.
Si el archivo no se puede leer, un aviso encima del diagrama dice por qué, con el texto del motor.
En Apple Vision Pro, Abrir en el espacio despliega en la habitación el diagrama del archivo, también sólo para leer; se cierra al cerrar el archivo.
Arma un SELECT con las tablas de la base y llévalo a Ejecutar SQL.
La sección Query Builder es el Query Builder de una conexión, sobre la base abierta y sin servidor; también funciona con una base en memoria. La lista de la izquierda tiene las tablas de la base, con un filtro por nombre; pulsa una, su +, o arrástrala al lienzo. El JOIN sale de las claves foráneas que declara la base, y donde no hay ninguna dices en Relaciones qué columnas se relacionan. Las condiciones, el tipo de JOIN, los alias, Limpiar canvas y copiar el SQL funcionan igual que con una conexión.
Con bases adjuntas, el menú de arriba elige cuál; la del archivo se llama como el archivo. En cuanto hay más de una base o de un esquema, cada tabla se escribe con su nombre entero ("tienda"."main"."clientes"), porque dos pueden llamarse igual. Si un DETACH se lleva la base elegida, el lienzo pasa a la principal.
Insertar en el editor añade la consulta al final de lo que tengas escrito en Ejecutar SQL, tras una línea en blanco, y cambia a esa sección. Nunca sustituye lo que había.
El lienzo sigue ahí al cambiar de sección o de pestaña, y se descarta al cerrar la base. En el iPhone, y en el iPad con la pantalla partida, la lista ocupa la pantalla y añadir una tabla te lleva al lienzo.
Los cambios quedan pendientes hasta que los guardas.
Las ediciones se agrupan en una transacción pendiente, igual que en el Editor SQLite. Un punto ámbar indica cambios sin guardar. Usa Guardar cambios para confirmarlos o Revertir cambios para descartarlos. Cerrar el archivo, o abrir o crear otro, con cambios pendientes pregunta antes si guardarlos o descartarlos.
Si una sentencia falla
Depende de qué falla. Un error de sintaxis, o el nombre de una tabla, una columna o una función que no existe, no toca lo pendiente: corriges la consulta y sigues. Tampoco Visual EXPLAIN sobre una consulta mal escrita.
Un error que ocurre al ejecutar hace que DuckDB cancele la transacción entera, y con ella todos los cambios sin guardar, no sólo lo que intentaba la sentencia que falló: una celda o una fila nueva que viola una restricción, un valor que no se puede convertir, una división entera entre cero, un SET de un ajuste del motor —la configuración va cerrada; los dos que proponen los mensajes del motor los para Calíope antes y no cancelan nada— o una consulta que paras con Detener. Calíope lo dice junto al error, el punto ámbar desaparece y la rejilla vuelve a enseñar lo que hay guardado. No hay nada que deshacer a mano: lo siguiente que hagas va en una transacción nueva. Antes de probar consultas, guarda lo que no quieras perder.
Con un script pasa lo mismo: si falla al ejecutar, lo que sus sentencias anteriores escribieron se va con la transacción; si falla por la sintaxis o por un nombre, lo que escribieron queda pendiente.
DuckDB 2.0, por sí solo, cancelaría la transacción con cualquier error; Calíope abre cada archivo con la regla de DuckDB 1.5, que es la de arriba. Lo cuenta el tema Qué cambia con DuckDB 2.0.
DuckDB escribe primero en un archivo .wal junto al .duckdb; el volcado al archivo principal (CHECKPOINT) es asíncrono, así que el .wal puede tardar unos segundos en desaparecer después de guardar y cerrar —el dato ya está a salvo, aunque el archivo auxiliar siga ahí un momento—.
Dale a DuckDB núcleos y memoria, y haz checkpoint o compacta el archivo.
La sección Ajustes es al Editor DuckDB lo que la sección Pragmas al Editor SQLite. En Editables, Núcleos (threads) y Límite de memoria (MB) se aplican con Aplicar: la configuración de DuckDB queda cerrada mientras un archivo está abierto —un SET threads o SET memory_limit no la cambia: el motor lo rechaza y, como todo error al ejecutar, eso cancela los cambios sin guardar—, así que Calíope guarda el valor y vuelve a abrir el archivo con él. Son de este aparato —un Mac y un iPad no tienen los mismos núcleos ni la misma memoria— y no viajan con el resto de tus preferencias. Con una base en memoria no hay archivo que reabrir, y no se aplican.
Mantenimiento ejecuta Checkpoint —que vuelca el .wal en el archivo—, Forzar checkpoint, Vacuum y Analizar, y la respuesta del motor aparece debajo de los botones. Como los ajustes, los botones se apagan mientras haya cambios sin guardar: guarda o revierte antes. El resto de ajustes del motor se listan en Solo lectura con su valor actual.
Desde Importar / Exportar puedes importar un archivo CSV a una tabla nueva de columnas de texto, exportar una tabla a CSV o JSON, o exportar toda la base a un volcado SQL (esquema y datos).
Esto es distinto de Consultar archivo de datos…: aquí el CSV se copia dentro del archivo .duckdb como una tabla nueva; allí el archivo se queda donde está y sólo se consulta a través de una vista.
Con DuckDB, el CSV lo lee el propio motor (COPY … AUTO_DETECT), así que cada columna entra con su tipo y no como texto. Y Base entera vuelca toda la base a una carpeta que elijas —en CSV o en Parquet, con el esquema al lado— o lee en la base abierta lo que dejó otra exportación. Si la base está en memoria, Guardar como… la escribe entera en un archivo .duckdb y sigue trabajando sobre él.
Exportar e importar la base entera piden que no haya cambios sin guardar: Calíope las corre fuera de la transacción pendiente, porque un fallo a medias —una tabla que ya existe, una carpeta sin permiso— la cancelaría con todo lo que tuvieras sin guardar. Guardar como… no lo pide: confirma antes lo pendiente, que con una base en memoria no toca ningún archivo.
Consulta un CSV, JSON o Parquet como si fuera una tabla, sin copiarlo.
El botón Consultar archivo de datos… crea, por cada archivo elegido, una vista sobre él —read_csv_auto, read_json_auto o read_parquet según su extensión—: el archivo se queda donde está y se lee al vuelo cada vez que se consulta la vista, sin copiar sus datos dentro de la base.
El nombre de la vista sale del nombre del archivo, sin su extensión; si dos archivos darían el mismo nombre, al segundo se le añade _2, al tercero _3, y así. En Estructura, estas vistas llevan un icono distinto —un clip— y su tooltip enseña la ruta del archivo de origen.
Si no hay ninguna base abierta, el botón abre primero una base en memoria: no existe ningún archivo .duckdb en disco, así que Guardar como… es el camino para no perder el trabajo al cerrar: la escribe entera en un archivo .duckdb y el editor sigue trabajando sobre él.
Un archivo Parquet abierto desde fuera de Calíope —desde el Finder con Abrir con › Calíope, o compartido desde la app Archivos— también llega aquí: abre una base en memoria con la vista sobre ese archivo, y deja SELECT * FROM read_parquet(…) LIMIT 100; escrito en Ejecutar SQL, sin ejecutarlo.
iPad y Apple Vision Pro: el panel de detalle también enseña el archivo de origen.
Palabras clave: csv, json, parquet, consultar, vista, adjuntar, en memoria
El botón Resumen de Datos escribe SUMMARIZE sobre la tabla abierta y lo ejecuta: una fila por columna con su tipo, rango, valores distintos, nulos y cuartiles.
Dónde está: Espacio de Trabajo › Herramientas › Editor DuckDB
En Datos, con una tabla elegida, el botón Resumen escribe SUMMARIZE <esquema>.<tabla>; en el editor, pasa a Ejecutar SQL y lo ejecuta. El resultado tiene una fila por columna, con su tipo, mínimo, máximo, número aproximado de valores distintos, porcentaje de nulos, media y cuartiles.
Es una función de DuckDB: el Editor SQLite no dibuja el botón.