Ir al contenido

Explorador de esquema e historial ​

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. Posterior a 0.4.1.
  • S3 — presente una vez que S3 está configurado. 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 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 ​

La base de datos principal va primero, luego cada base de datos adjunta 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.

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:

ClicSQL generado
El botón de reproducir de una tablaSELECT * FROM db.schema.table LIMIT 100;
La casilla de una columna, o su nombreSELECT col FROM db.schema.table LIMIT 100;
Más columnas de la misma tablaSELECT a, b FROM db.schema.table LIMIT 100;
Un objeto de S3 que es un archivo de datosSELECT * 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 ​

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:

FilaMenú
Tabla o vistaGenerar consulta SELECT, Resumen de columnas, Copiar nombre, Copiar información de la tabla
ColumnaGenerar consulta SELECT, Copiar nombre, Cambiar tipo de dato… (solo columnas de tablas)
Base de datos adjuntaUsar como base de datos predeterminada, Separar base de datos
Lista de buckets de S3Actualizar buckets
Panel recienteQuitar de la lista
Archivo localGenerar 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.

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.

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 ​

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:

EstadoSignificado
CargadaActiva en la conexión actual: sus funciones, lectores y tipos funcionan ya en las consultas
InstaladaDescargada en esta máquina, pero no cargada en esta conexión
No instaladaDuckDB 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ónSe muestra cuandoEjecuta
InstalarNo instaladaINSTALL name
CargarInstalada, no cargadaLOAD name
ActualizarInstalada desde un repositorioUPDATE 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 ​

La UI de DuckDB — 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

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 compara las dos y explica cuándo usar cada una.

Historial de consultas ​

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 para saber dónde está.

Publicado bajo la licencia Apache-2.0.