Ir al contenido

Propiedades

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
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

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

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

El tipo string es el más versátil — según las opciones configuradas, se renderiza en distintos widgets.

Una entrada de texto básica de una sola línea.

name: {
type: "string",
name: "Name",
validation: { required: true, min: 2, max: 200 }
}

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 }
}

Configure admin.markdown para renderizar un editor de Markdown completo con barra de herramientas.

body: {
type: "string",
name: "Blog text",
admin: { markdown: true }
}

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 }
}

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
}

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.

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" },
]
}

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" },
]
}
}
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

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.

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.

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

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
active: {
type: "boolean",
name: "Selectable",
defaultValue: true
}

Los booleanos se renderizan como un interruptor de alternancia (toggle switch).

Configure mode: "date" para mostrar un selector de fecha sin hora.

event_date: {
type: "date",
name: "Expiry date",
mode: "date"
}

El modo por defecto "date_time" incluye tanto la fecha como la hora.

arrival_time: {
type: "date",
name: "Arrival time",
mode: "date_time"
}

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).

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)

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.

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.

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.

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

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.

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.