> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puente.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Databases

> Datos persistentes con schema, asistente IA, tipos de columna avanzados e importación CSV. Editadas desde el módulo Tables del workspace.

<Frame>
  <img src="https://mintcdn.com/puenteos/MFY1kiPfI9fyixWy/images/Screenshot-2026-06-03-at-3.46.27-PM.png?fit=max&auto=format&n=MFY1kiPfI9fyixWy&q=85&s=63a223b8c16095848c845b5b2eb3bbcc" alt="Screenshot 2026 06 03 At 3 46 27 PM" width="1550" height="881" data-path="images/Screenshot-2026-06-03-at-3.46.27-PM.png" />
</Frame>

**Databases** es el Build type para datos persistentes en Puente OS. Cada Database tiene un schema tipado (columnas con tipo), se conecta automáticamente a Apps y Workflows del workspace, y se edita visualmente desde el módulo **Tables**.

<Note>
  **Vocabulario:** "Database" es el Build type canónico (App / Agent / Workflow / Database). El editor visual donde la operas se llama **Tables** — son la misma cosa vista desde dos ángulos: el artefacto y la interfaz.
</Note>

## Crear una Database

<Steps>
  <Step title="Abre el editor Tables">
    Desde el panel de Componentes de un Project → **+ Nuevo** → **Database**.
  </Step>

  <Step title="Define el schema">
    Click en el botón **`+`** del encabezado para agregar la primera columna. Ponle nombre, elige el tipo y confirma. La Database se crea en el backend con esa primera columna.
  </Step>

  <Step title="Agrega más columnas">
    Repite el paso anterior para cada columna que necesites. También puedes importar todo de una vía CSV.
  </Step>
</Steps>

<Note>
  El nombre interno (`key`) se genera automáticamente en snake\_case. El nombre visible (label) puedes cambiarlo después sin afectar la integración.
</Note>

<Tip>
  Si abres el editor sin una Database seleccionada, parte en estado vacío: puedes agregar columnas a mano o crear toda la Database desde un CSV. Al agregar la primera columna, se crea en el backend automáticamente.
</Tip>

***

## Tipos de columna

| Tipo         | Cómo se muestra       | Cómo se edita         | Ejemplo          |
| ------------ | --------------------- | --------------------- | ---------------- |
| **Texto**    | Texto plano           | Input inline          | `"MacBook Pro"`  |
| **Número**   | Alineado a la derecha | Input numérico        | `2499.99`        |
| **Fecha**    | `DD/MM/YYYY`          | Date picker           | `2026-02-15`     |
| **Checkbox** | Checkbox centrado     | Toggle directo        | `true` / `false` |
| **Select**   | Badge de color        | Dropdown con opciones | `"Electrónica"`  |

### Sobre tipo `select`

* Las opciones se definen al crear o editar la columna
* Solo se aceptan valores dentro de las opciones definidas
* El backend valida automáticamente al insertar o actualizar filas

***

## Importar desde CSV

<Steps>
  <Step title="Click en Import CSV">
    En la toolbar. Si la Database está vacía, también aparece **"Crear desde CSV"** en el estado vacío.
  </Step>

  <Step title="Nombra la Database">
    Solo al crear una Database nueva: ingresa nombre y una descripción opcional.
  </Step>

  <Step title="Sube el archivo">
    Arrastra el CSV o haz click para seleccionar. Soporta delimitadores `,` y `;`, con o sin comillas. El archivo se procesa en tu navegador, no se sube al backend hasta confirmar.
  </Step>

  <Step title="Revisa las columnas detectadas">
    El sistema detecta automáticamente el tipo de cada columna. Puedes corregir cualquier tipo antes de confirmar. Se muestra una preview con las primeras 5 filas.
  </Step>

  <Step title="Confirma">
    Se crea la Database y se cargan todas las filas en bulk.
  </Step>
</Steps>

<Warning>
  Límite: **máximo 10,000 filas por importación**. Para datasets más grandes, divide en múltiples archivos.
</Warning>

### Detección automática de tipos

| Tipo detectado | Patrón                           |
| -------------- | -------------------------------- |
| `boolean`      | `true`/`false`/`si`/`no`/`1`/`0` |
| `number`       | Todos los valores numéricos      |
| `date`         | `YYYY-MM-DD`, `DD/MM/YYYY`       |
| `text`         | Fallback (todo lo demás)         |

***

## Trabajar con filas

### Agregar fila

Click en **+ New Row** en la toolbar. Se abre un modal con todos los campos. Completa y confirma.

### Editar celda

Click directo en cualquier celda. La celda entra en modo edición según el tipo (input, dropdown, toggle, date picker). Confirma con `Enter` o haciendo click fuera.

### Eliminar filas

| Caso             | Cómo                                                                       |
| ---------------- | -------------------------------------------------------------------------- |
| **Una fila**     | Click en el icono de papelera al final de la fila, luego confirma          |
| **Varias filas** | Selecciona con checkboxes → click en **Eliminar seleccionadas** → confirma |

<Warning>
  La eliminación de filas es **irreversible**. No hay papelera de reciclaje.
</Warning>

### Selección múltiple

Activa los checkboxes de la columna izquierda para seleccionar varias filas. El checkbox del encabezado selecciona **todas las filas visibles** de una vez. Úsalo para eliminar en lote o accionar sobre el conjunto seleccionado.

***

## Trabajar con columnas

### Agregar columna

Click en `+` al final del encabezado. Completa nombre, tipo y opciones (para `select`).

### Redimensionar

Arrastra el borde derecho del encabezado de cualquier columna.

### Reordenar

Arrastra el encabezado a la posición deseada.

### Ocultar/mostrar

Click en **Columns** en la toolbar y activa/desactiva cada columna. Las ocultas no se eliminan, solo se esconden visualmente.

### Editar nombre o descripción de la Database

Click en el icono de lápiz (**✏️**) en la barra superior, modifica el nombre o la descripción y confirma.

***

## Búsqueda, filtros y orden

### Búsqueda global

Campo **Search…** en la toolbar. Opera sobre todas las columnas visibles simultáneamente. Instantánea, sin llamadas al backend.

### Filtros avanzados

Click en **Filter** → agrega condiciones con `+`. Para cada condición elige columna y operador:

| Operador       | Tipos         | Descripción                   |
| -------------- | ------------- | ----------------------------- |
| `contains`     | texto         | El valor contiene el texto    |
| `not_contains` | texto         | El valor NO contiene el texto |
| `is`           | todos         | Igual exacto                  |
| `is_not`       | todos         | Distinto                      |
| `is_empty`     | todos         | Vacío o nulo                  |
| `is_not_empty` | todos         | No vacío                      |
| `gt` / `gte`   | número, fecha | Mayor (o igual) que           |
| `lt` / `lte`   | número, fecha | Menor (o igual) que           |

<Tip>
  Múltiples condiciones se combinan con **AND** lógico.
</Tip>

### Ordenamiento

Click en el encabezado de cualquier columna. Cicla entre **ascendente → descendente → sin orden**. También puedes definir un orden por defecto con los props `defaultSortColumn` y `defaultSortDirection`.

***

## Asistente IA

<Card icon="robot">
  El asistente IA tiene acceso al schema y a una muestra de hasta 20 filas reales. Puedes preguntarle sobre tus datos sin escribir SQL ni fórmulas.
</Card>

### Cómo abrirlo

Click en **IA** en la barra superior derecha. El panel ocupa 320px a la derecha y la tabla se reacomoda automáticamente (funciona tanto en paginación como en scroll infinito).

### Qué puede hacer

Pregúntale cosas como:

```text theme={null}
¿Cuántas filas tienen el precio mayor a 1000?
¿Qué productos están activos?
Muéstrame un resumen de los datos
¿Qué columnas tiene esta Database y de qué tipo son?
```

### Reset del chat

Click en el icono de reinicio dentro del panel para borrar el historial. La conversación vive solo en memoria mientras tienes la Database abierta.

***

## Exportar a CSV

Click en **Export** en la toolbar. Se descarga un CSV con:

* Los datos visibles actualmente (respetando filtros y orden activos)
* Las columnas en el orden actual (excluyendo las ocultas)

***

## Paginación vs Scroll infinito

|                 | **Paginación**                                | **Scroll infinito**                    |
| --------------- | --------------------------------------------- | -------------------------------------- |
| Navegación      | Botones Anterior / Siguiente / página directa | Scroll carga más filas automáticamente |
| Carga inicial   | Filas según `pageSize` (default 10)           | 3,000 filas                            |
| Carga adicional | Al llegar a la última página                  | Al scrollear al final, carga 3,000 más |

### Configuración de paginación

| Prop              | Default             | Descripción           |
| ----------------- | ------------------- | --------------------- |
| `pageSize`        | `10`                | Filas por página      |
| `pageSizeOptions` | `[10, 25, 50, 100]` | Opciones del selector |

<Note>
  En modo paginación, deja que el contenedor crezca con el contenido (sin altura fija). En scroll infinito, el componente usa altura fija y scrollea por dentro.
</Note>

***

## Personalización visual

Los colores y tamaños del editor son configurables desde el panel de la App:

| Prop                    | Default   | Qué controla                            |
| ----------------------- | --------- | --------------------------------------- |
| `backgroundColor`       | `#ffffff` | Fondo del grid                          |
| `headerBackgroundColor` | `#f4f4f5` | Fondo del encabezado                    |
| `textColor`             | `#374151` | Color del texto de las celdas           |
| `borderColor`           | `#e5e7eb` | Bordes y separadores                    |
| `accentColor`           | `#3b82f6` | Selección, focus y botones principales  |
| `rowHoverColor`         | `#f9fafb` | Color al pasar el cursor sobre una fila |
| `fontSize`              | `13px`    | Tamaño de fuente del contenido          |
| `headerFontSize`        | `12px`    | Tamaño de fuente de los encabezados     |
| `rowHeight`             | `36px`    | Altura de cada fila                     |

***

## Conectar con Apps y Workflows

Las Databases son **first-class citizens** del workspace. Cualquier App o Workflow puede leer y escribir.

<CardGroup cols={2}>
  <Card title="Conectar a una App" icon="window" href="/componentes/app-builder#conectar-databases">
    Desde el tab Datos del App Builder, selecciona tu Database y mapea columnas. La App deja de usar datos mock.
  </Card>

  <Card title="Trigger de Workflow" icon="diagram-project" href="/componentes/workflows">
    Configura un Workflow para que se dispare cuando una fila cambie, se agregue o se elimine.
  </Card>
</CardGroup>

***

## Preguntas frecuentes

<AccordionGroup>
  <Accordion title="¿Hay límite de filas por Database?">
    No hay límite duro. Con scroll infinito (virtual scroll), el editor maneja 50,000+ filas sin degradación, porque solo renderiza las filas visibles más un buffer. La importación CSV está capada en 10,000 filas por archivo. Para datasets de millones de filas, escribe a soporte para discutir opciones.
  </Accordion>

  <Accordion title="¿Puedo restaurar una fila eliminada?">
    No. La eliminación es irreversible. Si necesitas auditoría, considera agregar una columna `estado` con un valor `archivado` en vez de eliminar.
  </Accordion>

  <Accordion title="¿Cómo agrego columnas a una Database que ya tiene datos?">
    Usa el botón `+` del encabezado. El schema se migra automáticamente y las filas existentes quedan sin valor en la nueva columna (aparecen como `null`).
  </Accordion>

  <Accordion title="¿Qué pasa si cambio el tipo de una columna que ya tiene datos?">
    El sistema intenta convertir los valores existentes al nuevo tipo. Si un valor no se puede convertir, queda como `null` y se te notifica antes de confirmar.
  </Accordion>

  <Accordion title="¿Las Databases tienen historial de cambios?">
    No en el editor visual. Si necesitas auditoría, configura un Workflow con trigger en `rowAdd`/`cellChange` que guarde el cambio en otra Database de historial.
  </Accordion>
</AccordionGroup>