Work with data

The entities module lets you work with your app’s data. Each entity type in your app has methods for creating, reading, updating, and deleting records. You access entity methods through your entity name: base44.entities.YourEntityName.methodName(). For example, if you have a Task entity, you use base44.entities.Task.list() to get a list of tasks.

Generate TypeScript types from your entities to get autocomplete and type safety. Run base44 types generate in your project, and all entity fields, methods, and return types will be fully typed. Learn more about dynamic types.

Permissions

Data access is controlled by the client’s authentication mode and your app’s permission rules. You can configure the permissions for each entity in your app’s security settings. Learn more about changing data permissions.

Anonymous users: Can only access entities marked as public.
Authenticated users: Can access entities and records they have permission to view or modify based on your app’s configured access rules.
Service role: Bypasses entity access rules and field-level security entirely. Has full read and write access to every entity and record in the app.

In backend code, you can use the service role to access data without access-rule restrictions.

Create records

Use create() to add new records to an entity:

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

// After running: base44 types generate
const newTask = await base44.entities.Task.create({
  title: "Complete documentation",
  status: "pending",
  // TypeScript knows which fields exist
  // and validates their types
});

// Autocomplete works for fields
console.log(newTask.id);
console.log(newTask.created_date);

Read records

Retrieve data using get() for a single record, list() for all records, or filter() for records matching specific criteria. Use get() with a record ID to retrieve a specific record:

const task = await base44.entities.Task.get(taskId);

Use list() to retrieve all records. The method supports sorting, pagination, and field selection:

const tasks = await base44.entities.Task.list();

const tasks = await base44.entities.Task.list("-created_date");

const tasks = await base44.entities.Task.list(
  "-created_date",
  10, // limit
  20, // skip
);

const tasks = await base44.entities.Task.list(
  "-created_date",
  10,
  0,
  ["title", "status"], // only return these fields
);

For loops that read through many pages, pass an options object with a cursor instead of skip. See paging with a cursor below. Records added or deleted between pages never shift the boundary.

Use filter() to find records that match specific criteria:

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

const urgentTasks = await base44.entities.Task.filter({
  status: "pending",
  priority: "high",
});

const recentTasks = await base44.entities.Task.filter(
  { status: "pending" },
  "-created_date", // Sort by created date, descending
);

const tasks = await base44.entities.Task.filter(
  { status: "pending" },
  "-created_date",
  10, // limit
  20, // skip
);

Paging with a cursor

Pass an options object instead of positional arguments to list() or filter() to read one page by cursor. Each call returns a page with items, next_cursor, and has_more:

const allTasks = [];
let page = await base44.entities.Task.list({ sort: "-created_date", limit: 1000 });
allTasks.push(...page.items);

while (page.has_more) {
  page = await base44.entities.Task.list({ cursor: page.next_cursor, limit: 1000 });
  allTasks.push(...page.items);
}

const allOrders = [];
let page = await base44.entities.Order.filter(
  { status: "open" },
  { sort: "-created_date", limit: 1000 },
);
allOrders.push(...page.items);

while (page.has_more) {
  page = await base44.entities.Order.filter(
    { status: "open" },
    { cursor: page.next_cursor, limit: 1000 },
  );
  allOrders.push(...page.items);
}

const { items: categories } = await base44.entities.Product.list({
  distinct: "category",
});

A cursor carries this walk’s parameters, so a later page needs only cursor and limit. Passing different parameters with a cursor fails. Existing code using skip still works, but prefer a cursor for pagination. Records added or deleted between pages never shift the boundary.

Count records

Use count() to get the number of matching records without fetching them, for totals, badges, and “page N of M”:

const open = await base44.entities.Task.count({ status: "open" });

const total = await base44.entities.Task.count();

Aggregate records

Use aggregate() to group records on the server and compute totals, sums, averages, or distinct counts per group, up to 1,000 rows. This is faster than loading every record and adding up the results yourself:

const { rows } = await base44.entities.Sale.aggregate({
  query: { sale_date: { $gte: "2026-09-01" } },
  groupBy: "agent_id",
  sum: "amount",
  sort: "-sum_amount",
});
// rows: [
//   { agent_id: "a1", count: 42, sum_amount: 18250 },
//   { agent_id: "a2", count: 37, sum_amount: 15400 },
//   ...
// ]

const { rows } = await base44.entities.Task.aggregate({
  dateBucket: { field: "created_date", unit: "day" },
});
// rows: [
//   { created_date: "2026-09-01", count: 8 },
//   { created_date: "2026-09-02", count: 11 },
//   ...
// ]

const { rows } = await base44.entities.Order.aggregate({
  groupBy: "external_id",
  having: { count: { $gt: 1 } },
});
// rows: [
//   { external_id: "ext-42", count: 3 },
//   { external_id: "ext-77", count: 2 }
// ]

You can group by up to four fields. Every date field supports "day", "month", and "year" for dateBucket.unit. The created_date and updated_date fields also support "week". A having filter applies to the computed rows after grouping, keyed by computed field names like count and sum_<field>, not by raw or groupBy fields. See the aggregate() reference for avg, min, max, and countDistinct.

Update records

Use update() to modify an existing record:

await base44.entities.Task.update(taskId, {
  status: "completed",
});

Delete records

Use delete() to remove a single record:

await base44.entities.Task.delete(taskId);

Use deleteMany() to remove multiple records matching specific criteria:

const result = await base44.entities.Task.deleteMany({
  status: "completed",
  priority: "low",
});

Bulk operations

Use bulkCreate() to create multiple records in a single request:

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

Use importEntities() to import records from a CSV file. This is useful for migrating data or bulk uploads from user interfaces:

const handleFileUpload = async (event) => {
  const file = event.target.files?.[0];
  if (file) {
    const result = await base44.entities.Task.importEntities(file);
    console.log(`Imported ${result.output.length} records`);
  }
};

Using importEntities() requires a browser environment. It cannot be used in backend code.

Upsert by a key

Use upsert() to create or update records by a key you define, instead of by id. This is useful whenever records have a natural key, such as an ID from another system or a one-per-user record keyed by user_id, so you don’t have to look up each record first to decide between create and update. Name the field, or fields, that identify a record, and matching records are updated while the rest are created, in one call:

const result = await base44.entities.Product.upsert(
  supplierCatalog.map((p) => ({ sku: p.sku, name: p.name, price: p.price })),
  { key: "sku" },
);
console.log(`${result.created} new, ${result.updated} updated`);

const result = await base44.entities.Inventory.upsert(
  warehouseFeed.map((row) => ({ sku: row.sku, warehouse: row.warehouseCode, quantity: row.qty })),
  { key: ["sku", "warehouse"] },
);
console.log(`${result.created} new, ${result.updated} updated`);

Every record needs a value, not an object or array, for the field, or fields, named in key, so the server can find or create by it. Other fields are optional, and only the ones you include are merged into a matched record, like update(). You can upsert up to 500 records per request. When two records in one call share a key, the last one wins.

Realtime subscriptions

Use subscribe() to receive realtime updates when records are created, updated, or deleted:

const unsubscribe = base44.entities.Task.subscribe((event) => {
  console.log(`Task ${event.id} was ${event.type}d`);
  console.log("Updated data:", event.data);
});

// Later, clean up the subscription
unsubscribe();

Realtime events follow your entity’s security rules. When an entity has row-level or field-level read rules, each subscriber only receives events for the records their rules allow, and the event data only includes the fields they can read.

Service role data access

By default, data access is scoped to the current user’s permissions. With service role authentication, you can read and write any data in your app. Entity access rules and field-level security are bypassed entirely, regardless of how the entity is configured. Use base44.asServiceRole.entities to access data without access-rule restrictions:

// User-level access (limited to current user's permissions)
const myTasks = await base44.entities.Task.list();

// Service role access (bypasses entity access rules)
const allTasks = await base44.asServiceRole.entities.Task.list();

Service role access skips every access rule on the entity. Use it only for trusted backend logic. If your function needs access checks, you’re responsible for enforcing them yourself.

User entity

Every Base44 app includes a built-in User entity that stores user account information. This entity has special security rules:

Regular users can only read and update their own user record
With service role authentication, you can read, update, and delete any user
You cannot create users through the entities module - use the auth module instead

You can add fields to the User entity to store additional user data, then use those fields in security rules to control data access or in your app to personalize the experience. See User Schema for details.

const allUsers = await base44.asServiceRole.entities.User.list();

Get Started

SDK Reference

Permissions

Create records

Read records

Paging with a cursor

Count records

Aggregate records

Update records

Delete records

Bulk operations

Upsert by a key

Realtime subscriptions

Service role data access

User entity

See more

entities module

Base44 client

​Permissions

​Create records

​Read records

​Paging with a cursor

​Count records

​Aggregate records

​Update records

​Delete records

​Bulk operations

​Upsert by a key

​Realtime subscriptions

​Service role data access

​User entity

​See more

entities module

Base44 client

Permissions

Create records

Read records

Paging with a cursor

Count records

Aggregate records

Update records

Delete records

Bulk operations

Upsert by a key

Realtime subscriptions

Service role data access

User entity

See more