Salta ai contenuti
Rebase LogoRebase

Proprietà

Panoramica

Sezione intitolata “Panoramica”

Le proprietà definiscono le colonne nella tabella del database e la loro modalità di visualizzazione nell’interfaccia utente di amministrazione (admin UI). Ogni proprietà ha un type che determina:

  • Il tipo di colonna del database (tramite la generazione dello schema Drizzle)
  • Il componente del campo del modulo
  • Il renderer della cella della tabella
  • Le regole di validazione

Tipi di proprietà

Sezione intitolata “Tipi di proprietà”
Tipo Descrizione Colonna PostgreSQL
string Testo, select, markdown, caricamento file, URL, email text per impostazione predefinita; varchar, char o uuid con columnType
number Intero, decimale, valuta integer, numeric, bigint, serial
boolean Interruttore true/false boolean
date Data, data e ora, timestamp timestamp, date
array Elenco ordinato di valori Un array nativo (text[], integer[], numeric[], boolean[]) quando of è una sola proprietà string, number o boolean; altrimenti jsonb
map Oggetto chiave-valore jsonb
geopoint Coppia latitudine/longitudine jsonb
reference Riferimento incorporato a un’altra entità Il tipo della chiave primaria della destinazione (ne memorizza l’ID)
relation Relazione con chiave esterna SQL Utilizza l’array relations
vector Embedding, per la ricerca del vicino più prossimo VECTOR(n) (pgvector)
binary Byte grezzi, letti e scritti come base64 bytea

Proprietà comuni

Sezione intitolata “Proprietà comuni”

Tutti i tipi di proprietà condividono le seguenti opzioni:

Proprietà Tipo Descrizione
type string Obbligatorio. Tipo di dati (vedere sopra)
name string Etichetta visualizzata. Di default è la chiave della proprietà, formattata graficamente — publishDate → “Publish Date”. Impostala quando tale derivazione è errata: "URL" anziché “Url”.
description string Testo di aiuto mostrato sotto il campo
defaultValue any Valore predefinito per le nuove entità. Un valore letterale — una stringa, un numero, un booleano, una data, un ID di enum o un documento map/array — diventa anche il DEFAULT della colonna, quindi qualsiasi riga inserita da elementi esterni al pannello di amministrazione (l’API REST, un seed, psql) lo riceve a sua volta
databaseDefault boolean | SqlExpression Da 0.25 Il database riempie la colonna quando una creazione la lascia vuota: una colonna NOT NULL DEFAULT <expression> come gen_random_uuid() o nextval(…). Un campo required che lo ha può essere omesso da una creazione, sia dal form di amministrazione sia dall’API, e un null inviato in creazione viene lasciato al database; resta obbligatorio in modifica, e il tipo Insert generato lo rende facoltativo. Indica l’espressione nella forma template che accetta isId, databaseDefault: "sql`gen_random_uuid()`", e il planner dello schema la scrive come DEFAULT della colonna, così rebase db push la mantiene. true dichiara un DEFAULT scritto altrove e non ne scrive nessuno, quindi un push pianifica di eliminarlo. «Import from table» e rebase schema introspect impostano l’espressione che leggono
validation object Regole di validazione
propertyConfig string Chiave di configurazione della proprietà registrata
columnName string Nome esplicito della colonna del database (ignora la conversione in snake_case)
callbacks PropertyCallbacks Hook per le trasformazioni afterRead e beforeSave
excludeFromApi boolean Non menziona mai questa colonna a livello di superficie API, in nessuna direzione — utile per un hash di password o un token di verifica. Il valore viene comunque scritto ed è interrogabile lato server; viene rimosso da ogni riga restituita dall’API, per qualsiasi chiamante inclusi admin e service key, ed è assente dai tipi generati Row, Insert e Update e dallo schema OpenAPI. Sugar per access: { read: [], write: [] } — i due sono lo stesso meccanismo e l’impostazione di entrambi su una proprietà viene rifiutata all’avvio
access { read?: string[]; write?: string[] } Chi può leggere e chi può scrivere questo singolo campo, in base al ruolo. Se la lista viene omessa, delega alle regole di sicurezza della riga; [] indica nessun accesso tramite l’API; una lista di ruoli indica tali ruoli più admin. Un campo non leggibile è assente dalle risposte anziché null, e una scrittura che specifica un campo non scrivibile restituisce un errore 400. Vedere Accesso ai campi
metadata Record<string, unknown> Qualsiasi informazione aggiuntiva di cui il tuo codice ha bisogno per una proprietà. Rebase non la legge; viene preservata invariata durante la serializzazione
dynamicProps function Costruttore di proprietà dinamiche (vedere Campi condizionali). Solo per il modulo admin — non applicato dall’API o dal database.
conditions PropertyConditions Condizioni JSON Logic dichiarative. Solo per il modulo admin — non applicato dall’API o dal database.

Configurazione dell’interfaccia utente (admin)

Sezione intitolata “Configurazione dell’interfaccia utente (admin)”

Le opzioni relative all’interfaccia utente sono nidificate all’interno del sotto-oggetto admin:

price: {
    type: "number",
    name: "Price",
    admin: {
        readOnly: true,
        columnWidth: 120,
        hideFromCollection: false
    }
}
Proprietà Tipo Descrizione
admin.readOnly boolean Impedisce la modifica
admin.disabled boolean | PropertyDisabledConfig Disabilita con tooltip opzionale
admin.filledByServer boolean Il server compila il campo quando un nuovo record lo lascia vuoto (un hook beforeSave). Il modulo lascia passare una creazione senza di esso; resta obbligatorio in modifica, e i controlli del server si applicano comunque
admin.hideFromCollection boolean Nasconde dalla vista a tabella. Solo visualizzazione: le righe correlate di una proprietà di relazione nascosta vengono comunque incorporate nella lettura dell’elenco (vedi Relazioni)
admin.columnWidth number Larghezza della colonna in pixel (vista a tabella)
admin.span 1 | 2 | 3 | 4 Larghezza del campo sulla griglia del modulo a quattro colonne
admin.Field React.ComponentType Componente personalizzato per il campo
admin.Preview React.ComponentType Componente personalizzato per la cella della tabella
admin.Filter React.ComponentType Campo di filtro personalizzato per questa proprietà. Ha priorità sull’override di livello collection Collection.FilterField e sul campo integrato per tipo
admin.filterOperators WhereFilterOp[] Restringe gli operatori disponibili quando si filtra su questa proprietà. L’insieme disponibile è l’intersezione tra le capacità dell’engine, i valori predefiniti del tipo e questo elenco — puoi solo restringere, mai aggiungere un operatore che l’engine non è in grado di eseguire. [] disabilita il filtro sulla proprietà
admin.customProps unknown Qualsiasi elemento necessario ai tuoi componenti Field o Preview. Rebase lo passa invariato

PropertyDisabledConfig

Sezione intitolata “PropertyDisabledConfig”

La forma a oggetto di admin.disabled. Il controllo rimane visibile ma disattivato (in grigio), che è la differenza rispetto ad admin.readOnly — l’utente può vedere la struttura di ciò che non è autorizzato a compilare.

Proprietà Tipo Descrizione
disabledMessage string Motivo per cui questa proprietà è disabilitata, mostrato all’utente. Senza di esso un controllo disattivato non fornisce spiegazioni
clearOnDisabled boolean Imposta il valore a null quando la proprietà diventa disabilitata, in modo che un dato non più valido non venga salvato con l’entità
hidden boolean Nasconde completamente il campo mentre è disabilitato, anziché mostrarlo in grigio

Proprietà String

Sezione intitolata “Proprietà String”

Il tipo string è il più versatile: a seconda delle opzioni impostate, viene renderizzato con diversi widget.

Campo di testo

Sezione intitolata “Campo di testo”

Un input di testo standard a riga singola.

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

Testo multilinea

Sezione intitolata “Testo multilinea”

Imposta admin.multiline per eseguire il rendering come textarea. Modifica il modo in cui il campo viene visualizzato, non ciò che la colonna memorizza, quindi risiede nel blocco admin con il resto delle opzioni di presentazione.

description: {
    type: "string",
    name: "Description",
    admin: { multiline: true }
}

Editor Markdown

Sezione intitolata “Editor Markdown”

Imposta admin.markdown per eseguire il rendering di un editor markdown completo di barra degli strumenti.

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

Campo Email

Sezione intitolata “Campo Email”

Imposta email: true per aggiungere la validazione del formato email e visualizzare un’icona email.

email: {
    type: "string",
    name: "User email",
    email: true,
    validation: { required: true }
}

Campo URL

Sezione intitolata “Campo URL”

Imposta url: true per aggiungere la validazione del formato URL e visualizzare un’icona link.

website: {
    type: "string",
    name: "Amazon link",
    url: true
}

Caricamento file

Sezione intitolata “Caricamento file”

Imposta storage per eseguire il rendering di una dropzone per il caricamento dei file. La colonna rimane una stringa — ciò che viene salvato è la chiave dell’oggetto nel bucket:

avatar: {
    type: "string",
    name: "Main image",
    storage: { storagePath: "avatars", acceptedFiles: ["image/*"] }
}

Tutte le opzioni all’interno di storage, e la modalità multifile dello stesso campo, sono descritte in Caricamento file.

Select (enum)

Sezione intitolata “Select (enum)”

Imposta enum per eseguire il rendering di un menu a discesa select. Consulta Valori Enum per i dettagli.

category: {
    type: "string",
    name: "Category",
    enum: [
        { id: "electronics", label: "Electronics", color: "blueDark" },
        { id: "clothing", label: "Clothing", color: "pink" },
    ]
}

Selezione multipla

Sezione intitolata “Selezione multipla”

Più valori scelti da un set fisso rappresentano un array di stringhe enum, non un flag su una singola stringa: la colonna memorizza più valori, quindi la proprietà che la descrive è l’array. È una singola colonna Postgres, un text[], anziché una join: un array il cui of è una sola proprietà string ottiene per impostazione predefinita un array nativo, e il columnType qui sotto lo dice soltanto in modo esplicito.

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

Opzioni String

Sezione intitolata “Opzioni String”
Proprietà Tipo Descrizione
admin.multiline boolean Renderizza come textarea
admin.markdown boolean Renderizza come editor markdown
email boolean Validazione del formato email
url boolean Validazione del formato URL
storage StorageConfig Abilita il caricamento dei file — vedere Caricamento file
enum EnumValues Renderizza come menu a discesa select
columnType "varchar" | "text" | "char" | "uuid" La colonna del database. Il valore predefinito è text, o uuid se specificato da isId. text per stringhe a lunghezza illimitata, char per lunghezza fissa
isId boolean | string Contrassegna la proprietà come chiave primaria e stabilisce come viene popolata: "manual" (inserimento manuale), "uuid" (gen_random_uuid()), o qualsiasi altra stringa, usata letteralmente come espressione predefinita SQL della colonna — semplice (nanoid()) o in formato template ("sql`nanoid()`"). La funzione deve esistere; nulla qui provvede a crearla. "increment" è una strategia per valori di tipo number e qui non ha effetto, mentre "cuid" viene rifiutato durante il caricamento della configurazione
autoValue "user_on_create" | "user_on_update" Imposta nella colonna l’uid dell’utente corrente — solo alla creazione o a ogni scrittura. Vedere Colonne di audit
userSelect boolean Renderizza come selettore utente. Il valore è una normale colonna di tipo stringa contenente l’id utente — non viene risolto né verificato all’inserimento. Solo per il modulo admin — non applicato dall’API o dal database. Il selettore mostra nomi, email e avatar degli utenti a chiunque possa scrivere la collection, tramite GET /api/admin/users/pick, senza lo scope users:read. Una collection le cui regole di scrittura sono SQL grezzo non conta, perché non si possono valutare in anticipo: lì possono scegliere solo i titolari di users:read.
admin.previewAsTag boolean Renderizza questa stringa come tag nelle anteprime
admin.clearable boolean Aggiunge un’icona per cancellare il valore (impostandolo su null)
admin.urlPreview PreviewType Come visualizzare una stringa contenente un URL: un link o un’anteprima inline di immagine, audio o video. Solo a scopo di presentazione — il fatto che il valore sia effettivamente un URL è determinato dal flag url sulla proprietà, a partire dal quale viene generato il contratto OpenAPI

Colonne di audit

Sezione intitolata “Colonne di audit”

autoValue su una stringa è la controparte created_by / updated_by della stessa opzione disponibile per date:

createdBy: {
    type: "string",
    name: "Created by",
    autoValue: "user_on_create",
    admin: { readOnly: true }
},


updatedBy: {
    type: "string",
    name: "Updated by",
    autoValue: "user_on_update"
}

Il valore proviene dal contesto della chiamata, mai dal corpo della richiesta: il driver sovrascrive qualsiasi dato inviato, impedendo al chiamante di spacciarsi per un altro fornendo il campo. Una colonna il cui valore è fornito dal chiamante non è una colonna di audit.

In assenza di un utente attivo (richiesta anonima, token di servizio, script di seed), la colonna viene impostata a null. Abbinandola a validation: { required: true }, l’operazione restituirà invece un errore 400: una collection che richiede obbligatoriamente di sapere chi ha scritto una riga non può accettare scritture anonime.

Non è presente alcuna chiave esterna. L’uid è una stringa, l’archivio utenti potrebbe essere un database completamente separato e un utente eliminato non deve cancellare la traccia di audit — dichiara una relazione se desideri una join.

Proprietà Number

Sezione intitolata “Proprietà Number”
price: {
    type: "number",
    name: "Price",
    validation: { required: true, min: 0 }
}


quantity: {
    type: "number",
    name: "Quantity",
    columnType: "integer"  // Store as integer
}

I campi numerici vengono renderizzati come un normale input di testo con validazione numerica.

Opzioni Number

Sezione intitolata “Opzioni Number”
Proprietà Tipo Descrizione
enum EnumValues Renderizza come select con valori numerici. A differenza di un enum di stringhe, questo non crea alcun tipo enum Postgres — la colonna rimane NUMERIC o INTEGER, quindi il pannello offre i valori ma il database non ne impone il vincolo
columnType string "integer", "real", "double precision", "numeric", "bigint", "serial", "bigserial". Il valore predefinito è integer dove validation.integer o isId indicano un numero intero, altrimenti numeric
precision / scale number Cifre significative totali e cifre dopo la virgola su una colonna numeric — NUMERIC(10, 2). I valori monetari senza di essi sono memorizzati come NUMERIC illimitati che mantengono qualsiasi valore inviato dal chiamante, e non possono essere ristretti in seguito senza riscrivere la colonna
isId boolean | string Contrassegna la proprietà come chiave primaria: "manual", "increment", o qualsiasi altra stringa usata letteralmente come espressione predefinita SQL della colonna. "increment" è sempre INTEGER GENERATED BY DEFAULT AS IDENTITY — un columnType specificato contestualmente viene ignorato con un avviso, poiché ogni chiave esterna che punta a una chiave numerica è INTEGER e una chiave di tipo più ampio verrebbe referenziata da colonne più strette
admin.clearable boolean Aggiunge un’icona per cancellare il valore (impostandolo su null)
admin.format NumberFormatOptions Formatta il numero come valuta, percentuale o con decimali fissi. Se omesso, viene renderizzato il valore grezzo — un numero nel database viene mostrato esattamente come nel database

NumberFormatOptions

Sezione intitolata “NumberFormatOptions”

Solo per la presentazione. Il valore memorizzato non cambia mai: una visualizzazione arrotondata corrisponde comunque al numero completo nella colonna e nell’API.

Proprietà Tipo Descrizione
style "decimal" | "currency" | "percent" Valore predefinito: "decimal". "currency" richiede currency
currency string Codice ISO 4217 — "EUR", "USD". L’impostazione implica style: "currency", rendendo sufficiente una sola chiave per il caso d’uso comune
locale string Tag BCP 47. Il valore predefinito è il locale del pannello, motivo per cui lo stesso importo può apparire come 1,234.50 per un utente e 1.234,50 per un altro
minimumFractionDigits number Aggiunge zeri fino ad almeno questo numero di decimali — 2 mostra 5 come 5.00
maximumFractionDigits number Arrotonda al massimo a questo numero di decimali. Non modifica il valore memorizzato
notation "standard" | "compact" "compact" visualizza 12000 come 12K. Utile in una colonna di tabella stretta

Proprietà Boolean

Sezione intitolata “Proprietà Boolean”
active: {
    type: "boolean",
    name: "Selectable",
    defaultValue: true
}

I valori booleani vengono renderizzati come un interruttore (toggle switch).

Proprietà Date

Sezione intitolata “Proprietà Date”

Solo data

Sezione intitolata “Solo data”

Imposta mode: "date" per mostrare un selettore di data senza l’orario.

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

Data e ora

Sezione intitolata “Data e ora”

La modalità predefinita "date_time" include sia la data che l’ora.

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

Timestamp automatici

Sezione intitolata “Timestamp automatici”

Usa autoValue per impostare automaticamente i timestamp alla creazione o all’aggiornamento.

createdAt: {
    type: "date",
    name: "Created At",
    autoValue: "on_create",
    admin: { readOnly: true }
}


updatedAt: {
    type: "date",
    name: "Updated At",
    autoValue: "on_update"
}

on_update è un trigger del database, non solo una modifica a livello di applicazione. Rebase aggiorna la colonna a ogni salvataggio effettuato — così un hook beforeSave può vedere il nuovo valore — e installa un trigger BEFORE UPDATE che la aggiorna per qualsiasi altra operazione. Senza questo trigger, uno script di seed, un backfill di migrazione o una riga modificata manualmente in psql lascerebbero la colonna invariata, e qualsiasi processo che la legge per decidere cosa reindicizzare o reinviare salterebbe quella riga.

Il trigger viene generato in .rebase/sql/triggers.sql, applicato da rebase db push e all’avvio dalla sincronizzazione dello schema — Atlas non è in grado di gestirlo, per lo stesso motivo per cui non può gestire gli helper di ricerca full-text.

Opzioni Date

Sezione intitolata “Opzioni Date”
Proprietà Tipo Descrizione
mode "date" | "date_time" Solo data o data + ora (predefinito: "date_time"). Determina il widget; la colonna è identica in entrambi i casi. Solo per il modulo admin — non applicato dall’API o dal database.
autoValue "on_create" | "on_update" Timestamp automatici. on_create imposta un DEFAULT now(); on_update crea un trigger BEFORE UPDATE oltre a impostare il valore a livello di applicazione, in modo che anche un UPDATE diretto da un seed o da una migrazione aggiorni la colonna
columnType "timestamp" | "date" | "time" La colonna del database. Il valore predefinito è timestamp with time zone. Una colonna date viene scelta e mostrata come giorno, qualunque cosa dica mode; una colonna time come sola ora del giorno, in UTC, senza giorno (viaggia come quell’ora al 1970-01-01)
timezone string Il fuso orario in cui il selettore legge e scrive il valore. Solo per il modulo admin — non applicato dall’API o dal database.
admin.clearable boolean Aggiunge un’icona per cancellare il valore (impostandolo su null)

Proprietà Array e Map

Sezione intitolata “Proprietà Array e Map”

I due tipi compositi — un elenco ripetibile e un oggetto strutturato, entrambi memorizzati come JSONB a meno che non sia utilizzabile un array nativo di Postgres. Ripetizioni, editor a blocchi, gruppi, editor chiave-valore e tutte le opzioni accettate da ciascuno sono documentati in Array e map.

Proprietà Geopoint

Sezione intitolata “Proprietà Geopoint”

Una coppia latitudine/longitudine, memorizzata come jsonb — { latitude, longitude }, che è quanto descritto dal tipo TypeScript generato, dallo schema OpenAPI e dal campo del modulo.

location: {
    type: "geopoint",
    name: "Location"
}

Le operazioni di scrittura richiedono la stessa struttura, oppure un’istanza GeoPoint da @rebasepro/types: new GeoPoint(41.4036, 2.1744).

Non ci sono opzioni oltre a quelle comuni a ogni proprietà. La colonna non è indicizzata spazialmente e non è disponibile un operatore di distanza per il filtraggio: un geopoint è un valore da memorizzare e mostrare, non su cui eseguire ricerche. Per questo scopo, modella i due numeri come colonne separate.

Proprietà Reference

Sezione intitolata “Proprietà Reference”

I reference creano collegamenti a entità in un’altra collection. Vengono renderizzati come una card di anteprima che mostra i dettagli dell’entità referenziata.

client: {
    type: "reference",
    name: "Related client",
    path: "clients",
    admin: {
        previewProperties: ["first_name", "last_name", "email"]
    }
}

Su Postgres un reference è una chiave esterna a tutti gli effetti, pertanto segue la stessa regola ON DELETE di una relazione belongsTo: facoltativo corrisponde a SET NULL, obbligatorio corrisponde a RESTRICT. Vedere Relazioni.

Opzioni Reference e Relation

Sezione intitolata “Opzioni Reference e Relation”

Queste opzioni si applicano sia alle proprietà reference che relation.

Proprietà Tipo Descrizione
admin.fixedFilter FilterValues Filtra le entità disponibili nel widget di selezione
admin.widget "select" | "dialog" Quale widget seleziona l’entità correlata (solo relazioni)
admin.includeId boolean Mostra l’id dell’entità correlata nelle anteprime (predefinito: true)
admin.includeEntityLink boolean Mostra un link per aprire l’entità correlata (predefinito: true)
admin.previewProperties string[] Quali proprietà della destinazione mostrare nell’anteprima (massimo 3)
admin.renderInForm boolean Renderizza una relazione molti come selettore all’interno del modulo oltre che nella scheda già prevista. false per impostazione predefinita: la vista entità elenca già le righe correlate sotto forma di scheda, quindi le due visualizzazioni sarebbero ridondanti per impostazione predefinita. Nessun effetto su una relazione verso uno, che non riceve alcuna scheda

Proprietà Vector

Sezione intitolata “Proprietà Vector”

Una colonna per embedding, usata per la ricerca del vicino più prossimo (nearest-neighbour search). Solo per Postgres.

embedding: {
    type: "vector",
    name: "Embedding",
    dimensions: 1536
}
Proprietà Tipo Descrizione
dimensions number Obbligatorio. Lunghezza del vettore. Compila in VECTOR(n).
index VectorIndexConfig | false Come viene creato l’indice ANN. Se omesso, viene creato un indice HNSW per la distanza del coseno. false non ne crea alcuno.

Un indice ANN viene creato insieme alla colonna, garantendo che vectorSearch sia approssimata e veloce anziché una scansione esatta. È configurato per la distanza del coseno, che è la metrica utilizzata da vectorSearch a meno che non venga specificato distance — un indice supporta esattamente un solo operatore, quindi una query l2 eseguita su un indice di tipo coseno tornerà implicitamente a una scansione completa. I parametri method (hnsw o ivfflat), distance (uno o più), m, efConstruction e lists sono configurabili all’interno di index. Oltre le 2000 dimensioni pgvector non può creare alcun tipo di indice, pertanto la colonna viene lasciata senza indice e segnalata all’avvio.

Interrogala tramite .vectorSearch(), che illustra anche i requisiti per l’installazione di pgvector e l’ottimizzazione dell’indice. Per i normali indici btree, GIN e BRIN su qualsiasi collection, vedere Indici.

Proprietà Binary

Sezione intitolata “Proprietà Binary”

Byte grezzi, memorizzati come bytea. I valori transitano tramite l’API come stringhe base64 — incluso il defaultValue.

signature: {
    type: "binary",
    name: "Signature"
}

I file di grandi dimensioni devono essere gestiti nello storage, non in una colonna: un valore bytea viene letto e scritto interamente insieme alla riga.

I valori di enum, le regole di validazione e i campi condizionali sono descritti in dettaglio in una pagina dedicata: Validazione e condizioni.

Passaggi successivi

Sezione intitolata “Passaggi successivi”