Tables — Rows

Read and write custom-table rows from your server with the client.table(name) accessor

Custom tables let you provision your own database tables alongside Sublay’s built-in models. The client.table(name) accessor gives you full row-level access to a custom table from your server. For an overview of the feature — the custom_ naming model, managed columns, and soft-delete — see Custom Tables. To create tables and columns, see Tables — Management.

client.table(name) is a callable accessor, not a flat module namespace — it closes over the table name and returns the row-operation object. You can type the rows by passing a generic: client.table<EventRow>("Events").

interface EventRow {
  id: string;
  name: string;
  capacity: number;
  createdAt: string;
}

const events = sublay.table<EventRow>("Events");
const { data } = await events.find({ limit: 20 });

The name you pass is the logical table name — Sublay applies the custom_ prefix for you.

---

find

Fetches a filtered, sorted, paginated page of rows. Returns the shared { data, pagination } envelope.

const { data, pagination } = await sublay.table<EventRow>("Events").find({
  page: 1,
  limit: 20,
  sortBy: "createdAt",
  sortDir: "desc",
  filters: [
    { column: "capacity", operator: "gte", value: 100 },
    { column: "name", operator: "contains", value: "summit" },
  ],
});

page · number

Page number (1-indexed).

limit · number

Rows per page.

sortBy · string

Column to sort by. Validated against the table’s real columns. Defaults to createdAt (descending) on a table with timestamps, otherwise id.

sortDir · "asc" | "desc"

Sort direction.

filters · DbFilter[]

An array of { column, operator, value } clauses, AND-combined. Operators: eq, ne, gt, gte, lt, lte, in, contains, like, isNull. Serialized to a JSON query parameter for you.

includeDeleted · boolean

On a paranoid table, set true to include soft-deleted rows. Defaults to false.

Returns — Promise<PaginatedResponse<T>>

---

findOne

Fetches a single row by its id. Throws (axios 404) if the row doesn’t exist or has been soft-deleted.

const event = await sublay.table<EventRow>("Events").findOne("a1b2c3d4-...");

rowId · string · required

The row’s id (UUID).

Returns — Promise<T>

---

create

Inserts a single row. Managed columns (id, createdAt, updatedAt, deletedAt) are rejected from the body — they are set by the server.

const event = await sublay.table<EventRow>("Events").create({
  name: "Launch Summit",
  capacity: 250,
});

data · Partial<T> · required

The column values for the new row.

Returns — Promise<T>

---

bulkCreate

Inserts many rows in one call. Capped at 100 rows per request.

const rows = await sublay.table<EventRow>("Events").bulkCreate([
  { name: "Workshop A", capacity: 40 },
  { name: "Workshop B", capacity: 40 },
]);

rows · Partial<T>[] · required

The rows to insert (max 100).

Returns — Promise<T[]>

---

update

Updates a row by id. On a table with timestamps, updatedAt is bumped automatically. Managed columns are rejected from the body.

const event = await sublay.table<EventRow>("Events").update("a1b2c3d4-...", {
  capacity: 300,
});

rowId · string · required

The row’s id.

data · Partial<T> · required

The column values to change.

Returns — Promise<T>

---

delete

Deletes a row by id. On a paranoid table this is a soft delete (sets deletedAt); pass force: true to hard-delete. On a non-paranoid table it is always a hard delete.

// Soft delete on a paranoid table
await sublay.table("Events").delete("a1b2c3d4-...");

// Hard delete
await sublay.table("Events").delete("a1b2c3d4-...", { force: true });

rowId · string · required

The row’s id.

opts.force · boolean

When true, hard-deletes a paranoid row instead of soft-deleting it.

Returns — Promise<{ deleted: boolean; soft: boolean }> — soft is true when the row was soft-deleted.

---

bulkDelete

Deletes many rows by an id list and/or a filters predicate (at least one is required). Paranoid-aware (soft by default, force to hard-delete) and capped at the bulk limit.

// By id list
await sublay.table("Events").bulkDelete({ rowIds: ["id-1", "id-2"] });

// By predicate
await sublay.table("Events").bulkDelete({
  filters: [{ column: "capacity", operator: "lt", value: 10 }],
  force: true,
});

rowIds · string[]

Rows to delete by id.

filters · DbFilter[]

A predicate selecting rows to delete (same shape as find’s filters).

force · boolean

When true, hard-deletes matched paranoid rows.

Returns — Promise<{ deletedCount: number; soft: boolean }>

---

restore

Clears deletedAt on a soft-deleted row, bringing it back. Only valid on a paranoid table.

const event = await sublay.table<EventRow>("Events").restore("a1b2c3d4-...");

rowId · string · required

The soft-deleted row’s id.

Returns — Promise<T>

---

Row CRUD on the /db surface is currently open — identity is captured but not enforced. See the security note on the overview page before storing access-controlled data in custom tables.