> ## Documentation Index > Fetch the complete documentation index at: https://docs.base44.com/llms.txt > Use this file to discover all available pages before exploring further. # Módulo Entities > Operações CRUD em modelos de dados. Acesse via base44.entities.EntityName.method(). 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](/developers). # Módulo Entities Operações CRUD em modelos de dados. Acesse via `base44.entities.EntityName.method()`. ## Conteúdo * [Métodos](#methods) * [Exemplos](#examples) (Criar, Bulk Create, Listar, Filtrar, Obter, Atualizar, Excluir, Subscrever) * [Entidade User](#user-entity) * [Acesso Service Role](#service-role-access) * [Permissões](#permissions) ## 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` | Cria um registro | | `bulkCreate(dataArray)` | `Promise` | Cria vários registros | | `list(sort?, limit?, skip?, fields?)` | `Promise[]>` | Obtém todos os registros (paginado) | | `filter(query, sort?, limit?, skip?, fields?)` | `Promise[]>` | Obtém registros correspondentes às condições | | `get(id)` | `Promise` | Obtém um único registro pelo ID | | `update(id, data)` | `Promise` | Atualiza o registro (atualização parcial) | | `updateMany(query, data)` | `Promise` | Atualiza todos os registros correspondentes usando operadores de atualização MongoDB | | `bulkUpdate(dataArray)` | `Promise` | Atualiza vários registros pelo ID, cada um com seus próprios dados | | `delete(id)` | `Promise` | Exclui o registro pelo ID | | `deleteMany(query)` | `Promise` | Exclui todos os registros correspondentes | | `importEntities(file)` | `Promise>` | Importa de CSV (apenas frontend) | | `subscribe(callback)` | `() => void` | Assina atualizações em tempo real (retorna função de cancelamento) | ## Exemplos ### Criar ```javascript theme={null} const task = await base44.entities.Task.create({ title: "Complete documentation", status: "pending", dueDate: "2024-12-31" }); ``` ### Bulk Create ```javascript theme={null} const tasks = await base44.entities.Task.bulkCreate([ { title: "Task 1", status: "pending" }, { title: "Task 2", status: "pending" } ]); ``` ### Listar com paginação ```javascript theme={null} // 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 ```javascript theme={null} // 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 ```javascript theme={null} const task = await base44.entities.Task.get("task-id-123"); ``` ### Atualizar ```javascript theme={null} // Partial update - only specified fields change await base44.entities.Task.update("task-id-123", { status: "completed", completedAt: new Date().toISOString() }); ``` ### Excluir ```javascript theme={null} // 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) ```javascript theme={null} // 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) ```javascript theme={null} // 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 ```javascript theme={null} // 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 ```javascript theme={null} // 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:** ```javascript theme={null} { 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 ```javascript theme={null} // 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): ```javascript theme={null} // 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. 1. **Nível de autenticação**: anônimo, autenticado ou service role 2. **Regras RLS**: Controlam quais registros (linhas) os usuários podem criar/ler/atualizar/excluir 3. **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](https://docs.base44.com/developers/skills/base44-sdk/references/../../base44-cli/references/entities-create.md#row-level-security-rls) 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 ```typescript theme={null} /** Event types for realtime entity updates. */ type RealtimeEventType = "create" | "update" | "delete"; /** Payload received when a realtime event occurs. */ interface RealtimeEvent { /** 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 = (event: RealtimeEvent) => void; ``` ### Tipos de resultado ```typescript theme={null} /** 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 { /** 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 ```typescript theme={null} /** * Sort field type for entity queries. * Supports ascending (no prefix or '+') and descending ('-') sorting. * Example: 'created_date', '+created_date', '-created_date' */ type SortField = (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**. ```typescript theme={null} /** * 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 ```typescript theme={null} /** Entity handler providing CRUD operations for a specific entity type. */ interface EntityHandler { /** Lists records with optional pagination and sorting. Max 5,000 per request. */ list( sort?: SortField, limit?: number, skip?: number, fields?: K[] ): Promise[]>; /** Filters records based on a query. Max 5,000 per request. */ filter( query: Partial, sort?: SortField, limit?: number, skip?: number, fields?: K[] ): Promise[]>; /** Gets a single record by ID. */ get(id: string): Promise; /** Creates a new record. */ create(data: Partial): Promise; /** Updates an existing record. */ update(id: string, data: Partial): Promise; /** Deletes a single record by ID. */ delete(id: string): Promise; /** Deletes multiple records matching a query. */ deleteMany(query: Partial): Promise; /** Creates multiple records in a single request. */ bulkCreate(data: Partial[]): Promise; /** * 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, data: Record>): Promise; /** Updates multiple records by ID, each with its own update data. */ bulkUpdate(data: (Partial & { id: string })[]): Promise; /** Imports records from a file (frontend only). */ importEntities(file: File): Promise>; /** Subscribes to realtime updates. Returns unsubscribe function. */ subscribe(callback: RealtimeCallback): () => void; } ``` ### EntitiesModule ```typescript theme={null} /** Entities module: typed registry keys get typed handlers; dynamic access remains untyped. */ type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule; type TypedEntitiesModule = { [K in keyof EntityTypeRegistry]: EntityHandler; }; type DynamicEntitiesModule = { [entityName: string]: EntityHandler; }; ``` Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a [versão em inglês](/).