Tablas y campos

Antes de que haya pantallas hay datos: las tablas donde la aplicación guarda cuentas, contactos, pedidos o solicitudes de vacaciones. En Keplin esos datos viven en una base de datos conectada a la app (un datasource) y se describen en un modelo — el diseño de tablas, campos, claves y relaciones que todo el resto de la plataforma lee.

Esta página trata de la primera mitad de ese trabajo: crear y cambiar tablas, elegir tipos, definir claves e índices. Las relaciones y los campos enumerados tienen página propia en Relaciones y enums.

Los ejemplos son de la app Gestión de Clientes: un CRM con tres tablas — contas, contactos y oportunidades.

#Dos capas: la base de datos y el modelo

Merece la pena separar desde ya dos cosas que se parecen:

Capa	Qué es	Quién la usa
La base de datos	Las tablas, columnas e índices que existen de verdad en el motor conectado a la app.	El motor de base de datos. Cambiarla es ejecutar comandos reales.
El modelo	La descripción de esas tablas para la plataforma: entidades, campos, nombres amigables, descripciones, relaciones y enums.	Las APIs, las pantallas, los scripts y los informes.

Una tabla solo entra en el modelo cuando la importas — y salir del modelo no elimina nada en la base de datos. Por eso la plataforma distingue siempre Quitar del modelo de Eliminar.

#Abrir el modelo

1. Abre la app y elige la pestaña Datos en la barra lateral.
2. En Fuentes de datos, haz clic en el nombre del datasource — en la Gestión de Clientes, Dados CRM.
3. Se abre una pestaña con el diagrama del modelo en el centro, la consola SQL abajo, y el árbol de objetos del datasource expandido en la barra lateral.

El diagrama se arrastra con el ratón; los botones de la esquina inferior izquierda hacen zoom y lo encuadran todo. La posición de cada entidad queda guardada — ordenas el diagrama una vez y así es como vuelve a abrirse.

#El árbol de objetos

Bajo el datasource, el árbol muestra lo que existe en la base de datos, agrupado y con el recuento de cada grupo:

Grupo	Qué lista
Tablas	Las tablas del motor. Cada una tiene menú propio (⋯).
Vistas	Las vistas (consultas guardadas con nombre).
Programación	Funciones / Procedimientos y Triggers — ver Triggers.

La caja Buscar en todo… en la parte superior de la barra lateral filtra el árbol; con búsqueda activa los grupos se abren solos y un grupo sin resultados desaparece.

#Crear una tabla

1. Pasa el ratón por el datasource y abre el menú ⋯ (Acciones de …).
2. Elige Nueva tabla.
3. Rellena el Nombre de la tabla — es el nombre que queda en la base de datos (minúsculas y guion bajo te ahorran dolores de cabeza: actividades, linhas_encomenda).
4. Schema (opcional) solo interesa en motores con schemas; déjalo vacío si no los usas.
5. En Descripción de la tabla, escribe para qué sirve. No es decoración: esta descripción acompaña a la tabla en la plataforma y es lo que explica la tabla a quien llegue después de ti.
6. Define las columnas (a continuación) y confirma con Crear tabla.

#Las columnas

El panel izquierdo del diálogo es la lista de columnas (Columnas (N)) y el botón + añade una. Haz clic en una columna de la lista para editarla a la derecha.

La tabla empieza siempre con una columna id, de tipo integer, con Clave primaria (PK) y Autoincremento activados — el arranque que sirve a 9 de cada 10 tablas.

Campo	Qué hace
Nombre	El nombre de la columna en la base de datos.
Tipo	El tipo lógico de la columna (lista completa abajo).
Tamaño	Solo en text y char — cuántos caracteres caben.
Precisión · Escala	Solo en decimal — total de dígitos y cuántos quedan a la derecha de la coma (18 · 2 para dinero).
Elementos del enum	Solo en enum — ver Relaciones y enums.
Permite NULL	Si la columna acepta quedarse vacía. Desactivado, la base de datos rechaza registros sin valor.
Clave primaria (PK)	Identifica el registro de forma única.
Autoincremento	El motor genera el valor en cada inserción.
Descripción	Para qué sirve esta columna.

La papelera que aparece al pasar el ratón sobre una columna de la lista la quita (en una tabla nueva, sale enseguida de la lista).

#Los tipos de columna

Los tipos son lógicos: describes lo que la columna guarda y la plataforma lo traduce al tipo correcto del motor conectado. El mismo diseño sirve para cualquier base de datos soportada.

Tipo	Para qué
text	Texto de longitud variable — nombres, descripciones, notas.
char	Texto de longitud fija — códigos de país, siglas.
integer	Números enteros. El tipo natural de un id.
smallint	Enteros pequeños.
bigint	Enteros grandes — contadores, identificadores externos.
decimal	Números exactos con decimales. Es el tipo del dinero.
float	Números aproximados — mediciones, porcentajes científicos.
boolean	Sí/No.
date	Una fecha, sin horas.
time	Una hora, sin fecha.
datetime	Fecha y hora.
uuid	Identificadores universales.
json	Estructuras libres guardadas como texto estructurado.
binary	Contenido binario.
enum	Un conjunto cerrado de valores, definido ahí mismo — ver Relaciones y enums.

#Claves primarias

La Clave primaria (PK) es lo que identifica un registro. No es opcional en la práctica: sin PK, una tabla puede leerse pero no puede editarse ni eliminarse desde las pantallas — la Tabla avisa El datastore necesita una clave primaria, y el Kanban desactiva el arrastre. Si la clave se compone de más de una columna, activa Clave primaria (PK) en cada una.

El Autoincremento le entrega al motor el trabajo de numerar. Solo tiene sentido en columnas enteras.

#Traer una tabla al modelo

Una tabla que ya exista en la base de datos (creada por ti aquí, o que ya estaba antes) tiene que entrar en el modelo para que las APIs y las pantallas la vean. Hay dos caminos, y son lo mismo:

• Arrastrar la tabla del árbol al diagrama — cae en el sitio donde la sueltes.
• Abrir el menú ⋯ de la tabla y elegir Importar al modelo.

La plataforma lee la estructura de la tabla y crea la entidad: un nombre con mayúscula inicial (contas → Contas), los campos, las claves y las relaciones que encuentre declaradas en la base de datos.

La importación lee también si cada columna tiene valor por omisión en la base de datos, o si la genera la base (una identidad, una columna calculada): esos campos no son obligatorios en los formularios ni en las APIs, y se quedan con el valor de la base cuando no se envían. Las entidades importadas antes de existir esta información las pone al día la actualización de la plataforma, que lee el catálogo de todas las bases de datos que consigue contactar, en todas las apps y versiones (un commit por versión, «Valor por omissão das colunas lido da base de dados»); una base sin respuesta en ese momento queda para la actualización siguiente, o para el comando pnpm model:refresh-defaults en la máquina de la plataforma. Volver a importar la tabla (arrastrar, o Importar al modelo) hace lo mismo para una entidad.

Una clave entera de 64 bits (bigint, o un NUMBER ancho en Oracle), primaria o foránea, entra en el modelo como ID: viaja como texto, y un id por encima de 9 007 199 254 740 991 llega exacto, algo que un número no garantizaba. Un ID se filtra con eq, neq, in y nin. Un bigint que no es clave sigue siendo número, y las entidades ya importadas conservan el tipo que tenían.

Los nombres de las relaciones importadas nunca repiten el de una columna ni el de otra relación: una columna cliente que apunta a la tabla cliente da la relación clienteRel, y dos claves a la misma tabla reciben nombres tomados de las columnas (moradaEntrega, moradaFaturacao). Crear a mano una relación con un nombre ya usado se rechaza.

#La tarjeta de una entidad

Cada entidad es una tarjeta en el diagrama:

• El nombre de la entidad en la cabecera, y dos botones: Localizar en el árbol (marca la tabla correspondiente en la barra lateral) y Quitar del modelo.
• Un campo por fila, con el nombre a la izquierda y el tipo a la derecha. La marca PK señala la clave primaria, y un ! después del tipo significa que el campo no acepta vacío.
• Los campos enumerados aparecen en cursiva, con el nombre del enum en vez del tipo.
• Con muchos campos, la tarjeta se encoge y ofrece Mostrar N campos más / Mostrar menos.
• Al fondo, la sección Navegación lista los caminos hacia las entidades relacionadas — asunto de Relaciones y enums.

#Cambiar una tabla

El menú ⋯ de una tabla → Editar estructura abre el editor de la estructura, con dos pestañas: Columnas e Índices (N).

Arriba están las tres cosas que describen la tabla:

Campo	Qué es
Nombre en la BD	El nombre real de la tabla.
Nombre amigable (apps)	El nombre por el que la tabla es conocida en la app.
Descripción de la tabla	Para qué sirve.

El Nombre amigable (apps) es el puente entre una base de datos heredada y una app legible: la columna puede llamarse cli_nm_fis en la base de datos y nome en la app. También existe por columna — y es el nombre amigable el que aparece en las APIs, en los datastores y en las pantallas.

Cambiar el Nombre amigable (apps) de una columna actualiza las API de tabla que la eligen y las reglas de datos de los permisos que la usan. Las pantallas y los informes que ya piden el campo por el nombre antiguo no cambian solos: revísalos después de cambiar el nombre.

#Tocar las columnas

Haz clic en una columna de la lista de la izquierda para editarla. Los cambios no son inmediatos: se acumulan y solo ocurren cuando pulsas Aplicar cambios.

• Una columna añadida con + aparece marcada como nueva y trae la nota Columna nueva — se crea al aplicar los cambios.
• Eliminar una columna existente (la papelera al final de la fila) la tacha y muestra Marcada para eliminar (DROP) al aplicar; Anular lo deshace.
• Si no hay nada que aplicar, la plataforma dice Sin cambios.

#Índices

La pestaña Índices (N) lista los índices de la tabla — nombre, marca unique y las columnas — y permite crear y eliminar.

Para crear un índice:

1. Escribe el nombre (la convención ix_alguna_cosa es buena y es la que el campo sugiere).
2. Marca unique si el índice también sirve para impedir valores repetidos — así se garantiza que no hay dos clientes con el mismo NIF.
3. Haz clic en las columnas que forman parte del índice (el orden en que haces clic es el orden del índice).
4. Crear índice.

Una tabla sin índices propios dice Sin índices (además de la PK) — la clave primaria ya es un índice, no hace falta crearla.

#Ver los datos

El menú ⋯ de una tabla → Ver datos abre la consola SQL abajo, ya con la consulta hecha y el resultado a la vista. Es la forma rápida de confirmar lo que hay sin salir del modelo.

La consola también acepta SQL escrito por ti: escribe a la izquierda, Ejecutar, y el resultado aparece a la derecha con el recuento de filas. La barra que separa la consola del diagrama se arrastra, y la flecha de la esquina la recoge.

#Eliminar una tabla

El menú ⋯ de una tabla tiene Eliminar, con confirmación: Esta operación es permanente y quita el objeto de la base de datos. No confundir con Quitar del modelo, que solo saca la entidad de la descripción de la app.

#¿Por qué no…?

• ¿Por qué no veo mi tabla en las APIs? Probablemente aún no está en el modelo. Arrástrala del árbol al diagrama, o usa Importar al modelo.
• ¿Por qué creé una columna y no aparece? Confirma que pulsaste Aplicar cambios — en el editor de estructura, nada pasa antes de eso.
• ¿Por qué mi tabla nueva no deja editar registros en las pantallas? Falta la Clave primaria (PK). Sin ella, las pantallas solo saben leer.
• ¿Por qué no puedo cambiar el tipo de una columna? Hay motores sin «alterar columna». La plataforma te avisa y el camino es columna nueva → copiar datos → eliminar la vieja.
• ¿Por qué el nombre del campo en la app no es el de la base de datos? Está definido el Nombre amigable (apps) de esa columna. Es a propósito — y se edita en el mismo sitio.
• ¿Por qué desapareció la entidad del diagrama pero la tabla sigue en el árbol? Fue quitada del modelo. Arrástrala otra vez del árbol al diagrama.