Propiedades
Descripción general
Sección titulada «Descripción general»Las propiedades definen las columnas en la tabla de su base de datos y cómo se renderizan en la UI de administración. Cada propiedad tiene un type que determina:
- El tipo de columna de base de datos (mediante la generación de esquemas de Drizzle)
- El componente de campo de formulario
- El renderizador de celda de tabla
- Las reglas de validación
Tipos de propiedades
Sección titulada «Tipos de propiedades»| Tipo | Descripción | Columna de PostgreSQL |
|---|---|---|
string |
Texto, select, markdown, subida de archivos, URL, correo electrónico | text por defecto; varchar, char o uuid con columnType |
number |
Entero, decimal, moneda | integer, numeric, bigint, serial |
boolean |
Selector booleano (verdadero/falso) | boolean |
date |
Fecha, fecha y hora, marca de tiempo | timestamp, date |
array |
Lista ordenada de valores | Un array nativo (text[], integer[], numeric[], boolean[]) cuando of es una sola propiedad string, number o boolean; jsonb en caso contrario |
map |
Objeto clave-valor | jsonb |
geopoint |
Par latitud/longitud | jsonb |
reference |
Referencia incrustada a otra entidad | El tipo de la clave primaria del destino (almacena su ID) |
relation |
Relación de clave foránea SQL | Utiliza el array relations |
vector |
Embedding, para búsqueda de vecinos más cercanos | VECTOR(n) (pgvector) |
binary |
Bytes en bruto, leídos y escritos en base64 | bytea |
Propiedades comunes
Sección titulada «Propiedades comunes»Todos los tipos de propiedades comparten estas opciones:
| Propiedad | Tipo | Descripción |
|---|---|---|
type |
string |
Requerido. Tipo de dato (ver arriba) |
name |
string |
Etiqueta visible. Por defecto toma la clave de la propiedad, formateada de manera legible — publishDate → “Publish Date”. Establézcala cuando dicha derivación no sea la deseada: "URL" en lugar de “Url”. |
description |
string |
Texto de ayuda mostrado debajo del campo |
defaultValue |
any |
Valor por defecto para nuevas entidades. Un valor literal — una cadena, número, booleano, fecha, id de enum o un documento map/array — también se convierte en el DEFAULT de la columna, por lo que una fila insertada por cualquier medio ajeno al panel de administración (la API REST, un seed, psql) también lo recibe |
databaseDefault |
boolean | SqlExpression |
La base de datos rellena la columna cuando una creación la deja vacía: una columna NOT NULL DEFAULT <expression> como gen_random_uuid() o nextval(…). Un campo required con ella puede omitirse en una creación, tanto en el formulario del panel como en la API, y un null enviado al crear se deja a la base de datos; sigue siendo obligatorio al editar, y el tipo Insert generado la hace opcional. Da la expresión en la forma de plantilla que acepta isId, databaseDefault: "sql`gen_random_uuid()`", y el planificador de esquemas la escribe como el DEFAULT de la columna, de modo que rebase db push la conserva. true declara un DEFAULT escrito en otro lugar y no escribe ninguno, así que un push planifica eliminarlo. “Importar desde tabla” y rebase schema introspect establecen la expresión que leen |
validation |
object |
Reglas de validación |
propertyConfig |
string |
Clave de configuración de propiedad registrada |
columnName |
string |
Nombre explícito de la columna en la base de datos (omite la conversión a snake_case) |
callbacks |
PropertyCallbacks |
Hooks para transformaciones afterRead y beforeSave |
excludeFromApi |
boolean |
Nunca expone esta columna en la API, en ninguna dirección — para un hash de contraseña o un token de verificación. El valor se sigue escribiendo y se puede consultar en el servidor; se elimina de cada fila que sirve la API, para cualquier solicitante, incluidos administradores y claves de servicio, y no está presente en los tipos generados Row, Insert y Update ni en el esquema OpenAPI. Azúcar sintáctico para access: { read: [], write: [] } — ambos son el mismo mecanismo, y definir ambos en una misma propiedad será rechazado al iniciar |
access |
{ read?: string[]; write?: string[] } |
Quién puede leer y quién puede escribir este campo específico, por rol. Omitir la lista delega en las reglas de seguridad de la fila; [] significa nadie a través de la API; una lista de roles representa esos roles más admin. Un campo no legible está ausente de las respuestas en lugar de ser null, y una escritura que intente modificar uno no escribible devuelve un error 400. Consulte Acceso a campos |
metadata |
Record<string, unknown> |
Cualquier dato que su propio código necesite asociar a una propiedad. Rebase no lo lee; se mantiene intacto tras la serialización |
dynamicProps |
function |
Generador de propiedades dinámicas (consulte Campos condicionales). Solo para el formulario de administración — no se aplica en la API ni en la base de datos. |
conditions |
PropertyConditions |
Condiciones declarativas de JSON Logic. Solo para el formulario de administración — no se aplica en la API ni en la base de datos. |
Configuración de la interfaz de usuario (admin)
Sección titulada «Configuración de la interfaz de usuario (admin)»Las opciones relacionadas con la UI se anidan bajo el subobjeto admin:
price: { type: "number", name: "Price", admin: { readOnly: true, columnWidth: 120, hideFromCollection: false }}| Propiedad | Tipo | Descripción |
|---|---|---|
admin.readOnly |
boolean |
Evitar la edición |
admin.disabled |
boolean | PropertyDisabledConfig |
Deshabilitar con tooltip opcional |
admin.filledByServer |
boolean |
El servidor rellena el campo cuando un registro nuevo lo deja vacío (un hook beforeSave). El formulario permite crear sin él; sigue siendo obligatorio al editar, y las propias comprobaciones del servidor siguen aplicándose |
admin.hideFromCollection |
boolean |
Ocultar de la vista de tabla. Solo afecta a la presentación: las filas relacionadas de una propiedad de relación oculta siguen incrustadas en la lectura del listado (véase Relaciones) |
admin.columnWidth |
number |
Ancho de columna en píxeles (vista de tabla) |
admin.span |
1 | 2 | 3 | 4 |
Ancho del campo en la cuadrícula de formulario de cuatro columnas |
admin.Field |
React.ComponentType |
Componente de campo personalizado |
admin.Preview |
React.ComponentType |
Componente de celda de tabla personalizado |
admin.Filter |
React.ComponentType |
Campo de filtro personalizado para esta propiedad. Prevalece sobre la sobreescritura a nivel de colección Collection.FilterField y el campo integrado por tipo |
admin.filterOperators |
WhereFilterOp[] |
Restringe los operadores disponibles al filtrar por esta propiedad. El conjunto ofrecido es la intersección de las capacidades del motor, los valores predeterminados del tipo y esta lista — solo puede restringir, nunca agregar un operador que el motor no pueda ejecutar. [] deshabilita el filtrado en la propiedad |
admin.customProps |
unknown |
Cualquier elemento que su propio Field o Preview necesite. Rebase lo transfiere sin modificaciones |
PropertyDisabledConfig
Sección titulada «PropertyDisabledConfig»La forma de objeto de admin.disabled. El control permanece visible y deshabilitado en gris, que es la diferencia con admin.readOnly — el usuario puede ver la forma de lo que no tiene permitido rellenar.
| Propiedad | Tipo | Descripción |
|---|---|---|
disabledMessage |
string |
Razón por la cual esta propiedad está deshabilitada, mostrada al usuario. Sin ella, un control deshabilitado en gris no explica nada |
clearOnDisabled |
boolean |
Establece el valor en null cuando la propiedad pasa a estar deshabilitada, de modo que no se guarde una respuesta obsoleta con la entidad |
hidden |
boolean |
Oculta el campo por completo mientras está deshabilitado, en lugar de mostrarlo en gris |
Propiedades de tipo String
Sección titulada «Propiedades de tipo String»El tipo string es el más versátil — según las opciones configuradas, se renderiza en distintos widgets.
Campo de texto
Sección titulada «Campo de texto»Una entrada de texto básica de una sola línea.
name: { type: "string", name: "Name", validation: { required: true, min: 2, max: 200 }}Texto multilínea
Sección titulada «Texto multilínea»Configure admin.multiline para renderizar como un área de texto (textarea). Modifica cómo se dibuja el campo, no lo que contiene la columna, por lo que reside en el bloque admin junto con el resto de las opciones de presentación.
description: { type: "string", name: "Description", admin: { multiline: true }}Editor de Markdown
Sección titulada «Editor de Markdown»Configure admin.markdown para renderizar un editor de Markdown completo con barra de herramientas.
body: { type: "string", name: "Blog text", admin: { markdown: true }}Campo de correo electrónico
Sección titulada «Campo de correo electrónico»Configure email: true para agregar validación de formato de correo electrónico y renderizar con un icono de correo.
email: { type: "string", name: "User email", email: true, validation: { required: true }}Campo de URL
Sección titulada «Campo de URL»Configure url: true para agregar validación de formato de URL y renderizar con un icono de enlace.
website: { type: "string", name: "Amazon link", url: true}Subida de archivos
Sección titulada «Subida de archivos»Configure storage para renderizar una zona de soltar archivos (dropzone). La columna sigue siendo un string — lo que se escribe en ella es la clave del objeto en el bucket:
avatar: { type: "string", name: "Main image", storage: { storagePath: "avatars", acceptedFiles: ["image/*"] }}Todas las opciones dentro de storage, y la variante de múltiples archivos del mismo campo, se encuentran en Subida de archivos.
Select (enum)
Sección titulada «Select (enum)»Configure enum para renderizar un menú desplegable de selección. Consulte Valores de enum para obtener más detalles.
category: { type: "string", name: "Category", enum: [ { id: "electronics", label: "Electronics", color: "blueDark" }, { id: "clothing", label: "Clothing", color: "pink" }, ]}Selección múltiple
Sección titulada «Selección múltiple»Varios valores de un conjunto fijo es un array de un enum string, no un indicador sobre uno solo: la columna contiene múltiples valores, por lo que la propiedad que la describe es el array. Es una sola columna de Postgres, un text[], en lugar de un join: un array cuyo of es una sola propiedad string obtiene un array nativo por defecto, y el columnType de abajo solo lo indica de forma explícita.
locales: { type: "array", name: "Available locales", columnType: "text[]", of: { type: "string", name: "Locale", enum: [ { id: "es", label: "Spanish", color: "pink" }, { id: "en", label: "English", color: "blueLight" }, { id: "fr", label: "French", color: "purpleLight" }, ] }}Opciones de String
Sección titulada «Opciones de String»| Propiedad | Tipo | Descripción |
|---|---|---|
admin.multiline |
boolean |
Renderizar como textarea |
admin.markdown |
boolean |
Renderizar como editor de markdown |
email |
boolean |
Validación de formato de correo electrónico |
url |
boolean |
Validación de formato de URL |
storage |
StorageConfig |
Habilitar subida de archivos — consulte Subida de archivos |
enum |
EnumValues |
Renderizar como menú desplegable de selección |
columnType |
"varchar" | "text" | "char" | "uuid" |
La columna de base de datos. Por defecto es text, o uuid si isId así lo indica. text para cadenas ilimitadas, char para ancho fijo |
isId |
boolean | string |
Marca la propiedad como clave primaria y define quién la genera: "manual" (usted), "uuid" (gen_random_uuid()), o cualquier otra cadena de texto, utilizada literalmente como la expresión de SQL default de la columna — directa (nanoid()) o en formato plantilla ("sql`nanoid()`"). La función debe existir; nada aquí la crea. "increment" es una estrategia para number y no hace nada aquí, y "cuid" es rechazada al cargar la configuración |
autoValue |
"user_on_create" | "user_on_update" |
Asigna automáticamente a la columna el uid del usuario activo — solo en la creación o en cada escritura. Consulte Columnas de auditoría |
userSelect |
boolean |
Renderizar como selector de usuarios. El valor es una columna de texto simple que almacena el id del usuario — nada lo resuelve ni lo valida en la entrada. Solo para el formulario de administración — no se aplica en la API ni en la base de datos. El selector muestra los nombres, correos y avatares de los usuarios a cualquiera que pueda escribir en la colección, mediante GET /api/admin/users/pick, sin el alcance users:read. Una colección cuyas reglas de escritura son SQL en bruto no cuenta, ya que no se pueden juzgar de antemano: ahí solo pueden elegir quienes tengan users:read. |
admin.previewAsTag |
boolean |
Renderizar esta cadena como una etiqueta (tag) en las vistas previas |
admin.clearable |
boolean |
Agregar un icono para borrar el valor (establecer en null) |
admin.urlPreview |
PreviewType |
Cómo renderizar una cadena que contiene una URL: un enlace o una vista previa insertada de imagen, audio o video. Solo presentación — que el valor sea una URL depende del flag url en la propiedad, a partir del cual se genera el contrato OpenAPI |
Columnas de auditoría
Sección titulada «Columnas de auditoría»autoValue en un string es el equivalente de created_by / updated_by de la misma opción en una fecha:
createdBy: { type: "string", name: "Created by", autoValue: "user_on_create", admin: { readOnly: true }},
updatedBy: { type: "string", name: "Updated by", autoValue: "user_on_update"}El valor proviene del contexto de la llamada, nunca del cuerpo de la petición — el controlador sobrescribe cualquier valor recibido, por lo que quien llama no puede hacerse pasar por otra persona enviando el campo. Una columna cuyo valor es proporcionado por el remitente no es una columna de auditoría.
Sin un usuario activo —una petición anónima, un token de servicio, un script de seed— la columna se establece en null. Si se combina con validation: { required: true }, se convierte en un error 400: una colección que exige saber quién escribió una fila es una colección que no puede aceptar escrituras anónimas.
No hay clave foránea. El uid es una cadena de texto, el almacén de usuarios puede ser una base de datos completamente distinta y un usuario eliminado no debe llevarse consigo el registro de auditoría — declare una relación si desea realizar el join.
Propiedades de tipo Number
Sección titulada «Propiedades de tipo Number»price: { type: "number", name: "Price", validation: { required: true, min: 0 }}
quantity: { type: "number", name: "Quantity", columnType: "integer" // Store as integer}Los campos numéricos se renderizan como una entrada de texto estándar con validación numérica.
Opciones de Number
Sección titulada «Opciones de Number»| Propiedad | Tipo | Descripción |
|---|---|---|
enum |
EnumValues |
Renderizar como select con valores numéricos. A diferencia de un enum de texto, esto no crea ningún tipo enum en Postgres — la columna sigue siendo NUMERIC o INTEGER, por lo que el panel ofrece los valores pero la base de datos no los restringe |
columnType |
string |
"integer", "real", "double precision", "numeric", "bigint", "serial", "bigserial". Por defecto es integer cuando validation.integer o isId indiquen que el valor es entero, y numeric en caso contrario |
precision / scale |
number |
Dígitos significativos totales y dígitos después del punto en una columna numeric — NUMERIC(10, 2). El dinero sin ellos es un NUMERIC sin límites que conserva lo que el emisor envíe, y no se puede restringir más adelante sin reescribir la columna |
isId |
boolean | string |
Marca la propiedad como clave primaria: "manual", "increment", o cualquier otra cadena utilizada literalmente como la expresión de SQL default de la columna. "increment" siempre es INTEGER GENERATED BY DEFAULT AS IDENTITY — si se especifica columnType junto a él, se ignorará con una advertencia, porque toda clave foránea que apunta a una clave numérica es INTEGER y una clave más amplia sería referenciada por columnas más estrechas |
admin.clearable |
boolean |
Agregar un icono para borrar el valor (establecer en null) |
admin.format |
NumberFormatOptions |
Muestra el número formateado como moneda, porcentaje o con decimales fijos. Si se omite, se renderiza el valor sin procesar — un número en la base de datos se muestra tal cual como el número en la base de datos |
NumberFormatOptions
Sección titulada «NumberFormatOptions»Solo para presentación. El valor almacenado nunca cambia — una visualización redondeada sigue siendo el número completo en la columna y en la API.
| Propiedad | Tipo | Descripción |
|---|---|---|
style |
"decimal" | "currency" | "percent" |
Por defecto es "decimal". "currency" requiere currency |
currency |
string |
Código ISO 4217 — "EUR", "USD". Definirlo implica style: "currency", por lo que el caso habitual requiere una sola clave |
locale |
string |
Etiqueta BCP 47. Por defecto toma la configuración regional del panel, lo que hace que una misma cantidad se lea 1,234.50 para un usuario y 1.234,50 para otro |
minimumFractionDigits |
number |
Rellenar con al menos esta cantidad de decimales — 2 escribe 5 como 5.00 |
maximumFractionDigits |
number |
Redondear como máximo a esta cantidad de decimales. No modifica el valor almacenado |
notation |
"standard" | "compact" |
"compact" renderiza 12000 como 12K. Útil en columnas de tabla estrechas |
Propiedades de tipo Boolean
Sección titulada «Propiedades de tipo Boolean»active: { type: "boolean", name: "Selectable", defaultValue: true}Los booleanos se renderizan como un interruptor de alternancia (toggle switch).
Propiedades de tipo Date
Sección titulada «Propiedades de tipo Date»Solo fecha
Sección titulada «Solo fecha»Configure mode: "date" para mostrar un selector de fecha sin hora.
event_date: { type: "date", name: "Expiry date", mode: "date"}Fecha y hora
Sección titulada «Fecha y hora»El modo por defecto "date_time" incluye tanto la fecha como la hora.
arrival_time: { type: "date", name: "Arrival time", mode: "date_time"}Marcas de tiempo automáticas
Sección titulada «Marcas de tiempo automáticas»Utilice autoValue para establecer automáticamente marcas de tiempo al crear o actualizar.
createdAt: { type: "date", name: "Created At", autoValue: "on_create", admin: { readOnly: true }}
updatedAt: { type: "date", name: "Updated At", autoValue: "on_update"}on_update es un trigger de base de datos, no solo una marca a nivel de aplicación. Rebase escribe la columna en cada guardado que realiza —de modo que un hook beforeSave ve el nuevo valor— e instala un trigger BEFORE UPDATE que la escribe para todos los demás. Sin el trigger, un script de seed, el backfill de una migración o una fila corregida en psql dejaban la columna indicando que la fila no había cambiado, y cualquier proceso que la leyera para decidir qué reindexar o reenviar ignoraba esa fila.
El trigger se genera en .rebase/sql/triggers.sql, aplicado por rebase db push y al iniciar por la verificación del esquema — Atlas no puede gestionarlo, por la misma razón que no puede gestionar las herramientas de búsqueda de texto completo (full-text search).
Opciones de Date
Sección titulada «Opciones de Date»| Propiedad | Tipo | Descripción |
|---|---|---|
mode |
"date" | "date_time" |
Solo fecha o fecha + hora (por defecto: "date_time"). Selecciona el widget; la columna es la misma en ambos casos. Solo para el formulario de administración — no se aplica en la API ni en la base de datos. |
autoValue |
"on_create" | "on_update" |
Establece marcas de tiempo automáticamente. on_create es un DEFAULT now(); on_update es un trigger BEFORE UPDATE además de una marca a nivel de aplicación, de modo que un UPDATE directo desde un seed o una migración también actualiza la columna |
columnType |
"timestamp" | "date" | "time" |
La columna de base de datos. Por defecto es timestamp con zona horaria. Una columna date se elige y se muestra como un día, diga lo que diga mode; una columna time como una hora del día sola, en UTC, sin día (viaja como esa hora el 1970-01-01) |
timezone |
string |
En qué zona horaria el selector lee y escribe el valor. Solo para el formulario de administración — no se aplica en la API ni en la base de datos. |
admin.clearable |
boolean |
Agregar un icono para borrar el valor (establecer en null) |
Propiedades de tipo Array y Map
Sección titulada «Propiedades de tipo Array y Map»Los dos tipos compuestos: una lista repetible y un objeto estructurado, ambos almacenados como JSONB a menos que encaje un array nativo de Postgres. Repeticiones, editores de bloques, grupos, editores clave-valor y todas las opciones que admite cualquiera de ellos se encuentran en Arrays y maps.
Propiedades de tipo Geopoint
Sección titulada «Propiedades de tipo Geopoint»Un par latitud/longitud, almacenado como jsonb — { latitude, longitude }, que es lo que describen el tipo TypeScript generado, el esquema OpenAPI y el campo del formulario.
location: { type: "geopoint", name: "Location"}Las escrituras adoptan la misma estructura, o un GeoPoint de @rebasepro/types: new GeoPoint(41.4036, 2.1744).
No hay opciones adicionales más allá de las que tiene cada propiedad. La columna no tiene un índice espacial y no existe un operador de distancia para filtrar: un geopoint es un valor que se almacena y se muestra, no uno por el cual se busca. Para eso, modele los dos números como columnas independientes.
Propiedades de tipo Reference
Sección titulada «Propiedades de tipo Reference»Las referencias vinculan a entidades en otra colección. Se renderizan como una tarjeta de vista previa que muestra los detalles de la entidad referenciada.
client: { type: "reference", name: "Related client", path: "clients", admin: { previewProperties: ["first_name", "last_name", "email"] }}En Postgres, una reference es una clave foránea como cualquier otra, por lo que sigue la misma regla ON DELETE que una relación belongsTo: opcional es SET NULL, requerida es RESTRICT. Consulte Relaciones.
Opciones de Reference y Relation
Sección titulada «Opciones de Reference y Relation»Estas se aplican tanto a las propiedades de tipo reference como a las de relation.
| Propiedad | Tipo | Descripción |
|---|---|---|
admin.fixedFilter |
FilterValues |
Filtra las entidades ofrecidas en el widget de selección |
admin.widget |
"select" | "dialog" |
Qué widget selecciona la entidad relacionada (solo relaciones) |
admin.includeId |
boolean |
Mostrar el id de la entidad relacionada en las vistas previas (por defecto: true) |
admin.includeEntityLink |
boolean |
Mostrar un enlace que abre la entidad relacionada (por defecto: true) |
admin.previewProperties |
string[] |
Cuáles de las propiedades del destino aparecen en la vista previa (máximo 3) |
admin.renderInForm |
boolean |
Renderiza una relación de tipo many (muchos) como un selector dentro del formulario, además de la pestaña que ya incluye. false por defecto: la vista de entidad ya lista las filas relacionadas en una pestaña, por lo que las dos superficies son redundantes por definición. No tiene efecto en una relación to-one (a uno), la cual no recibe pestaña |
Propiedades de tipo Vector
Sección titulada «Propiedades de tipo Vector»Una columna de embedding, para búsqueda de vecinos más cercanos. Solo para Postgres.
embedding: { type: "vector", name: "Embedding", dimensions: 1536}| Propiedad | Tipo | Descripción |
|---|---|---|
dimensions |
number |
Requerido. Longitud del vector. Se compila en VECTOR(n). |
index |
VectorIndexConfig | false |
Cómo se construye el índice ANN. Si se omite, se crea un índice HNSW para distancia de coseno. false no crea ninguno. |
Se crea un índice ANN junto con la columna, por lo que vectorSearch es aproximado y rápido en lugar de un escaneo exacto. Está construido para distancia de coseno, que es con lo que mide vectorSearch a menos que pase distance — un índice sirve exactamente para un operador, por lo que una consulta l2 contra un índice de coseno vuelve silenciosamente a un escaneo completo. method (hnsw o ivfflat), distance (uno o varios), m, efConstruction y lists se configuran en index. Por encima de 2000 dimensiones, pgvector no puede construir ningún tipo de índice, por lo que la columna se deja sin indexar y el inicio del sistema así lo indica.
Consúltelo con .vectorSearch(), que también cubre los requisitos de instalación de pgvector y cómo ajustar el índice. Para índices ordinarios btree, GIN y BRIN en cualquier colección, consulte Índices.
Propiedades de tipo Binary
Sección titulada «Propiedades de tipo Binary»Bytes en bruto, almacenados como bytea. Los valores se transmiten a través de la API como cadenas base64 — incluyendo defaultValue.
signature: { type: "binary", name: "Signature"}Los archivos grandes pertenecen al almacenamiento, no a una columna: un bytea se lee y se escribe completo, con la fila.
Los valores de enum, las reglas de validación y los campos condicionales tienen su propia página: Validación y condiciones.
Pasos siguientes
Sección titulada «Pasos siguientes»- Relaciones — Claves foráneas y joins
- Reglas de seguridad — Seguridad a nivel de fila (Row Level Security)
- Campos personalizados — Construya componentes de campo personalizados