# Explorador de esquema e historial

> Explora bases de datos, tablas y columnas en la barra lateral de esquema de DuckLocal, genera consultas SELECT, gestiona extensiones de DuckDB y reutiliza consultas anteriores.

Source: https://ducklocal.app/docs/es/schema-and-history

La barra lateral tiene tres pestañas: **Esquema**, **Historial** y
**Extensiones** (**表结构**, **查询历史** y **扩展** en chino). El botón a la
izquierda de la barra de título, o **⌘B**, oculta la barra lateral y la vuelve a
mostrar; el botón se queda en el mismo sitio en ambos casos. Se recuerda si la
barra lateral está oculta.

## El árbol de esquema

De arriba abajo, el árbol muestra **Archivos locales**, **Paneles**, **Métricas** y **S3** como
pequeños encabezados grises, seguidos de tus bases de datos en filas en negrita:

- **Archivos locales** — los archivos de datos que has registrado, cada uno con
  el nombre de su vista y su número de filas. Sus hijos son las columnas de la
  vista.
  - El nombre del archivo aparece junto al nombre de la vista solo cuando los
    dos difieren (`sales_2` de `sales.csv`).
  - La carpeta aparece cuando dos archivos comparten nombre de vista.
  - Pasa el cursor por una fila para ver la ruta completa.
- **Paneles** — los paneles `.dash` que has abierto recientemente, ordenados por
  nombre para que una fila no se mueva al hacer clic.
  - Haz clic en uno para volver a abrirlo como pestaña, igual que harías con un
    archivo.
  - Dos paneles con el mismo nombre muestran su carpeta al lado. Un archivo
    alcanzado por dos escrituras de su ruta (`E:\Proj` y `E:\proj`, o una ruta
    relativa y una absoluta) es una sola entrada y abre una sola pestaña.
  - La × al pasar el cursor lo quita de la lista, sin tocar sus archivos ni
    ninguna pestaña abierta.
  - Una entrada cuya ruta ya no existe se elimina de la lista.
- **Métricas** — presente cuando hay un `model.ossie.yaml` junto a alguno de
  esos paneles. Una fila por métrica; al hacer clic se compila en el editor de
  consultas y se ejecuta. Consulta [Métricas semánticas](metrics.md#sidebar).
  Posterior a 0.4.1.
- **S3** — presente una vez que [S3 está configurado](s3.md). Carga de forma diferida.
- Cada base de datos, luego sus esquemas, luego tablas y vistas, luego columnas.
  La base de datos con la que se abrió la ventana va primero; las bases de datos
  que [adjuntaste al lado](data-sources.md#attached-databases) vienen después,
  marcadas `read-only` cuando se adjuntaron así.

Las tablas muestran recuentos de filas estimados; las vistas no. Las entradas de
columna muestran tipos de datos de DuckDB. La base de datos del sistema y los
esquemas `information_schema`, `pg_catalog` y `system` están ocultos.

El cuadro de búsqueda sobre el árbol (**Buscar tablas y columnas**) conserva solo
las filas cuyos nombres contienen lo que escribes, sin distinguir mayúsculas, y
las filas por encima de ellas. Una tabla cuyo nombre coincide conserva todas sus
columnas; una tabla que se conserva por una columna coincidente se abre para
mostrarla. Vacía el cuadro para recuperar el árbol completo.

### Bases de datos {#databases}

La base de datos principal va primero, luego cada
[base de datos adjunta](data-sources.md#attached-databases) como grupo propio,
con el número de tablas junto a su nombre.

- Una base de datos adjunta se muestra aunque esté vacía. La base de datos
  principal se omite mientras no tenga tablas, que es como empieza una sesión en
  memoria recién creada.
- Una pista atenuada junto al nombre dice **read-only**, y el tipo de archivo
  cuando no es DuckDB (**sqlite**).
- Pasa el cursor por el nombre para ver la ruta del archivo de base de datos.

Haz clic derecho en una base de datos para convertirla en la predeterminada o
para separarla — consulta [Menú contextual](#right-click-menu).

El botón de actualizar junto a las pestañas (**Actualizar esquema**) recarga el
catálogo y la lista de archivos registrados.

## Generar un SELECT

Todos los clics de abajo **reemplazan todo el búfer** de la pestaña activa — no
insertan en el cursor. Lo mismo pasa al hacer clic en una entrada del historial.
Guarda lo que te importe antes de ir haciendo clic.

Estos rellenan el editor activo al hacer clic:

| Clic | SQL generado |
| --- | --- |
| El botón de reproducir de una tabla | `SELECT * FROM db.schema.table LIMIT 100;` |
| La casilla de una columna, o su nombre | `SELECT col FROM db.schema.table LIMIT 100;` |
| Más columnas de la misma tabla | `SELECT a, b FROM db.schema.table LIMIT 100;` |
| Un objeto de S3 que es un archivo de datos | `SELECT * FROM 's3://bucket/key' LIMIT 100;` |

Cada columna, de una tabla, una vista o un archivo local, tiene una casilla. Al
marcar columnas, o al hacer clic en sus nombres, que las marca, se construye el
`SELECT` con las marcadas, en el orden de columnas de la tabla y no en el orden
en que las marcaste. Al desmarcar la última se obtiene `SELECT *`. Las marcas
pertenecen a una tabla: marcar una columna de otra tabla empieza de cero ahí.

El SQL generado ocupa tres líneas (`SELECT …`, `FROM …`, `LIMIT 100;`). Los
nombres de tabla se escriben lo más cortos que permitan la base de datos y el
esquema predeterminados actuales: `orders` para una tabla del esquema
predeterminado, `main.orders` para otro esquema de la misma base de datos, y
`database.schema.table` en los demás casos. Tras **Usar como base de datos
predeterminada** en `snap`, la vista previa de una de sus tablas dice
`FROM orders`. Hasta que se haya ejecutado la primera consulta, los nombres van
totalmente cualificados.

Un nombre se entrecomilla solo cuando contiene caracteres distintos de letras,
dígitos y guiones bajos.

## Menú contextual {#right-click-menu}

Cada comando que ofrecen los botones al pasar el cursor sobre una fila está
también en su menú contextual, así encuentras el comando sin necesidad de pasar
el cursor:

| Fila | Menú |
| --- | --- |
| Tabla o vista | Generar consulta SELECT, Resumen de columnas, Copiar nombre, Copiar información de la tabla |
| Columna | Generar consulta SELECT, Copiar nombre, Cambiar tipo de dato… (solo columnas de tablas) |
| Base de datos adjunta | Usar como base de datos predeterminada, Separar base de datos |
| Lista de buckets de S3 | Actualizar buckets |
| Panel reciente | Quitar de la lista |
| Archivo local | Generar consulta SELECT, Resumen de columnas, Copiar nombre, Copiar información de la tabla, Quitar de archivos locales |

**Copiar nombre** copia el nombre desnudo — solo el nombre de la tabla, la
columna o la vista, sin cualificar con su base de datos y su esquema, y sin
comillas.

**Copiar información de la tabla** copia la tabla entera como Markdown, lista
para pegar en un chat, un issue o el prompt de un agente de IA — el nombre que
usa una consulta, qué es, su tamaño y cada columna con su tipo:

```md
memory.main.orders (table, ~224 rows, 3 columns)

| column | type |
|---|---|
| date | DATE |
| channel | VARCHAR |
| revenue | DOUBLE |
```

**Resumen de columnas** reemplaza el texto del editor activo con
`FROM <table>;`, lo ejecuta y abre el panel de resultados en su pestaña
**Resumen**, que resume cada columna de toda la tabla: nulos, valores distintos,
rango y un pequeño gráfico de sus valores. Consulta
[Resumen de columnas](results-and-charts.md#overview).

**Usar como base de datos predeterminada** ejecuta `USE` sobre esa base de
datos, así los nombres de tabla sin base de datos se resuelven ahí y las
consultas generadas salen más cortas (ver arriba). No se ofrece en la base de
datos que ya es la predeterminada.

**Separar base de datos** separa una base de datos adjunta y la olvida, así no
se vuelve a adjuntar la próxima vez. Si era la predeterminada, la sesión pasa
antes a otra base de datos. El archivo no se toca. La base de datos principal no
se puede separar, así que su menú no tiene ese elemento. Más en
[Bases de datos adjuntas](data-sources.md#attached-databases).

## Cambiar el tipo de una columna

Una fila de columna ofrece una acción de tipo (no disponible en columnas de
vistas, así que las columnas de CSV y Parquet adjuntos no se pueden retipar).
Abre un diálogo de texto libre rellenado con el tipo actual y ejecuta:

```sql
ALTER TABLE db.schema.table ALTER COLUMN col SET DATA TYPE <what you typed>
```

Aquí el nombre de la tabla siempre va totalmente cualificado, y el nombre de la
columna se entrecomilla solo cuando hace falta.

No hay selector ni lista de validación — cualquier cadena de tipo de DuckDB
funciona, incluidas las parametrizadas como `DECIMAL(10,2)`. Un tipo no válido
vuelve como notificación de error. Si va bien, se recarga el catálogo.

Renombrar y eliminar columnas, y editar comentarios de columnas, no están
disponibles.

## Quitar un archivo registrado

La **×** de una fila de archivo pide confirmación y luego elimina la vista y
olvida el registro. **El archivo en disco no se toca.**

Para quitar varios registros a la vez, selecciona sus filas en
**Archivos locales**:

- **⌘-clic** en macOS o **Ctrl-clic** en Windows/Linux añade o quita un archivo de la selección.
- **Mayús-clic** selecciona un rango consecutivo.
- Haz clic en **×** en un archivo seleccionado, o usa su acción de quitar del menú contextual, para confirmar que quieres quitar los registros seleccionados. El menú indica cuántos archivos se quitarán.

Esto quita las vistas y los registros y deja los archivos originales en disco.
Seleccionar archivos de esta forma no selecciona tablas de base de datos ni
filtros de paneles.

## Extensiones {#extensions}

La pestaña **Extensiones** lista todas las extensiones de DuckDB que conoce el
motor: primero las cargadas, luego las instaladas y luego el resto, cada grupo
por nombre.

Cada fila muestra:

- el nombre de la extensión y una etiqueta de estado: **Cargada**,
  **Instalada** o **No instalada**;
- la descripción de una línea que da DuckDB;
- su versión y de dónde vino: **integrada**, o el repositorio desde el que se
  instaló (`core`, `community` o una URL).

Qué significan los estados:

| Estado | Significado |
| --- | --- |
| Cargada | Activa en la conexión actual: sus funciones, lectores y tipos funcionan ya en las consultas |
| Instalada | Descargada en esta máquina, pero no cargada en esta conexión |
| No instalada | DuckDB la conoce, pero aún no está en esta máquina |

Las extensiones **integradas** están compiladas en DuckLocal — `parquet` y `json`
entre ellas, ambas cargadas desde el principio. Nunca se instalan ni se
actualizan.

Las extensiones de la comunidad se instalan igual. Desde 0.4.1 la pestaña llega
al repositorio de la comunidad de DuckDB además del repositorio principal, así
que una extensión como `mssql` (SQL Server) se puede instalar y cargar sin salir
de la app; la etiqueta del repositorio en la fila dice `community`.

Una fila ofrece las acciones que le corresponden:

| Botón | Se muestra cuando | Ejecuta |
| --- | --- | --- |
| **Instalar** | No instalada | `INSTALL name` |
| **Cargar** | Instalada, no cargada | `LOAD name` |
| **Actualizar** | Instalada desde un repositorio | `UPDATE EXTENSIONS (name)` |

- **Instalar** y **Actualizar** descargan del repositorio de extensiones de
  DuckDB, así que necesitan red. **Cargar** lee el archivo instalado y no la
  necesita.
- Instalar no carga. Haz clic en **Cargar** después, o ejecuta `LOAD name`.
- Una extensión instalada sigue instalada: es un archivo en disco, en la carpeta
  de extensiones propia de DuckDB. La carga dura solo lo que dura la conexión
  actual.
- Esa carpeta es por versión de DuckDB (`~/.duckdb/extensions/v2.0.0/…`). Cuando
  una actualización lleva DuckLocal a una nueva versión de DuckDB, como hizo
  0.3.0 con DuckDB 2.0, las extensiones que tenías aparecen como **No instalada**
  hasta que las vuelvas a instalar.
- Se ejecuta una acción a la vez; mientras tanto, los demás botones están
  desactivados. Una notificación dice *Instalada …*, *Cargada …* o
  *Actualizada …*, o por qué falló.
- Tras una carga o una actualización, se recarga el árbol de esquema, ya que una
  extensión puede traer tablas y funciones consigo.

La lista se lee de `duckdb_extensions()` cada vez que se abre la pestaña, tras
cada acción, cuando cambia la conexión mientras la pestaña está abierta y cuando
haces clic en el botón de actualizar junto a las pestañas (**Actualizar
extensiones**). Así también muestra una extensión cargada de otra forma — por un
`LOAD` escrito en una pestaña de consulta, o por DuckDB por su cuenta.

Desde v0.2.1, ni la ventana ni la CLI descargan automáticamente una extensión que
falte cuando una consulta la necesita. Instálala de forma explícita en
**Extensiones** o con `INSTALL name`. Las extensiones que ya estén instaladas en
esta máquina se pueden seguir cargando automáticamente.

### Abrir la UI de DuckDB {#duckdb-ui}

La [UI de DuckDB](https://duckdb.org/2025/03/12/duckdb-ui) — el cuaderno de
navegador propio de DuckDB, creado por MotherDuck — es una extensión como
cualquier otra, así que también se ejecuta dentro de DuckLocal:

1. En la pestaña **Extensiones**, haz clic en **Instalar** en la fila `ui` y
   luego en **Cargar**.
2. En una pestaña de consulta, ejecuta:

   ```sql
   CALL start_ui();
   ```

   Tu navegador abre la UI en `http://localhost:4213`. Para iniciar el servidor
   sin abrir un navegador, ejecuta `CALL start_ui_server();` en su lugar.

![La pestaña Extensiones con la extensión ui cargada](../assets/duckdb-ui.png)

La UI se ejecuta sobre la instancia de DuckDB desde la que se inició, que aquí es
la de DuckLocal. Algunas cosas que conviene saber:

- **Necesita red.** Instalar `ui` la descarga, como cualquier extensión. Y cada
  vez que arranca, el servidor local de la extensión descarga los archivos
  propios de la UI desde `https://ui.duckdb.org`. Tus consultas y tus datos se
  siguen ejecutando en local.
- **Vive lo que vive DuckLocal.** Al salir de DuckLocal se cierra su instancia de
  DuckDB y, con ella, el servidor. `CALL stop_ui_server();` lo detiene antes.
- **Los cuadernos los guarda la extensión, no DuckLocal,** en
  `~/.duckdb/extension_data/ui/`. El historial de consultas de DuckLocal no
  incluye lo que ejecutes en la UI.
- **No puede ejecutarse directamente sobre una base de datos de solo lectura.**
  Adjunta esa base de datos desde un cuaderno con `ATTACH '…' (READ_ONLY)`.

[DuckDB UI vs DuckLocal](https://ducklocal.app/blog/duckdb-ui-vs-ducklocal/)
compara las dos y explica cuándo usar cada una.

## Historial de consultas {#query-history}

Cada ejecución se registra — tanto los aciertos como los fallos — con una marca
de tiempo en hora local, la duración en milisegundos, el número de filas (o de
filas afectadas en DML) y el texto del error si falló. Las entradas fallidas se
muestran en rojo con una etiqueta *Fallida*.

La lista muestra las **200** entradas más recientes. Al hacer clic en una fila se
rellena el editor activo con ese SQL y se le da el foco, reemplazando lo que
hubiera.

No hay política de retención ni purga: la tabla de historial crece sin límite y
la interfaz solo muestra las 200 más recientes. Tampoco hay búsqueda, ni filtro,
ni exportación, ni forma de borrar una entrada desde la interfaz.

El historial se guarda en el archivo de base de datos propio de DuckLocal, no en
la base de datos que tengas abierta, así que sobrevive al cambio de base de datos
y a la pérdida de tu espacio de trabajo. Consulta
[Ajustes y datos de la app](settings-and-data.md) para saber dónde está.
