Esta página es parte de una habilidad de agente de codificación con IA y está escrita para agentes, no para humanos. Para la documentación de Base44 legible por humanos, consulta la documentación para desarrolladores.

Módulo Entities

Operaciones CRUD en modelos de datos. Accede mediante base44.entities.EntityName.method().

Contenido

Métodos
Ejemplos (Create, Bulk Create, List, Filter, Get, Update, Delete, Subscribe)
Entidad User
Acceso de rol de servicio
Permisos

Métodos

Nota: El límite máximo para list() y filter() es 5.000 elementos por solicitud.

Método	Firma	Descripción
`create(data)`	`Promise<T>`	Crea un registro
`bulkCreate(dataArray)`	`Promise<T[]>`	Crea varios registros
`list(sort?, limit?, skip?, fields?)`	`Promise<Pick<T, K>[]>`	Obtiene todos los registros (paginado)
`filter(query, sort?, limit?, skip?, fields?)`	`Promise<Pick<T, K>[]>`	Obtiene registros que coinciden con las condiciones
`get(id)`	`Promise<T>`	Obtiene un solo registro por ID
`update(id, data)`	`Promise<T>`	Actualiza registro (actualización parcial)
`updateMany(query, data)`	`Promise<UpdateManyResult>`	Actualiza todos los registros coincidentes usando operadores de actualización de MongoDB
`bulkUpdate(dataArray)`	`Promise<T[]>`	Actualiza varios registros por ID, cada uno con sus propios datos
`delete(id)`	`Promise<DeleteResult>`	Elimina registro por ID
`deleteMany(query)`	`Promise<DeleteManyResult>`	Elimina todos los registros coincidentes
`importEntities(file)`	`Promise<ImportResult<T>>`	Importa desde CSV (solo frontend)
`subscribe(callback)`	`() => void`	Suscribe a actualizaciones en tiempo real (devuelve función de cancelación de suscripción)

Ejemplos

Crear

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

Crear en masa

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

Listar con paginación

// Obtener los primeros 10 registros, ordenados por created_date descendente (máx. 5.000 por solicitud)
const tasks = await base44.entities.Task.list(
  "-created_date",  // orden (SortField: prefijo con - para descendente)
  10,               // límite
  0                 // saltar
);

// Obtener siguiente página
const page2 = await base44.entities.Task.list("-created_date", 10, 10);

Filtrar

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

// Múltiples condiciones
const myPending = await base44.entities.Task.filter({
  status: "pending",
  assignedTo: userId
});

// Con orden, límite, salto (máx. 5.000 por solicitud)
const recent = await base44.entities.Task.filter(
  { status: "pending" },
  "-created_date",  // orden (SortField: prefijo con - para descendente)
  5,
  0
);

// Seleccionar campos específicos
const titles = await base44.entities.Task.filter(
  { status: "pending" },
  null,
  null,
  null,
  ["id", "title"]
);

Obtener por ID

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

Actualizar

// Actualización parcial - solo cambian los campos especificados
await base44.entities.Task.update("task-id-123", {
  status: "completed",
  completedAt: new Date().toISOString()
});

Eliminar

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

// Varios registros que coinciden con la consulta
const manyResult = await base44.entities.Task.deleteMany({ status: "archived" });
console.log("Deleted:", manyResult.deleted);

Actualizar varios (estilo MongoDB)

// Actualizar todas las tareas pendientes a estado "in-progress"
const result = await base44.entities.Task.updateMany(
  { status: "pending" },                     // consulta: qué registros actualizar
  { $set: { status: "in-progress" } }        // operador de actualización de MongoDB
);
console.log("Updated:", result.updated);

// Incrementar un campo contador
await base44.entities.Task.updateMany(
  { category: "bugs" },
  { $inc: { priority: 1 } }
);

Actualización en masa (por ID)

// Actualizar varios registros, cada uno con datos diferentes
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 desde archivo

// Solo frontend: importar desde CSV/archivo
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);
}

Suscribirse a actualizaciones en tiempo real

// Suscribirse a todos los cambios en la entidad Task
const unsubscribe = base44.entities.Task.subscribe((event) => {
  console.log(`Task ${event.id} was ${event.type}:`, event.data);
  // event.type es "create", "update" o "delete"
});

// Más tarde: cancelar suscripción para dejar de recibir actualizaciones
unsubscribe();

Estructura del evento:

{
  type: "create" | "update" | "delete",
  data: { ... },       // los datos de la entidad
  id: "entity-id",     // el ID de la entidad afectada
  timestamp: "2024-01-15T10:30:00Z"
}

Entidad User

Cada app tiene una entidad User integrada con reglas especiales:

Los usuarios regulares solo pueden leer/actualizar su propio registro
No se pueden crear usuarios mediante entities.create() - usa auth.register() en su lugar
El rol de servicio tiene acceso completo a todos los registros de usuario

// Obtener el registro del usuario actual
const me = await base44.entities.User.get(currentUserId);

// Rol de servicio: obtener cualquier usuario
const anyUser = await base44.asServiceRole.entities.User.get(userId);

Acceso de rol de servicio

Para operaciones de nivel administrador (evitar permisos de usuario):

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

Permisos (RLS y FLS)

El acceso a datos está controlado por reglas de Row Level Security (RLS) y Field Level Security (FLS) definidas en los esquemas de entidad.

Nivel de autenticación: anónimo, autenticado o rol de servicio
Reglas RLS: Controlan qué registros (filas) pueden crear/leer/actualizar/eliminar los usuarios
Reglas FLS: Controlan qué campos pueden leer/escribir los usuarios dentro de los registros accesibles

Las operaciones tienen éxito o fallan según estas reglas - no hay resultados parciales. RLS y FLS se configuran en los archivos de esquema de entidad (base44/entities/*.jsonc). Consulta entities-create.md para detalles de configuración. Nota: asServiceRole establece el rol del usuario a "admin" pero NO evita RLS. Tus reglas RLS deben incluir acceso de administrador (por ejemplo, { "user_condition": { "role": "admin" } }) para que las operaciones de rol de servicio tengan éxito.

Definiciones de tipos

RealtimeEvent

/** Tipos de eventos para actualizaciones de entidad en tiempo real. */
type RealtimeEventType = "create" | "update" | "delete";

/** Carga útil recibida cuando ocurre un evento en tiempo real. */
interface RealtimeEvent<T = any> {
  /** El tipo de cambio que ocurrió. */
  type: RealtimeEventType;
  /** Los datos de la entidad. */
  data: T;
  /** El identificador único de la entidad afectada. */
  id: string;
  /** Marca de tiempo ISO 8601 de cuándo ocurrió el evento. */
  timestamp: string;
}

/** Función de callback invocada cuando ocurre un evento en tiempo real. */
type RealtimeCallback<T = any> = (event: RealtimeEvent<T>) => void;

Tipos de resultado

/** Resultado devuelto al actualizar varias entidades. */
interface UpdateManyResult {
  /** Si la actualización fue exitosa. */
  success: boolean;
  /** Número de entidades que se actualizaron. */
  updated: number;
}

/** Resultado devuelto al eliminar una sola entidad. */
interface DeleteResult {
  /** Si la eliminación fue exitosa. */
  success: boolean;
}

/** Resultado devuelto al eliminar varias entidades. */
interface DeleteManyResult {
  /** Si la eliminación fue exitosa. */
  success: boolean;
  /** Número de entidades que se eliminaron. */
  deleted: number;
}

/** Resultado devuelto al importar entidades desde un archivo. */
interface ImportResult<T = any> {
  /** Estado de la operación de importación. */
  status: "success" | "error";
  /** Mensaje de detalles, por ejemplo, "Successfully imported 3 entities with RLS enforcement". */
  details: string | null;
  /** Array de objetos de entidad creados cuando tiene éxito, o null en error. */
  output: T[] | null;
}

SortField y campos del servidor

/**
 * Tipo de campo de ordenación para consultas de entidad.
 * Admite ordenación ascendente (sin prefijo o '+') y descendente ('-').
 * Ejemplo: 'created_date', '+created_date', '-created_date'
 */
type SortField<T> = (keyof T & string) | `+${keyof T & string}` | `-${keyof T & string}`;

/** Campos añadidos por el servidor a cada registro de entidad. */
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)

Cómo obtener entidades tipadas: La CLI de Base44 puede generar interfaces de entidad y una augmentación de EntityTypeRegistry desde tu proyecto. Para saber cómo ejecutarlo, usa la habilidad base44-cli.

/**
 * Registro que mapea nombres de entidad a sus tipos TypeScript.
 * Aumenta esta interfaz con tu esquema de entidad (solo campos definidos por el usuario).
 * Normalmente lo rellena el generador de tipos de la CLI de Base44.
 */
interface EntityTypeRegistry {}

/**
 * Tipo de registro completo para cada entidad: campos de esquema + campos inyectados por el servidor.
 */
type EntityRecord = {
  [K in keyof EntityTypeRegistry]: EntityTypeRegistry[K] & ServerEntityFields;
};

EntityHandler

/** Manejador de entidad que proporciona operaciones CRUD para un tipo de entidad específico. */
interface EntityHandler<T = any> {
  /** Lista registros con paginación y ordenación opcionales. Máx. 5.000 por solicitud. */
  list<K extends keyof T = keyof T>(
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Filtra registros basados en una consulta. Máx. 5.000 por solicitud. */
  filter<K extends keyof T = keyof T>(
    query: Partial<T>,
    sort?: SortField<T>,
    limit?: number,
    skip?: number,
    fields?: K[]
  ): Promise<Pick<T, K>[]>;

  /** Obtiene un solo registro por ID. */
  get(id: string): Promise<T>;

  /** Crea un nuevo registro. */
  create(data: Partial<T>): Promise<T>;

  /** Actualiza un registro existente. */
  update(id: string, data: Partial<T>): Promise<T>;

  /** Elimina un solo registro por ID. */
  delete(id: string): Promise<DeleteResult>;

  /** Elimina varios registros que coinciden con una consulta. */
  deleteMany(query: Partial<T>): Promise<DeleteManyResult>;

  /** Crea varios registros en una sola solicitud. */
  bulkCreate(data: Partial<T>[]): Promise<T[]>;

  /**
   * Actualiza varios registros que coinciden con una consulta usando operadores de actualización de MongoDB.
   * @param query - Filtro para seleccionar qué registros actualizar.
   * @param data - Objeto de operador de actualización de MongoDB (por ejemplo, `{ $set: { field: value } }`).
   */
  updateMany(query: Partial<T>, data: Record<string, Record<string, any>>): Promise<UpdateManyResult>;

  /** Actualiza varios registros por ID, cada uno con sus propios datos de actualización. */
  bulkUpdate(data: (Partial<T> & { id: string })[]): Promise<T[]>;

  /** Importa registros desde un archivo (solo frontend). */
  importEntities(file: File): Promise<ImportResult<T>>;

  /** Suscribe a actualizaciones en tiempo real. Devuelve una función de cancelación de suscripción. */
  subscribe(callback: RealtimeCallback<T>): () => void;
}

EntitiesModule

/** Módulo Entities: las claves de registro tipadas obtienen manejadores tipados; el acceso dinámico permanece sin tipar. */
type EntitiesModule = TypedEntitiesModule & DynamicEntitiesModule;

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

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

Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la versión en inglés.

​Módulo Entities

​Contenido

​Métodos

​Ejemplos

​Crear

​Crear en masa

​Listar con paginación

​Filtrar

​Obtener por ID

​Actualizar

​Eliminar

​Actualizar varios (estilo MongoDB)

​Actualización en masa (por ID)

​Importar desde archivo

​Suscribirse a actualizaciones en tiempo real

​Entidad User

​Acceso de rol de servicio

​Permisos (RLS y FLS)

​Definiciones de tipos

​RealtimeEvent

​Tipos de resultado

​SortField y campos del servidor

​Registro de tipos (para entidades tipadas)

​EntityHandler

​EntitiesModule

Módulo Entities

Contenido

Métodos

Ejemplos

Crear

Crear en masa

Listar con paginación

Filtrar

Obtener por ID

Actualizar

Eliminar

Actualizar varios (estilo MongoDB)

Actualización en masa (por ID)

Importar desde archivo

Suscribirse a actualizaciones en tiempo real

Entidad User

Acceso de rol de servicio

Permisos (RLS y FLS)

Definiciones de tipos

RealtimeEvent

Tipos de resultado

SortField y campos del servidor

Registro de tipos (para entidades tipadas)

EntityHandler

EntitiesModule