Pular para o conteúdo
Rebase LogoRebase

Propriedades

Visão Geral

Seção intitulada “Visão Geral”

As propriedades definem as colunas na tabela do seu banco de dados e como elas são renderizadas na interface administrativa (UI). Cada propriedade possui um type que determina:

  • O tipo de coluna do banco de dados (via geração de schema do Drizzle)
  • O componente de campo de formulário
  • O renderizador de célula de tabela
  • As regras de validação

Tipos de Propriedade

Seção intitulada “Tipos de Propriedade”
Tipo Descrição Coluna PostgreSQL
string Texto, select, markdown, upload de arquivo, URL, e-mail text por padrão; varchar, char ou uuid com columnType
number Inteiro, decimal, moeda integer, numeric, bigint, serial
boolean Alternador verdadeiro/falso (toggle) boolean
date Data, data e hora (datetime), timestamp timestamp, date
array Lista ordenada de valores Um array nativo (text[], integer[], numeric[], boolean[]) quando of é uma única propriedade string, number ou boolean; jsonb caso contrário
map Objeto chave-valor jsonb
geopoint Par de latitude/longitude jsonb
reference Referência incorporada a outra entidade O tipo da chave primária do alvo (armazena seu ID)
relation Relação de chave estrangeira SQL Usa o array relations
vector Embedding, para busca de vizinho mais próximo VECTOR(n) (pgvector)
binary Bytes brutos, lidos e gravados como base64 bytea

Propriedades Comuns

Seção intitulada “Propriedades Comuns”

Todos os tipos de propriedade compartilham estas opções:

Propriedade Tipo Descrição
type string Obrigatório. Tipo de dados (veja acima)
name string Rótulo de exibição. O padrão é a chave da propriedade formatada amigavelmente — publishDate → “Publish Date”. Defina-o quando essa derivação estiver incorreta: "URL" em vez de “Url”.
description string Texto de ajuda exibido abaixo do campo
defaultValue any Valor padrão para novas entidades. Um valor literal — uma string, number, boolean, date, id de enum ou um documento map/array — também se torna o DEFAULT da coluna, portanto, uma linha inserida por qualquer coisa que não seja o painel de administração (a API REST, um seed, psql) também o recebe
databaseDefault boolean | SqlExpression Desde 0.25 O banco de dados preenche a coluna quando uma criação a deixa vazia: uma coluna NOT NULL DEFAULT <expression> como gen_random_uuid() ou nextval(…). Um campo required com ela pode ficar de fora de uma criação, tanto no formulário do admin quanto na API, e um null enviado na criação é deixado para o banco de dados; ele continua obrigatório na edição, e o tipo Insert gerado a torna opcional. Dê a expressão na forma de template que isId aceita, databaseDefault: "sql`gen_random_uuid()`", e o planejador de schema a escreve como o DEFAULT da coluna, de modo que rebase db push a mantém. true declara um DEFAULT escrito em outro lugar e não escreve nenhum, então um push planeja removê-lo. “Import from table” e rebase schema introspect definem a expressão que leem
validation object Regras de validação
propertyConfig string Chave de configuração de propriedade registrada
columnName string Nome explícito da coluna no banco de dados (ignora a conversão para snake_case)
callbacks PropertyCallbacks Hooks para transformações afterRead e beforeSave
excludeFromApi boolean Nunca menciona esta coluna na superfície da API, em nenhuma direção — para um hash de senha ou um token de verificação. O valor ainda é gravado e consultável no lado do servidor; ele é removido de cada linha retornada pela API, para todos os chamadores, incluindo admins e chaves de serviço, e fica ausente dos tipos gerados Row, Insert e Update e do schema OpenAPI. Atalho para access: { read: [], write: [] } — os dois são o mesmo mecanismo, e definir ambos em uma mesma propriedade é recusado na inicialização
access { read?: string[]; write?: string[] } Quem pode ler e quem pode gravar este campo específico, por função (role). Uma lista omitida delega para as regras de segurança da linha; [] significa ninguém através da API; uma lista de papéis representa esses papéis mais admin. Um campo ilegível fica ausente das respostas em vez de null, e uma gravação nomeando um campo não gravável retorna 400. Consulte Acesso ao campo
metadata Record<string, unknown> Qualquer coisa que seu próprio código precise associar a uma propriedade. O Rebase não faz a leitura; ele sobrevive à serialização sem alterações
dynamicProps function Construtor de propriedade dinâmica (consulte Campos condicionais). Apenas formulário administrativo — não imposto pela API ou pelo banco de dados.
conditions PropertyConditions Condições declarativas de JSON Logic. Apenas formulário administrativo — não imposto pela API ou pelo banco de dados.

Configuração de UI (admin)

Seção intitulada “Configuração de UI (admin)”

As opções relacionadas à interface do usuário ficam aninhadas no subobjeto admin:

price: {
    type: "number",
    name: "Price",
    admin: {
        readOnly: true,
        columnWidth: 120,
        hideFromCollection: false
    }
}
Propriedade Tipo Descrição
admin.readOnly boolean Impede a edição
admin.disabled boolean | PropertyDisabledConfig Desativa com tooltip opcional
admin.filledByServer boolean O servidor preenche o campo quando um novo registro o deixa vazio (um hook beforeSave). O formulário permite criar sem ele; permanece obrigatório na edição, e as próprias verificações do servidor continuam valendo
admin.hideFromCollection boolean Oculta da visualização em tabela. Apenas exibição: as linhas relacionadas de uma propriedade de relação oculta continuam embutidas na leitura de lista (veja Relações)
admin.columnWidth number Largura da coluna em pixels (visualização em tabela)
admin.span 1 | 2 | 3 | 4 Largura do campo na grade de formulário de quatro colunas
admin.Field React.ComponentType Componente de campo personalizado
admin.Preview React.ComponentType Componente de célula de tabela personalizado
admin.Filter React.ComponentType Campo de filtro personalizado para esta propriedade. Prevalece sobre a substituição de Collection.FilterField no nível da coleção e sobre o campo padrão embutido por tipo
admin.filterOperators WhereFilterOp[] Restringe os operadores oferecidos ao filtrar por esta propriedade. O conjunto oferecido é a interseção das capacidades do motor, dos padrões do tipo e desta lista — você só pode restringir, nunca adicionar um operador que o motor não consiga executar. [] desativa a filtragem na propriedade
admin.customProps unknown Qualquer coisa que seu próprio Field ou Preview precise. O Rebase repassa isso sem alterações

PropertyDisabledConfig

Seção intitulada “PropertyDisabledConfig”

O formato em objeto de admin.disabled. O controle permanece visível e esmaecido (cinza), o que é a diferença em relação a admin.readOnly — o leitor pode ver a estrutura do que não tem permissão para preencher.

Propriedade Tipo Descrição
disabledMessage string Motivo pelo qual esta propriedade está desativada, exibido ao leitor. Sem isso, um controle desativado não explica nada
clearOnDisabled boolean Define o valor como null quando a propriedade se torna desativada, para que uma resposta desatualizada não seja salva com a entidade
hidden boolean Oculta o campo completamente enquanto estiver desativado, em vez de esmaecê-lo

Propriedades String

Seção intitulada “Propriedades String”

O tipo string é o mais versátil — dependendo das opções definidas, ele é renderizado como diferentes widgets.

Campo de texto

Seção intitulada “Campo de texto”

Um campo de entrada de texto básico de linha única.

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

Texto multilinha

Seção intitulada “Texto multilinha”

Defina admin.multiline como true para renderizar como uma textarea. Isso altera como o campo é desenhado, não o que a coluna armazena, por isso fica no bloco admin junto com o restante das opções de apresentação.

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

Editor Markdown

Seção intitulada “Editor Markdown”

Defina admin.markdown como true para renderizar um editor markdown completo com barra de ferramentas.

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

Campo de e-mail

Seção intitulada “Campo de e-mail”

Defina email: true para adicionar validação de formato de e-mail e renderizar com um ícone de e-mail.

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

Campo de URL

Seção intitulada “Campo de URL”

Defina url: true para adicionar validação de formato de URL e renderizar com um ícone de link.

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

Upload de arquivo

Seção intitulada “Upload de arquivo”

Defina storage para renderizar uma área de soltar arquivos (dropzone). A coluna continua sendo uma string — o que é gravado nela é a chave do objeto no bucket:

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

Todas as opções dentro de storage e a versão de múltiplos arquivos do mesmo campo estão em Uploads de arquivos.

Select (enum)

Seção intitulada “Select (enum)”

Defina enum para renderizar um menu suspenso (select dropdown). Consulte Valores de Enum para obter detalhes.

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

Seleção múltipla (Multi-select)

Seção intitulada “Seleção múltipla (Multi-select)”

Vários valores de um conjunto fixo são representados como um array de uma string enum, e não uma flag em um único valor: a coluna armazena vários valores, portanto, a propriedade que a descreve é o array. É uma única coluna do Postgres, um text[], em vez de um join: um array cujo of é uma única propriedade string recebe um array nativo por padrão, e o columnType abaixo apenas diz isso explicitamente.

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

Opções de String

Seção intitulada “Opções de String”
Propriedade Tipo Descrição
admin.multiline boolean Renderiza como textarea
admin.markdown boolean Renderiza como editor markdown
email boolean Validação de formato de e-mail
url boolean Validação de formato de URL
storage StorageConfig Habilita o upload de arquivos — consulte Uploads de arquivos
enum EnumValues Renderiza como menu suspenso (select dropdown)
columnType "varchar" | "text" | "char" | "uuid" A coluna do banco de dados. O padrão é text, ou uuid quando isId assim definir. text para strings sem limite, char para tamanho fixo
isId boolean | string Marca a propriedade como a chave primária e especifica quem a preenche: "manual" (você), "uuid" (gen_random_uuid()) ou qualquer outra string, usada textualmente como a expressão padrão SQL da coluna — simples (nanoid()) ou em formato de template ("sql`nanoid()`"). A função precisa existir; nada aqui a cria. "increment" é uma estratégia de number e não faz nada aqui, e "cuid" é recusado no carregamento da configuração
autoValue "user_on_create" | "user_on_update" Grava na coluna o uid do usuário atuante — apenas na criação ou a cada gravação. Consulte Colunas de auditoria
userSelect boolean Renderiza como um seletor de usuário. O valor é uma coluna de string simples contendo o ID do usuário — nada o resolve ou verifica na entrada. Apenas formulário administrativo — não imposto pela API ou pelo banco de dados. O seletor lista nomes, e-mails e avatares de usuários para qualquer pessoa que possa escrever na coleção, por meio de GET /api/admin/users/pick, sem o escopo users:read. Uma coleção cujas regras de escrita são SQL bruto não conta, pois elas não podem ser avaliadas de antemão: nela só quem tem users:read pode escolher.
admin.previewAsTag boolean Renderiza esta string como uma tag nas pré-visualizações
admin.clearable boolean Adiciona um ícone para limpar o valor (definir como null)
admin.urlPreview PreviewType Como renderizar uma string que armazena uma URL: um link ou uma prévia inline de imagem, áudio ou vídeo. Apenas apresentação — se o valor é uma URL depende da flag url na propriedade, a partir da qual o contrato OpenAPI é gerado

Colunas de auditoria

Seção intitulada “Colunas de auditoria”

autoValue em uma string é o equivalente created_by / updated_by da mesma opção em uma date:

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


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

O valor vem do contexto da chamada, nunca do corpo da requisição — o driver sobrescreve o que quer que tenha chegado, de modo que um chamador não possa fingir ser outra pessoa enviando o campo. Uma coluna cujo valor é fornecido pelo chamador não é uma coluna de auditoria.

Sem nenhum usuário atuante — uma requisição anônima, um token de serviço, um script de seed — a coluna é definida como null. Combine isso com validation: { required: true } e isso se tornará um erro 400: uma coleção que exige saber quem gravou uma linha é uma coleção que não pode aceitar uma gravação anônima.

Não há chave estrangeira. O uid é uma string, o armazenamento de usuários pode ser outro banco de dados totalmente diferente, e um usuário excluído não deve levar a trilha de auditoria consigo — declare uma relação se quiser o join.

Propriedades Number

Seção intitulada “Propriedades Number”
price: {
    type: "number",
    name: "Price",
    validation: { required: true, min: 0 }
}


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

Campos numéricos são renderizados como uma entrada de texto padrão com validação numérica.

Opções de Number

Seção intitulada “Opções de Number”
Propriedade Tipo Descrição
enum EnumValues Renderiza como select com valores numéricos. Ao contrário de um enum de string, isso não cria nenhum tipo enum no Postgres — a coluna permanece NUMERIC ou INTEGER, de modo que o painel oferece os valores e o banco de dados não os impõe
columnType string "integer", "real", "double precision", "numeric", "bigint", "serial", "bigserial". O padrão é integer quando validation.integer ou isId indicam que o valor é inteiro, e numeric caso contrário
precision / scale number Total de dígitos significativos e dígitos após o ponto em uma coluna numeric — NUMERIC(10, 2). Valores monetários sem eles resultam em um NUMERIC ilimitado que mantém o que o chamador enviou, e não podem ser restringidos posteriormente sem reescrever a coluna
isId boolean | string Marca a propriedade como chave primária: "manual", "increment" ou qualquer outra string usada literalmente como a expressão SQL padrão da coluna. "increment" é sempre INTEGER GENERATED BY DEFAULT AS IDENTITY — columnType definido ao lado é ignorado, com um aviso, porque toda chave estrangeira apontando para uma chave numérica é INTEGER e uma chave mais ampla seria referenciada por colunas mais estreitas
admin.clearable boolean Adiciona um ícone para limpar o valor (definir como null)
admin.format NumberFormatOptions Exibe o número como moeda, porcentagem ou com casas decimais fixas. Se omitido, o valor bruto é renderizado — o número no banco de dados é mostrado exatamente como está no banco de dados

NumberFormatOptions

Seção intitulada “NumberFormatOptions”

Apenas apresentação. O valor armazenado nunca muda — uma exibição arredondada continua sendo o número completo na coluna e na API.

Propriedade Tipo Descrição
style "decimal" | "currency" | "percent" O padrão é "decimal". "currency" requer currency
currency string Código ISO 4217 — "EUR", "USD". Defini-lo implica style: "currency", de modo que o caso de uso comum requer apenas uma chave
locale string Tag BCP 47. O padrão é o locale do painel, que é o que faz com que a mesma quantia seja lida como 1,234.50 para um leitor e 1.234,50 para outro
minimumFractionDigits number Preenche com pelo menos este número de casas decimais — 2 exibe 5 como 5.00
maximumFractionDigits number Arredonda para no máximo este número de casas decimais. Não altera o valor armazenado
notation "standard" | "compact" "compact" renderiza 12000 como 12K. Útil em colunas estreitas de tabela

Propriedades Boolean

Seção intitulada “Propriedades Boolean”
active: {
    type: "boolean",
    name: "Selectable",
    defaultValue: true
}

Booleans são renderizados como um interruptor (toggle switch).

Propriedades Date

Seção intitulada “Propriedades Date”

Apenas data

Seção intitulada “Apenas data”

Defina mode: "date" para exibir um seletor de data sem horário.

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

Data e hora

Seção intitulada “Data e hora”

O modo padrão "date_time" inclui data e hora.

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

Timestamps automáticos

Seção intitulada “Timestamps automáticos”

Use autoValue para definir timestamps automaticamente na criação ou atualização.

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


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

on_update é um trigger de banco de dados, não apenas uma atribuição na camada da aplicação. O Rebase grava a coluna em cada salvamento que realiza — para que um hook beforeSave veja o novo valor — e instala um trigger BEFORE UPDATE que a atualiza para quaisquer outros acessos. Sem o trigger, um script de seed, um backfill de migração ou uma linha corrigida no psql deixaria a coluna indicando que a linha não havia sido alterada, e qualquer rotina lendo isso para decidir o que reindexar ou reenviar ignoraria essa linha.

O trigger é gerado em .rebase/sql/triggers.sql, aplicado por rebase db push e na inicialização pela verificação de schema — o Atlas não pode gerenciá-lo, pelo mesmo motivo que não pode gerenciar os utilitários de busca textual (full-text search).

Opções de Date

Seção intitulada “Opções de Date”
Propriedade Tipo Descrição
mode "date" | "date_time" Apenas data ou data + hora (padrão: "date_time"). Seleciona o widget; a coluna é a mesma em ambos os casos. Apenas formulário administrativo — não imposto pela API ou pelo banco de dados.
autoValue "on_create" | "on_update" Timestamps definidos automaticamente. on_create é um DEFAULT now(); on_update é um trigger BEFORE UPDATE bem como uma atribuição na camada de aplicação, de modo que um UPDATE direto de um seed ou migração também atualiza a coluna
columnType "timestamp" | "date" | "time" A coluna do banco de dados. O padrão é timestamp com fuso horário (with time zone). Uma coluna date é escolhida e exibida como um dia, diga o que disser mode; uma coluna time, apenas como uma hora do dia, em UTC, sem dia (ela trafega como essa hora em 1970-01-01)
timezone string Em qual fuso horário o seletor lê e grava o valor. Apenas formulário administrativo — não imposto pela API ou pelo banco de dados.
admin.clearable boolean Adiciona um ícone para limpar o valor (definir como null)

Propriedades Array e Map

Seção intitulada “Propriedades Array e Map”

Os dois tipos compostos — uma lista repetível e um objeto estruturado, ambos armazenados como JSONB, a menos que um array nativo do Postgres seja adequado. Repetições, editores de bloco, grupos, editores chave-valor e todas as opções aceitas por ambos estão em Arrays e maps.

Propriedades Geopoint

Seção intitulada “Propriedades Geopoint”

Um par latitude/longitude, armazenado como jsonb — { latitude, longitude }, que é o que o tipo TypeScript gerado, o schema OpenAPI e o campo de formulário descrevem.

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

As gravações seguem a mesma estrutura, ou um GeoPoint de @rebasepro/types: new GeoPoint(41.4036, 2.1744).

Não há opções além daquelas compartilhadas por todas as propriedades. A coluna não possui índice espacial e não há operador de distância para filtragem: um geopoint é um valor que você armazena e exibe, e não um pelo qual faz buscas. Para isso, modele os dois números como colunas separadas.

Propriedades Reference

Seção intitulada “Propriedades Reference”

Referências conectam entidades em outra coleção. Elas são renderizadas como um cartão de pré-visualização mostrando os detalhes da entidade referenciada.

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

No Postgres, uma reference é uma chave estrangeira como qualquer outra, portanto segue a mesma regra de ON DELETE de uma relação belongsTo: opcional é SET NULL, obrigatório é RESTRICT. Consulte Relações.

Opções de Reference e Relation

Seção intitulada “Opções de Reference e Relation”

Aplicam-se a propriedades reference e relation.

Propriedade Tipo Descrição
admin.fixedFilter FilterValues Filtra as entidades oferecidas no widget de seleção
admin.widget "select" | "dialog" Qual widget seleciona a entidade relacionada (apenas relações)
admin.includeId boolean Exibe o ID da entidade relacionada nas pré-visualizações (padrão: true)
admin.includeEntityLink boolean Exibe um link que abre a entidade relacionada (padrão: true)
admin.previewProperties string[] Quais propriedades do destino aparecem na pré-visualização (máx. 3)
admin.renderInForm boolean Renderiza uma relação do tipo many (muitos) como um seletor dentro do formulário, além da aba que ela já possui. false por padrão: a visualização da entidade já lista as linhas relacionadas em uma aba, tornando as duas superfícies redundantes por definição. Não tem efeito em relações to-one (para um), que não recebem abas

Propriedades Vector

Seção intitulada “Propriedades Vector”

Uma coluna de embedding, para busca de vizinho mais próximo. Apenas Postgres.

embedding: {
    type: "vector",
    name: "Embedding",
    dimensions: 1536
}
Propriedade Tipo Descrição
dimensions number Obrigatório. Tamanho do vetor. É compilado para VECTOR(n).
index VectorIndexConfig | false Como o índice ANN é construído. Se omitido, um índice HNSW para distância de cosseno. false não cria nenhum.

Um índice ANN é criado com a coluna, de modo que o vectorSearch seja aproximado e rápido em vez de realizar uma varredura exata. Ele é construído para a distância de cosseno, que é a métrica padrão do vectorSearch a menos que você passe distance — um índice atende a exatamente um operador, portanto, uma consulta l2 contra um índice de cosseno silenciosamente volta a realizar uma varredura completa. method (hnsw ou ivfflat), distance (um ou vários), m, efConstruction e lists são todos configurados em index. Acima de 2000 dimensões, o pgvector não consegue construir nenhum dos tipos de índice, portanto a coluna fica sem índice e a inicialização avisa sobre isso.

Consulte-a com .vectorSearch(), que também aborda os requisitos de instalação do pgvector e como ajustar o índice. Para índices comuns btree, GIN e BRIN em qualquer coleção, consulte Índices.

Propriedades Binary

Seção intitulada “Propriedades Binary”

Bytes brutos, armazenados como bytea. Os valores transitam pela API como strings base64 — incluindo defaultValue.

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

Arquivos grandes devem ficar no armazenamento (storage), e não em uma coluna: um bytea é lido e gravado por inteiro, junto com a linha.

Valores de enum, regras de validação e campos condicionais têm uma página dedicada: Validação e condições.

Próximos Passos

Seção intitulada “Próximos Passos”