Schemas de Entidade

As entidades são definidas usando um JSON Schema que descreve a estrutura dos dados e as regras de validação.

Estrutura básica do schema

Schemas de entidade são definidos em arquivos JSON no diretório de entidades do seu projeto. Por padrão, este é base44/entities/, mas você pode personalizar o caminho na configuração do seu projeto. O nome do arquivo determina o nome da entidade. Por exemplo, Task.json cria uma entidade Task. Aqui está um template de schema de entidade:

{
  "name": "my_entity",
  "type": "object",
  "title": "My Entity",
  "description": "Description of what this entity represents",
  "properties": {
    "<field_name>": {
      "type": "<field_type>",
      "<option>": "<value>"
    }
  },
  "required": ["<field_name>"]
}

Campos integrados

Cada registro de entidade inclui automaticamente os seguintes campos. Não defina campos com esses nomes no seu schema.

Campo	Tipo	Descrição
`id`	string	Identificador único do registro
`created_date`	datetime	Quando o registro foi criado
`updated_date`	datetime	Quando o registro foi atualizado pela última vez
`created_by`	string	E-mail do usuário que criou o registro
`created_by_id`	string	ID do usuário que criou o registro
`is_deleted` (interno)	boolean	Flag de soft delete
`deleted_date` (interno)	datetime	Quando o registro foi excluído
`is_sample` (interno)	boolean	Se o registro é dado de amostra
`entity_name` (interno)	string	Nome do tipo de entidade
`app_id` (interno)	string	ID do app
`environment` (interno)	string	Ou `prod` ou `dev`

Campos internos não são retornados nas respostas da API, mas podem ser referenciados em regras de segurança.

Campos do schema

string

Identificador em string para a entidade.

string

obrigatório

Deve ser "object".

string

Nome de exibição amigável ao usuário.

string

Descrição do que a entidade representa.

object

obrigatório

Objeto contendo suas definições de campo. Cada campo tem um type e regras de validação opcionais.

Tipos de campo

As entidades suportam vários tipos de campo para definir diferentes tipos de dados que você pode armazenar: string, integer, number, boolean, array e object. Cada campo dentro de properties requer um type. Com base no tipo, você pode adicionar opções de validação.

Campos string

Campos string suportam estas opções:

minLength / maxLength: Controla a contagem mínima e máxima de caracteres.
pattern: Expressão regular para validação customizada.
format: Formatos predefinidos. Valores suportados:
- "date"
- "date-time"
- "time"
- "email"
- "uri"
- "hostname"
- "ipv4"
- "ipv6"
- "uuid"
enum: Restrição a valores permitidos específicos. Defina como um array: ["value1", "value2", "value3"].
default: Valor padrão se nenhum for fornecido.

Campos integer

Campos integer suportam estas opções:

minimum / maximum: Define limites inferior/superior inclusivos.
default: Valor padrão se nenhum for fornecido.

Campos number

Campos number suportam estas opções:

minimum / maximum: Define limites inferior/superior inclusivos.
default: Valor padrão se nenhum for fornecido.

Campos boolean

Campos boolean suportam estas opções:

default: Valor padrão se nenhum for fornecido.

Campos array

Campos array suportam estas opções:

items: Define o tipo/schema para elementos do array.
default: Valor padrão do array se nenhum for fornecido.

Campos object

Campos object suportam estas opções:

properties: Define os campos dentro do objeto.
required: Lista de nomes de propriedade obrigatórios.

Campos obrigatórios

Especifique quais campos devem ser fornecidos:

{
  "required": ["title", "email"]
}

Unicidade

As entidades da Base44 não suportam restrições de unicidade. Uma propriedade que não faz parte do formato do schema, como unique_fields, é armazenada junto com seu schema e ignorada.

Para evitar registros duplicados, verifique em uma função de backend se já existe um registro antes de criar um novo. Uma verificação assim reduz a janela para duplicatas, mas não a fecha. Para garantir que apenas um usuário tenha sucesso, use o padrão de reivindicação em atualizações concorrentes.

Atualizações concorrentes

A Base44 não bloqueia registros nem executa transações entre vários registros. Quando 2 usuários ou processos alteram os mesmos dados ao mesmo tempo, cada escrita é aplicada de forma independente. Esta seção mostra quais atualizações são atômicas, como reivindicar um registro com segurança e o que esperar de chamadas que escrevem vários registros.

Reivindicando um registro com segurança

Para garantir que apenas um usuário possa reivindicar um registro existente, como uma tarefa ou um horário de reserva, chame updateMany() com o id desse único registro e as condições que ainda precisam ser verdadeiras. A atualização só é aplicada se essas condições ainda corresponderem no momento da escrita. Assim, quando 2 usuários tentam ao mesmo tempo, apenas um deles tem sucesso. Verifique updated na resposta para saber se a sua teve sucesso.

const result = await base44.entities.Task.updateMany(
  { id: taskId, status: "open" },
  { $set: { status: "claimed", claimed_by: user.email } }
);

if (result.updated === 1) {
  // This user claimed the task.
} else {
  // Someone else claimed it first, or it was no longer open.
}

As condições só são verificadas novamente no momento da escrita quando a consulta indica o id de um único registro como valor simples. Qualquer outra consulta, incluindo vários ids em $in ou $or, primeiro encontra os registros correspondentes e depois os atualiza. Por isso, um registro que mudou nesse intervalo ainda pode ser atualizado.

Escrevendo vários registros

bulkCreate(), bulkUpdate(), updateMany(), deleteMany() e upsert() não são transações. Cada registro é escrito de forma independente. Se uma chamada falhar no meio, os registros já escritos permanecem gravados. Projete essas chamadas para que seja seguro executá-las novamente, por exemplo, filtrando registros que já foram atualizados. Chamadas upsert() concorrentes com a mesma chave podem criar registros duplicados.

Exemplo completo

Aqui está um schema de entidade completo:

{
  "name": "Task",
  "type": "object",
  "title": "Task",
  "description": "A task item with priority, due date, and completion status",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "description": {
      "type": "string",
      "maxLength": 1000
    },
    "priority": {
      "type": "string",
      "enum": ["low", "medium", "high"],
      "default": "medium"
    },
    "completed": {
      "type": "boolean",
      "default": false
    },
    "due_date": {
      "type": "string",
      "format": "date"
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" }
    },
    "internal_notes": {
      "type": "string",
      "rls": {
        "read": {"user_condition": {"role": "admin"}},
        "write": {"user_condition": {"role": "admin"}}
      }
    }
  },
  "required": ["title"],
  "rls": {
    "create": true,
    "read": {"created_by": "{{user.email}}"},
    "update": {"created_by": "{{user.email}}"},
    "delete": {"created_by": "{{user.email}}"}
  }
}

Implantando entidades

Após definir seu schema de entidade, implante-o na Base44 usando entities push. As entidades também são implantadas automaticamente quando você executa o comando deploy para implantar todo o seu projeto. Uma vez implantadas, você pode interagir com suas entidades usando o módulo entities do SDK. O nome da entidade no seu schema deve corresponder exatamente a como você a acessa no SDK, incluindo capitalização. Por exemplo, se seu schema tem "name": "Task", você deve acessá-la como base44.entities.Task.list(). Schemas de entidade implantados podem ser visualizados no dashboard na seção Data.

Veja também

User Schema: Entidade integrada especial para autenticação de usuário
Segurança: Configure regras de segurança em nível de linha para entidades
Estrutura do projeto: Como schemas de entidade se encaixam no seu projeto

Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a versão em inglês.

Visão geral

Início rápido

Projeto

Ferramentas de Desenvolvimento com IA

Recursos

Estrutura básica do schema

Campos integrados

Campos do schema

Tipos de campo

Campos string

Campos integer

Campos number

Campos boolean

Campos array

Campos object

Campos obrigatórios

Unicidade

Atualizações concorrentes

Reivindicando um registro com segurança

Escrevendo vários registros

Exemplo completo

Implantando entidades

Veja também

​Estrutura básica do schema

​Campos integrados

​Campos do schema

​Tipos de campo

​Campos string

​Campos integer

​Campos number

​Campos boolean

​Campos array

​Campos object

​Campos obrigatórios

​Unicidade

​Atualizações concorrentes

​Reivindicando um registro com segurança

​Escrevendo vários registros

​Exemplo completo

​Implantando entidades

​Veja também

Estrutura básica do schema

Campos integrados

Campos do schema

Tipos de campo

Campos string

Campos integer

Campos number

Campos boolean

Campos array

Campos object

Campos obrigatórios

Unicidade

Atualizações concorrentes

Reivindicando um registro com segurança

Escrevendo vários registros

Exemplo completo

Implantando entidades

Veja também