Ir al contenido

Fuentes de datos ​

DuckLocal convierte los archivos en vistas dentro de una conexión DuckDB en memoria, o dentro de un archivo de base de datos si abriste uno. Otras bases de datos pueden convivir junto a ella. No hay nada que configurar. Consulta el flujo de trabajo de análisis de datos local para ver un recorrido breve desde los archivos hasta el SQL, los gráficos y la exportación.

Formas de abrir datos ​

Todas siguen las mismas reglas de resolución:

  1. Rutas en la línea de comandos: ducklocal ./logs/ billing.parquet
  2. El menú Abrir de la barra de título: Abrir archivos, Abrir carpeta o Introducir una ruta o un patrón, que abre el diálogo Abrir datos para una ruta escrita o elegida en el selector nativo
  3. Soltar archivos o carpetas en cualquier punto de la ventana
  4. En un Mac, los archivos que Finder entrega a DuckLocal; consulta Abrir desde Finder

Para añadir una base de datos junto a la que está abierta en lugar de reemplazarla, usa Abrir → Adjuntar base de datos…; consulta Bases de datos adjuntas.

En macOS también puedes hacer doble clic en archivos Parquet y DuckDB desde Finder para abrirlos, o pulsar la barra espaciadora para previsualizar las primeras filas de archivos Parquet, DuckDB, CSV, TSV y JSON Lines con Quick Look, sin abrir DuckLocal.

Formatos de archivo compatibles ​

Las extensiones se comparan sin distinguir mayúsculas y minúsculas.

ExtensiónCómo se lee
.csv, .tsv, .txtvista read_csv_auto
.parquetvista read_parquet
.json, .ndjson, .jsonlvista read_json_auto
.xlsx, .xls, .xlsb, .odsse importa como una tabla por hoja

El texto comprimido con gzip, como .json.gz y .csv.gz, también cuenta como archivo de datos, tanto en los bloques schema y source como al adjuntar un archivo; logs.json.gz se convierte en una vista llamada logs. Antes de 0.4.0, ducklocal schema intentaba abrir ese tipo de archivo como base de datos; en una copia anterior, léelo en SQL con read_json o read_csv.

Cualquier otra cosa no es un archivo de datos; consulta Archivos de base de datos.

Un libro de trabajo es el único formato que se convierte en tablas en lugar de vistas, e importa todas las hojas: la primera hoja toma el nombre del archivo sin su extensión, y las demás se llaman {stem}_{sheet name}. Una hoja vacía se omite. Los tipos de columna se infieren a partir de las celdas: los enteros pasan a BIGINT, una mezcla de entero y decimal a DOUBLE, las fechas a TIMESTAMP, y cualquier cosa mixta o no reconocida a VARCHAR; las celdas vacías se importan como NULL.

Carpetas y patrones ​

Un directorio se recorre de forma recursiva y cada archivo de datos que contiene se convierte en una vista. Al recorrerlo se aplican dos reglas:

  • Se omiten las entradas ocultas (nombres que empiezan por .) y no se desciende a sus subárboles.
  • No se siguen los enlaces simbólicos. Seguir un enlace que sube por el árbol nunca terminaría, y normalmente el directorio enlazado se recorre donde está realmente.

Los archivos se adjuntan en orden alfabético, así que la misma carpeta siempre produce el mismo espacio de trabajo.

Un patrón puede contener * (cualquier secuencia de caracteres) y ? (exactamente uno). La coincidencia se hace por componente de ruta, contra el sistema de archivos, así que un patrón puede abarcar varios directorios:

bash
ducklocal './data/2026-0*/*.parquet'

No hay carácter de escape. ** no es especial: se comporta como un solo * y no es recursivo. Un patrón que coincide con un directorio lo omite; solo se adjuntan archivos. Aquí también se omiten las entradas ocultas.

Los patrones sin comillas los expande tu shell antes de que DuckLocal los vea. Eso está bien. Pon comillas en un patrón solo cuando quieras que lo expanda DuckLocal; por ejemplo, cuando el shell no encuentra ninguna coincidencia y de otro modo daría error.

Muchos archivos CSV a la vez ​

Cada archivo que adjunta DuckLocal se convierte en su propia vista con su propio esquema detectado, así que dos CSV que no coinciden nunca se estropean entre sí. Los problemas aparecen cuando una sola lectura SQL abarca muchos archivos:

sql
SELECT * FROM read_csv('data/*.csv', union_by_name = true)
  • La detección de tipos puede no coincidir entre archivos. El lector infiere el tipo de una columna a partir de una muestra; una columna que es numérica en todas partes pero contiene una cadena 'NULL' suelta en un archivo hace fallar toda la lectura con un error de conversión, y un cast en la lista del SELECT llega demasiado tarde: la lectura en sí falla. Lee todas las columnas como texto y haz el cast en SQL:

    sql
    SELECT try_cast(amount AS DOUBLE) AS amount
    FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)

    union_by_name = true también tolera archivos cuyos conjuntos de columnas difieren.

  • La cadena 'NULL' no es NULL. Un 'NULL' literal (o 'N/A', 'null') en un CSV es texto normal, así que WHERE amount IS NOT NULL no lo filtra. Usa NULLIF(amount, 'NULL') o WHERE amount <> 'NULL'.

Las dos soluciones se combinan: try_cast(NULLIF(amount, 'NULL') AS DOUBLE).

Archivos de base de datos ​

DuckLocal tiene una sola base de datos principal a la vez: en memoria, o un archivo DuckDB que abriste. Los archivos de datos se convierten en vistas de la base de datos principal. También puedes adjuntar otras bases de datos junto a ella.

Cualquier ruta que exista y no sea un archivo de datos se abre como base de datos principal en lugar de adjuntarse como vista. La extensión da igual: una ruta .db, .duckdb o incluso .md se trata como base de datos, y DuckDB decide si realmente puede abrirla.

Vale la pena conocer algunas consecuencias:

  • Una base de datos nueva solo se crea desde el diálogo Abrir datos. Escribe una ruta que termine en .duckdb y que aún no exista, y DuckLocal crea la base de datos junto con las carpetas padre que falten. En cualquier otro sitio (la línea de comandos, los selectores, arrastrar un archivo, Finder) una ruta inexistente se informa como File not found.
  • Abrir una base de datos reemplaza la principal. Tus archivos registrados y las bases de datos adjuntas se vuelven a adjuntar en la conexión nueva. Las credenciales de S3 no; vuelve a configurar S3.
  • Si el archivo no se puede abrir, DuckLocal te dice por qué (más abajo). Al arrancar, vuelve a un espacio de trabajo en memoria en lugar de fallar al iniciarse. Mientras está en ejecución, el espacio de trabajo que tenías se queda como estaba.
  • Un archivo que ya está adjunto junto a la base de datos principal se separa primero y después se abre como base de datos principal. Si esa apertura falla, la adjunción vuelve. Abrir el archivo que ya es la base de datos principal lo reutiliza.

Adjuntar archivos de datos mientras hay un archivo de base de datos abierto escribe esas vistas dentro de ese archivo de base de datos: persisten ahí, no solo en la sesión.

Cuándo no se abre una base de datos ​

Cuando DuckDB rechaza un archivo, DuckLocal lee por su cuenta los primeros bytes y, si explican el fallo, coloca un motivo y una salida por encima del mensaje propio de DuckDB. El mensaje de DuckDB se queda debajo para el error exacto. La explicación está en el idioma de la interfaz.

Qué es el archivoQué te dice DuckLocal
Un archivo DuckDB escrito por una versión de DuckDB más nueva que la integrada en DuckLocalAmbas versiones, y el SQL que hay que ejecutar en la DuckDB más nueva para copiar el archivo a un formato que DuckLocal lea (más abajo)
Un archivo DuckDB de v0.9 o anteriorEjecuta EXPORT DATABASE 'dir' con la DuckDB que lo escribió y luego IMPORT DATABASE 'dir' en DuckLocal
Una base de datos SQLiteNo es un archivo DuckDB; adjúntala en su lugar, con Adjuntar base de datos… o INSTALL sqlite; ATTACH '…' (TYPE sqlite);
Cualquier otra cosa que no sea un archivo DuckDBAbre en su lugar archivos CSV, Parquet, JSON o Excel como archivos de datos

Para un archivo de una DuckDB más nueva, el mensaje rellena la ruta del archivo y la versión de DuckDB de DuckLocal. Ejecútalo en la DuckDB que creó el archivo y luego abre compat.duckdb:

sql
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;

Los archivos escritos antes de DuckDB v1.2 no registran qué versión los creó. Cualquier otro fallo (un archivo bloqueado por otro programa, uno que no puedes leer) muestra solo el mensaje de DuckDB. Consulta Solución de problemas.

Qué DuckDB puede leer una base de datos ​

Cuando hay un archivo de base de datos abierto, la barra de estado muestra su ruta. Pasa el cursor por encima para ver el formato de almacenamiento del archivo (la DuckDB más antigua que lo lee, por ejemplo Formato de almacenamiento: legible por DuckDB v1.0.0+) y, cuando el archivo lo registra, la versión que lo creó (Creado por DuckDB v1.4.3). Compruébalo antes de entregar un archivo a alguien que use una DuckDB más antigua.

DuckLocal ejecuta DuckDB 2.0, pero un archivo de base de datos que crea se escribe en el formato que escribía DuckDB 1.x (legible por DuckDB v1.0.0+), así que la CLI de duckdb, Python o DBeaver con DuckDB 1.x todavía lo abren. Un archivo que otro programa escribió en el formato propio de DuckDB 2.0 (v2.0.0+) también se abre y conserva ese formato: 1.x no puede leerlo.

Bases de datos adjuntas ​

Adjunta otro archivo DuckDB o SQLite junto a la base de datos principal para consultar entre ellos; por ejemplo, una instantánea junto a los datos de hoy.

  1. Abre el menú Abrir de la barra de título y elige Adjuntar base de datos….
  2. Escribe la ruta o haz clic en Examinar para elegir el archivo.
  3. Deja Solo lectura marcado a menos que quieras modificar el archivo. Está marcado de forma predeterminada.
  4. Haz clic en Adjuntar.

La base de datos recibe un alias a partir de su nombre de archivo, y consultas sus tablas como alias.table (o alias.schema.table):

sql
-- snap-2026-10-01.duckdb adjunta como snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);

Cómo se forma el alias:

  • El nombre del archivo sin extensión, con cada carácter que no sea una letra ASCII o un dígito sustituido por _.
  • db_ delante cuando no empieza por una letra: 2026-10 logs.duckdb pasa a ser db_2026_10_logs.
  • Un contador cuando el nombre ya está ocupado: snap, luego snap_2. main nunca se usa.
  • Volver a adjuntar un archivo más tarde le devuelve el alias que tenía, así que el SQL escrito contra él sigue funcionando.

Detalles:

  • Los archivos SQLite se reconocen por su contenido y se adjuntan mediante la extensión sqlite de DuckDB.
  • Desmarcar Solo lectura adjunta el archivo para escritura. Entonces, una ruta DuckDB que no existe se crea como base de datos nueva y vacía; en solo lectura, la adjunción falla.
  • El mismo archivo nunca se adjunta dos veces. Si adjuntas un archivo que ya está abierto (como base de datos principal o como adjunto), aparece Esta base de datos ya está abierta, como ….

En la barra lateral ​

Cada base de datos aparece en el árbol de esquema, tanto la principal como las adjuntas, incluidas las vacías. Una base de datos muestra solo lectura o sqlite junto a su nombre cuando corresponde, y su archivo como información sobre herramientas.

Haz clic derecho en una base de datos para:

  • Usar como base de datos predeterminada: ejecuta USE, así que los nombres de tabla sin base de datos se resuelven ahí. La barra de estado muestra dónde se resuelven ahora.
  • Separar base de datos: la separa y la olvida, así que no vuelve la próxima vez. Si era la base de datos predeterminada, la sesión vuelve antes a la principal. El archivo en sí no se toca.

El resto de ese menú se describe en Explorador de esquema e historial.

Se conservan entre conexiones ​

Las bases de datos adjuntas se guardan en la propia base de datos de historial de DuckLocal, con su alias y su ajuste de solo lectura, y se adjuntan de nuevo en cada conexión nueva: en el siguiente arranque, después de abrir otra base de datos y después de Nueva base de datos en memoria.

  • Una base de datos cuyo archivo falta se omite en silencio. Su registro se conserva, así que vuelve cuando el archivo vuelve; DuckLocal nunca crea una base de datos vacía en su lugar.
  • Una base de datos que ya está abierta, como principal o de otra forma, no se adjunta por segunda vez.
  • Si la nueva base de datos principal ya tiene una base de datos con ese alias, DuckLocal dice No se pudo adjuntar …: el nombre … ya está ocupado en la base de datos abierta.

Abrir desde Finder ​

En un Mac, Finder puede entregar archivos directamente a DuckLocal:

ArchivoDoble clicAbrir con, o arrastrar al icono del Dock
.parquetSe abre en DuckLocalSí
.duckdb, .ddbSe abre en DuckLocalSí
.dashSe abre en DuckLocalSí
.csv, .tsv, .json, .jsonl, .ndjson, .xlsx, .xlsSe queda con la app que ya los abre (Numbers, Excel, un editor de texto)Sí

DuckLocal se registra como predeterminado solo para los formatos que ninguna otra app de un Mac reclama. Si otra app ya se ha hecho cargo de los archivos Parquet o DuckDB, elige DuckLocal en Abrir con, o usa Mostrar información → Abrir con → Cambiar todo… en Finder para convertirlo en el predeterminado.

Un archivo que llega desde Finder se trata exactamente igual que si lo arrastras a la ventana: un archivo de datos se convierte en una vista del espacio de trabajo actual, un archivo de base de datos se abre como base de datos principal y un archivo .dash se abre como pestaña de panel. Si DuckLocal no está en ejecución, primero se inicia y abre el archivo cuando termina su propio arranque.

Vistas previas de Quick Look ​

En un Mac, selecciona un archivo de datos en Finder y pulsa Espacio para ver sus columnas y sus primeras filas sin abrir nada. La vista previa viene dentro de DuckLocal.app; no hay nada que instalar aparte. Necesita macOS 12 o posterior, igual que la app.

ArchivoQué muestra la vista previa
.parquetColumnas y tipos, las primeras 50 filas y, del pie del archivo: número de filas, grupos de filas, compresión y el escritor
.duckdb, .ddbEl número de tablas, el formato de almacenamiento (Legible por DuckDB …) y las cinco tablas más grandes, cada una con su número de filas estimado y sus primeras 50 filas
.csv, .tsvColumnas con sus tipos detectados y las primeras 50 filas: una tabla en lugar de texto sin formato
.jsonl, .ndjsonColumnas y las primeras 50 filas

Los archivos .json normales y los de Excel se dejan a las vistas previas propias de macOS.

Lo que la vista previa hace y no hace:

  • Nunca escribe. La base de datos se adjunta en solo lectura.
  • Nunca escanea un archivo entero: las filas son un LIMIT, y el número de filas aparece solo donde el formato lo guarda (el pie de Parquet, la estimación de una base de datos).
  • No descarga nada: las extensiones de DuckDB ni se instalan ni se cargan.
  • Las celdas de más de 200 caracteres se cortan. El texto de la página está en inglés.
  • Un archivo que no puede leer muestra una página explicando por qué.

Si al pulsar Espacio no aparece ninguna vista previa de DuckLocal:

  1. Asegúrate de que DuckLocal está en Aplicaciones y ábrelo una vez. macOS registra la vista previa la primera vez que ve la app.
  2. Reinicia Quick Look en Terminal: qlmanage -r. Después inténtalo de nuevo.
  3. Comprueba que DuckLocal Preview está activado en Quick Look, dentro de los ajustes de extensiones de Ajustes del Sistema.

Nombres ​

La vista de un archivo se nombra a partir del nombre del archivo sin extensión, limpiado hasta formar un identificador válido. Cuando ese nombre ya está ocupado en la conexión, DuckLocal añade un contador: events, luego events_2, events_3. Dos archivos con el mismo nombre sin extensión en carpetas distintas reciben por tanto vistas distintas.

La detección de duplicados se basa en el texto de la ruta tal como se escribe, así que ./a.csv y a.csv se tratan como dos archivos distintos.

Límites ​

  • 256 archivos de datos por solicitud de apertura. El límite cubre todas las rutas de una solicitud en conjunto, no cada carpeta por separado; existe para que arrastrar una carpeta personal por accidente no bloquee la conexión durante minutos. Cuando se alcanza el límite, DuckLocal lo dice y adjunta los primeros 256 archivos.
  • Los archivos que se vuelven a adjuntar al arrancar desde la sesión anterior no están sujetos a ese límite.

Gestionar las fuentes registradas ​

Los archivos registrados aparecen en el grupo Archivos locales de la barra lateral, cada uno con su nombre de vista, su nombre de archivo y su número de filas. Al seleccionar un archivo se genera una sentencia SELECT para él.

La × de una fila de archivo lo elimina, tras un diálogo de confirmación. La eliminación descarta la vista y olvida el registro; el archivo subyacente no se toca.

Actualizar esquema vuelve a cargar el catálogo y los archivos registrados.

Lo que se recuerda ​

La lista de archivos registrados (sus rutas, nombres de vista y tipos) se guarda en la propia base de datos de historial de DuckLocal y se vuelve a adjuntar en el siguiente arranque, así que el espacio de trabajo que dejaste es el que recuperas. Lo mismo ocurre con las bases de datos adjuntas. El archivo de la base de datos principal no se recuerda: cada arranque empieza en memoria a menos que indiques una base de datos.

Consulta Ajustes y datos de la app para ver las ubicaciones en disco.

Publicado bajo la licencia Apache-2.0.