Bases de Datos
Bases de datos — Referencia Técnica
Una mirada técnica a cómo las Bases de datos almacenan datos, se sincronizan en tiempo real, valida los tipos de columna y ejecuta las tareas de agentes.
Esta página describe cómo se comportan las Bases de datos por debajo de la interfaz, en términos técnicos, para desarrolladores y usuarios con perfil técnico. Asume familiaridad con bases de datos relacionales, JSON y APIs cliente–servidor, y se centra en el comportamiento observable y los contratos de datos, no en detalles de implementación.
Modelo de arquitectura
Las Bases de datos mantienen dos aspectos separados:
- Estructura (metadatos) — espacios, bases de datos, definiciones de columnas, vistas y conectores.
- Datos de registros — las filas almacenadas en cada base de datos.
Los datos de registros viven en una base de datos relacional y están aislados por espacio de trabajo: cada consulta se limita al espacio de trabajo propietario, y los registros de cuentas distintas nunca se mezclan.
Los clientes usan dos canales:
| Canal | Para qué se usa |
|---|---|
| API REST | Operaciones de estructura y metadatos (espacios, bases de datos, columnas, vistas, conectores), consultas de IA y exportaciones |
| WebSocket | Operaciones a nivel de registro (seleccionar, insertar, actualizar, eliminar) y actualizaciones en vivo difundidas a otros clientes conectados |
Entidades y relaciones
| Entidad | Descripción |
|---|---|
| Espacio | Un espacio de nombres que agrupa bases de datos relacionadas y corresponde a un contenedor de datos aislado. |
| Base de datos | Una colección de registros regida por un esquema de columnas tipado. |
| Columna | Un campo tipado definido por un tipo amigable, un tipo de almacenamiento subyacente y restricciones. |
| Registro | Una fila de valores de columna, más un cuerpo de contenido enriquecido y un icono. |
| Vista | Una configuración guardada (tipo + filtros, orden, agrupación, columnas visibles) sobre una base de datos. |
| Conector | Una fuente de datos externa vinculada a una base de datos que incorpora registros automáticamente. |
Almacenamiento y sincronización en tiempo real
- Los cambios estructurales (bases de datos, columnas, vistas, conectores) se realizan a través de la API REST. El cliente aplica actualizaciones optimistas y revierte si una solicitud falla.
- Las operaciones sobre registros se ejecutan por una conexión WebSocket persistente. Los registros se cargan en lotes (paginación); los lotes posteriores se anexan a los anteriores.
- Cuando cualquier cliente cambia un registro, el cambio se difunde a los demás clientes conectados a la misma base de datos, que se actualizan en vivo.
- Los cambios hechos por programa — por agentes de IA, automatizaciones o conectores — emiten las mismas notificaciones de cambio, así que los clientes abiertos se actualizan automáticamente.
Edición de páginas en tiempo real
El contenido de página de los registros usa un canal de edición colaborativa dedicado, separado de la conexión de operaciones sobre registros descrita arriba:
- Mientras una página de registro está abierta, todos los editores conectados (usuarios, invitados con permiso de edición y agentes) comparten un documento en vivo. Las ediciones se combinan con semántica libre de conflictos — los cambios concurrentes de varios editores se fusionan de forma determinista, carácter por carácter, sin bloqueos ni actualizaciones perdidas.
- El formato de almacenamiento sigue siendo markdown: el documento en vivo se persiste de vuelta al registro segundos después de que cesan las ediciones, y cuando el último editor se desconecta. Las lecturas de los agentes reflejan el documento en vivo, no solo el último valor persistido.
- La presencia (cursores y selecciones con nombre) forma parte del mismo canal.
- Si un cliente se desconecta a mitad de una edición, se reincorpora resincronizándose con el documento compartido actual; la versión compartida es la autoritativa.
Sistema de tipos de columna
Cada columna tiene un tipo amigable (el tipo visible para el usuario) que se asigna a un tipo de almacenamiento subyacente más reglas de validación. Los valores se validan al escribir y se rechazan si no cumplen.
| Categoría | Tipos | Almacenamiento |
|---|---|---|
| Escalar | text, number, date, checkbox, email, url, phone, currency, rating, progress, duration, uuid | Primitivos de almacenamiento con restricciones (rangos, formatos) |
| De opción | status, select, multi_select | Validados contra un conjunto de opciones definido |
| Compuesto | file, person, relation, multi_select | Valores codificados en JSON |
Los valores compuestos se almacenan como JSON. Estas formas son el contrato de datos que la API REST y las herramientas de los agentes leen y escriben:
| Tipo | Forma del valor |
|---|---|
file | { "url", "name", "size", "type" } |
person | arreglo de entradas { "type", ... } |
relation | { "id", "title", "icon", ... } |
multi_select | [ "Option A", "Option C" ] |
Los valores de opción deben coincidir con una de las opciones configuradas de la columna; los tipos numéricos (rating, progress, duration) aplican sus rangos.
Vistas y el modelo de consulta
Una vista almacena un objeto de configuración: su tipo más filtros, orden, agrupación, columnas visibles y ajustes específicos del tipo (por ejemplo, la columna de agrupación para Kanban o la columna de fecha para Calendario).
- La configuración se aplica al momento de la consulta — el filtrado y el orden ocurren cuando se obtienen los registros.
- Los operadores de filtro cubren igualdad, comparación, subcadena, pertenencia, vacío y comprobaciones booleanas, con un manejo explícito de NULL para los operadores negativos (por ejemplo, "no es" y "no es ninguno de" incluyen valores NULL).
- Para las vistas públicas y de invitado, los filtros incrustados y las columnas ocultas de la vista se aplican del lado del servidor y el cliente no puede saltárselos. Los filtros que aporta quien la ve se agregan encima solo para esa sesión.
Conectores
Los conectores usan un modelo de sincronización por sondeo (polling) en lugar de entrega por push:
- Las entradas nuevas se obtienen en un intervalo fijo (actualmente cada 30 minutos). Si un componente no está disponible por un momento, el siguiente ciclo se pone al día, así que no se pierde ninguna entrada.
- Cada ciclo procesa solo las entradas creadas desde la última sincronización exitosa y deduplica por el identificador único de la fuente.
- Las columnas que requiere un conector se crean de forma idempotente durante la configuración y en la ingesta.
Tareas de agentes
Una tarea de agente vincula un agente + instrucción + modo de ejecución a un único registro.
Estados de ejecución:
Modos: inmediato, programado (una fecha y hora) o por evento (una columna de estado/selección del registro que alcanza un valor objetivo, ya sea por una persona o por un agente).
- Cadenas — un agente puede actualizar otro registro cuyo disparador por evento inicia al siguiente agente, formando flujos de varios agentes sin un grafo de flujo explícito.
- Protección contra autobucles — un registro que ya está en
pending,queuedorunningno puede iniciar una nueva tarea. - Concurrencia y tiempo límite — límites por tabla de tareas ejecutándose a la vez (las que sobran esperan un cupo libre) y de tiempo de ejecución (luego
timeout). - Cada ejecución produce un registro de ejecución: el contexto del registro entregado, el razonamiento del agente y sus llamadas a herramientas.
Acceso programático
Los agentes y las automatizaciones operan sobre una base de datos a través de una interfaz de herramientas: seleccionar, insertar, actualizar, eliminar, inspeccionar la estructura y consulta en lenguaje natural.
- Cada herramienta se genera contra el esquema de columnas de la base de datos e incluye pistas de formato, para que el agente entregue los valores con la forma correcta — listas de opciones para columnas de opción, códigos de moneda, rangos de calificación y las formas JSON de arriba para columnas compuestas.
- Las herramientas que cambian registros emiten las mismas notificaciones de actualización en vivo que las ediciones hechas en la interfaz.
Límites y garantías
- Las lecturas de registros son paginadas; las bases de datos grandes se transmiten en lotes.
- Los valores compuestos son JSON — los clientes deben serializar y deserializar en consecuencia.
Qué sigue
- Proyectos: la siguiente sección; dale a tus agentes documentos y archivos con los que trabajar.
- Conecta una base de datos a un agente: la configuración del lado del agente para las herramientas descritas aquí.