Tables

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

The JS SDK is row-only. Creating tables and columns (DDL) is service-key work, and the browser SDK holds no service key — so there is no table-management surface here. Manage schema from the @sublay/node SDK or the dashboard.

client.table(name) is a callable accessor — it closes over the table name and returns the row-operation object. Type the rows with a generic:

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. As with the rest of the JS SDK, these operations act as the user behind the token — you never pass an actor userId.

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 }],
});

page

number

Page number (1-indexed).

limit

number

Rows per page.

sortBy

string

Column to sort by. 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.

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.

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; pass force: true to hard-delete. On a non-paranoid table it is always a hard delete.

await sublay.table("Events").delete("a1b2c3d4-...");
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 }>

bulkDelete

Deletes many rows by an id list and/or a filters predicate (at least one required). Paranoid-aware and capped.

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

rowIds

string[]

Rows to delete by id.

filters

DbFilter[]

A predicate selecting rows to delete.

force

boolean

When true, hard-deletes matched paranoid rows.

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

restore

Clears deletedAt on a soft-deleted row. 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.

Getting Started

Modules

find

findOne

create

bulkCreate

update

delete

bulkDelete

restore

​find

​findOne

​create

​bulkCreate

​update

​delete

​bulkDelete

​restore

find

findOne

create

bulkCreate

update

delete

bulkDelete

restore