# Fuentes de datos

> Consulta archivos CSV, Parquet, JSON y Excel en local con DuckDB SQL. Abre carpetas y patrones, adjunta bases de datos y mantén los datos en tu ordenador.

Source: https://ducklocal.app/docs/es/data-sources

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](https://ducklocal.app/use-cases/local-data-analysis/) 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](#open-from-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](#attached-databases).

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 {#supported-file-formats}

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

| Extensión | Cómo se lee |
| --- | --- |
| `.csv`, `.tsv`, `.txt` | vista `read_csv_auto` |
| `.parquet` | vista `read_parquet` |
| `.json`, `.ndjson`, `.jsonl` | vista `read_json_auto` |
| `.xlsx`, `.xls`, `.xlsb`, `.ods` | se 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](#database-files).

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 {#folders-and-patterns}

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 {#many-csv-files-at-once}

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 {#database-files}

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](#attached-databases).

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](#when-a-database-will-not-open)). 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 {#when-a-database-will-not-open}

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 archivo | Qué te dice DuckLocal |
| --- | --- |
| Un archivo DuckDB escrito por una **versión de DuckDB más nueva** que la integrada en DuckLocal | Ambas 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 anterior** | Ejecuta `EXPORT DATABASE 'dir'` con la DuckDB que lo escribió y luego `IMPORT DATABASE 'dir'` en DuckLocal |
| Una base de datos **SQLite** | No es un archivo DuckDB; adjúntala en su lugar, con [Adjuntar base de datos…](#attached-databases) o `INSTALL sqlite; ATTACH '…' (TYPE sqlite);` |
| Cualquier otra cosa que **no sea un archivo DuckDB** | Abre 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](troubleshooting.md#opening-a-database).

### Qué DuckDB puede leer una base de datos {#storage-version}

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 {#attached-databases}

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 {#in-the-sidebar}

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](schema-and-history.md).

### Se conservan entre conexiones {#kept-across-connections}

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 {#open-from-finder}

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

| Archivo | Doble clic | Abrir con, o arrastrar al icono del Dock |
| --- | --- | --- |
| `.parquet` | Se abre en DuckLocal | Sí |
| `.duckdb`, `.ddb` | Se abre en DuckLocal | Sí |
| `.dash` | Se abre en DuckLocal | Sí |
| `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`, `.xlsx`, `.xls` | Se 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](dashboards.md). Si DuckLocal no está en ejecución, primero se inicia y abre el archivo cuando termina su propio arranque.

## Vistas previas de Quick Look {#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.

| Archivo | Qué muestra la vista previa |
| --- | --- |
| `.parquet` | Columnas y tipos, las primeras 50 filas y, del pie del archivo: número de filas, grupos de filas, compresión y el escritor |
| `.duckdb`, `.ddb` | El 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`, `.tsv` | Columnas con sus tipos detectados y las primeras 50 filas: una tabla en lugar de texto sin formato |
| `.jsonl`, `.ndjson` | Columnas 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](#kept-across-connections). 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](settings-and-data.md) para ver las ubicaciones en disco.
