Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a documentação para desenvolvedores.

Módulo Entities

Operações CRUD em modelos de dados. Acesse via base44.entities.EntityName.method().

Conteúdo

Métodos
Exemplos (Criar, Bulk Create, Listar, Filtrar, Obter, Atualizar, Excluir, Subscrever)
Entidade User
Acesso Service Role
Permissões

Métodos

Nota: O limite máximo para list() e filter() é 5.000 itens por solicitação.

Método	Assinatura	Descrição
`create(data)`	`Promise<T>`	Cria um registro
`bulkCreate(dataArray)`	`Promise<T[]>`	Cria vários registros
`list(sort?, limit?, skip?, fields?)`	`Promise<Pick<T, K>[]>`	Obtém todos os registros (paginado)
`filter(query, sort?, limit?, skip?, fields?)`	`Promise<Pick<T, K>[]>`	Obtém registros correspondentes às condições
`get(id)`	`Promise<T>`	Obtém um único registro pelo ID
`update(id, data)`	`Promise<T>`	Atualiza o registro (atualização parcial)
`updateMany(query, data)`	`Promise<UpdateManyResult>`	Atualiza todos os registros correspondentes usando operadores de atualização MongoDB
`bulkUpdate(dataArray)`	`Promise<T[]>`	Atualiza vários registros pelo ID, cada um com seus próprios dados
`delete(id)`	`Promise<DeleteResult>`	Exclui o registro pelo ID
`deleteMany(query)`	`Promise<DeleteManyResult>`	Exclui todos os registros correspondentes
`importEntities(file)`	`Promise<ImportResult<T>>`	Importa de CSV (apenas frontend)
`subscribe(callback)`	`() => void`	Assina atualizações em tempo real (retorna função de cancelamento)

Exemplos

Criar

const task = await base44.entities.Task.create({
  title: "Complete documentation",
  status: "pending",
  dueDate: "2024-12-31"
});

Bulk Create

const tasks = await base44.entities.Task.bulkCreate([
  { title: "Task 1", status: "pending" },
  { title: "Task 2", status: "pending" }
]);

Listar com paginação

// Get first 10 records, sorted by created_date descending (max 5,000 per request)
const tasks = await base44.entities.Task.list(
  "-created_date",  // sort (SortField: prefix with - for descending)
  10,               // limit
  0                 // skip
);

// Get next page
const page2 = await base44.entities.Task.list("-created_date", 10, 10);

Filtrar

// Simple filter
const pending = await base44.entities.Task.filter({ status: "pending" });

// Multiple conditions
const myPending = await base44.entities.Task.filter({
  status: "pending",
  assignedTo: userId
});

// With sort, limit, skip (max 5,000 per request)
const recent = await base44.entities.Task.filter(
  { status: "pending" },
  "-created_date",  // sort (SortField: prefix with - for descending)
  5,
  0
);

// Select specific fields
const titles = await base44.entities.Task.filter(
  { status: "pending" },
  null,
  null,
  null,
  ["id", "title"]
);

Obter por ID

const task = await base44.entities.Task.get("task-id-123");

Atualizar

// Partial update - only specified fields change
await base44.entities.Task.update("task-id-123", {
  status: "completed",
  completedAt: new Date().toISOString()
});

Excluir

// Single record
const result = await base44.entities.Task.delete("task-id-123");
console.log("Deleted:", result.success);

// Multiple records matching query
const manyResult = await base44.entities.Task.deleteMany({ status: "archived" });
console.log("Deleted:", manyResult.deleted);

Update Many (estilo MongoDB)

// Update all pending tasks to status "in-progress"
const result = await base44.entities.Task.updateMany(
  { status: "pending" },                     // query: which records to update
  { $set: { status: "in-progress" } }        // MongoDB update operator
);
console.log("Updated:", result.updated);

// Increment a counter field
await base44.entities.Task.updateMany(
  { category: "bugs" },
  { $inc: { priority: 1 } }
);

Bulk Update (por ID)

// Update multiple records, each with different data
const updated = await base44.entities.Task.bulkUpdate([
  { id: "task-1", status: "done", completedAt: new Date().toISOString() },
  { id: "task-2", status: "in-progress", assignedTo: userId },
  { id: "task-3", priority: 5 }
]);

Importar de arquivo

// Frontend only: import from CSV/file
const result = await base44.entities.Task.importEntities(file);
if (result.status === "success" && result.output) {
  console.log(`Imported ${result.output.length} records`);
} else {
  console.error(result.details);
}

Subscrever atualizações em tempo real

// Subscribe to all changes on Task entity
const unsubscribe = base44.entities.Task.subscribe((event) => {
  console.log(`Task ${event.id} was ${event.type}:`, event.data);
  // event.type is "create", "update", or "delete"
});

// Later: unsubscribe to stop receiving updates
unsubscribe();

Estrutura do evento:

{
  type: "create" | "update" | "delete",
  data: { ... },       // the entity data
  id: "entity-id",     // the affected entity's ID
  timestamp: "2024-01-15T10:30:00Z"
}

Entidade User

Cada aplicativo tem uma entidade User integrada com regras especiais:

Usuários regulares só podem ler/atualizar seu próprio registro
Não é possível criar usuários via entities.create() - use auth.register() em vez disso
Service role tem acesso total a todos os registros de usuários

// Get current user's record
const me = await base44.entities.User.get(currentUserId);

// Service role: get any user
const anyUser = await base44.asServiceRole.entities.User.get(userId);

Acesso Service Role

Para operações em nível de administrador (contornar permissões de usuário):

// Backend only
const allTasks = await base44.asServiceRole.entities.Task.list();
const allUsers = await base44.asServiceRole.entities.User.list();

Permissões (RLS e FLS)

O acesso a dados é controlado por regras Row Level Security (RLS) e Field Level Security (FLS) definidas nos schemas de entidade.

Nível de autenticação: anônimo, autenticado ou service role
Regras RLS: Controlam quais registros (linhas) os usuários podem criar/ler/atualizar/excluir
Regras FLS: Controlam quais campos os usuários podem ler/escrever em registros acessíveis

As operações têm sucesso ou falham com base nessas regras - sem resultados parciais. RLS e FLS são configurados em arquivos de schema de entidade (base44/entities/*.jsonc). Veja entities-create.md para detalhes de configuração. Nota: asServiceRole define a função do usuário como "admin" mas NÃO contorna o RLS. Suas regras RLS devem incluir acesso de administrador (por exemplo, { "user_condition": { "role": "admin" } }) para que as operações de service role tenham sucesso.

Definições de tipo

RealtimeEvent

/** Event types for realtime entity updates. */
type RealtimeEventType = "create" | "update" | "delete";

/** Payload received when a realtime event occurs. */
interface RealtimeEvent<T = any> {
  /** The type of change that occurred. */
  type: RealtimeEventType;
  /** The entity data. */
  data: T;
  /** The unique identifier of the affected entity. */
  id: string;
  /** ISO 8601 timestamp of when the event occurred. */
  timestamp: string;
}

/** Callback function invoked when a realtime event occurs. */
type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;

Tipos de resultado

/** Result returned when updating multiple entities. */
interface UpdateManyResult {
  /** Whether the update was successful. */
  success: boolean;
  /** Number of entities that were updated. */
  updated: number;
}

/** Result returned when deleting a single entity. */
interface DeleteResult {
  /** Whether the deletion was successful. */
  success: boolean;
}

/** Result returned when deleting multiple entities. */
interface DeleteManyResult {
  /** Whether the deletion was successful. */
  success: boolean;
  /** Number of entities that were deleted. */
  deleted: number;
}

/** Result returned when importing entities from a file. */
interface ImportResult<T = any> {
  /** Status of the import operation. */
  status: "success" | "error";
  /** Details message, e.g., "Successfully imported 3 entities with RLS enforcement". */
  details: string | null;
  /** Array of created entity objects when successful, or null on error. */
  output: T[] | null;
}

SortField e campos do servidor

/**
 * Sort field type for entity queries.
 * Supports ascending (no prefix or '+') and descending ('-') sorting.
 * Example: 'created_date', '+created_date', '-created_date'
 */
type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;

/** Fields added by the server to every entity record. */
interface ServerEntityFields {
  id: string;
  created_date: string;
  updated_date: string;
  created_by?: string | null;
  created_by_id?: string | null;
  is_sample?: boolean;
}

Registro de tipos (para entidades tipadas)

Como obter entidades tipadas: A CLI Base44 pode gerar interfaces de entidade e um aumento de EntityTypeRegistry do seu projeto. Para saber como executá-la, use a habilidade base44-cli.

/**
 * Registry mapping entity names to their TypeScript types.
 * Augment this interface with your entity schema (user-defined fields only).
 * Typically populated by the Base44 CLI type generator.
 */
interface EntityTypeRegistry {}

/**
 * Full record type for each entity: schema fields + server-injected fields.
 */
type EntityRecord = {
  [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
};

EntityHandler

/** Entity handler providing CRUD operations for a specific entity type. */
interface EntityHandler<T = any> {
  /** Lists records with optional pagination and sorting. Max 5,000 per request. */
  list<K extends keyof T = keyof T>(
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Filters records based on a query. Max 5,000 per request. */
  filter<K extends keyof T = keyof T>(
    query: Partial<T>,
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Gets a single record by ID. */
  get(id: string): Promise<T>;

  /** Creates a new record. */
  create(data: Partial<T>): Promise<T>;

  /** Updates an existing record. */
  update(id: string, data: Partial<T>): Promise<T>;

  /** Deletes a single record by ID. */
  delete(id: string): Promise<DeleteResult>;

  /** Deletes multiple records matching a query. */
  deleteMany(query: Partial<T>): Promise<DeleteManyResult>;

  /** Creates multiple records in a single request. */
  bulkCreate(data: Partial<T>[]): Promise<T[]>;

  /**
   * Updates multiple records matching a query using MongoDB update operators.
   * @param query - Filter to select which records to update.
   * @param data - MongoDB update operator object (e.g., `{ $set: { field: value } }`).
   */
  updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;

  /** Updates multiple records by ID, each with its own update data. */
  bulkUpdate(data: (Partial<T> & { id: string })[]): Promise<T[]>;

  /** Imports records from a file (frontend only). */
  importEntities(file: File): Promise<ImportResult<T>>;

  /** Subscribes to realtime updates. Returns unsubscribe function. */
  subscribe(callback: RealtimeCallback<T>): () => void;
}

EntitiesModule

/** Entities module: typed registry keys get typed handlers; dynamic access remains untyped. */
type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;

type TypedEntitiesModule = {
  [K in keyof EntityTypeRegistry]: EntityHandler<EntityRecord[K]>;
};

type DynamicEntitiesModule = {
  [entityName: string]: EntityHandler<any>;
};

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

​Módulo Entities

​Conteúdo

​Métodos

​Exemplos

​Criar

​Bulk Create

​Listar com paginação

​Filtrar

​Obter por ID

​Atualizar

​Excluir

​Update Many (estilo MongoDB)

​Bulk Update (por ID)

​Importar de arquivo

​Subscrever atualizações em tempo real

​Entidade User

​Acesso Service Role

​Permissões (RLS e FLS)

​Definições de tipo

​RealtimeEvent

​Tipos de resultado

​SortField e campos do servidor

​Registro de tipos (para entidades tipadas)

​EntityHandler

​EntitiesModule

Módulo Entities

Conteúdo

Métodos

Exemplos

Criar

Bulk Create

Listar com paginação

Filtrar

Obter por ID

Atualizar

Excluir

Update Many (estilo MongoDB)

Bulk Update (por ID)

Importar de arquivo

Subscrever atualizações em tempo real

Entidade User

Acesso Service Role

Permissões (RLS e FLS)

Definições de tipo

RealtimeEvent

Tipos de resultado

SortField e campos do servidor

Registro de tipos (para entidades tipadas)

EntityHandler

EntitiesModule