Query rows

Use select() for a page of results. Filters are combined with AND. Query values are parameterized, and the Worker checks selected columns against the live table schema.

const page = await carpo.database
  .withSchema<AppDatabase>()
  .from('todos')
  .select({
    where: { completed: false, id: { gte: 10 } },
    columns: ['id', 'title', 'completed'],
    limit: 25,
    orderBy: 'id',
    orderDirection: 'desc',
  })

console.log(page.rows, page.hasMore, page.nextCursor)

columns narrows the selected TypeScript row type. limit is an alias for pageSize. The default page size is 50 and the maximum is 100.

Filter operatorsCopy Anchor Link

An exact scalar value matches that value. For ranges and sets, use an operator object:

const rows = await carpo.database.from<Todo>('todos').select({
  where: {
    status: { in: ['open', 'blocked'] },
    priority: { gte: 2, lte: 4 },
    title: { like: '%docs%' },
    archived_at: { isNull: true },
  },
})

Supported operators are eq, neq, gt, gte, lt, lte, in, notIn, like, and isNull. Multiple conditions and operators are combined with AND. The notIn list cannot contain null; use isNull for null checks.

Read one rowCopy Anchor Link

single() throws a CarpoApiError with code ROW_CARDINALITY unless exactly one row matches. maybeSingle() returns null when no row matches and throws if more than one row matches.

const todo = await todos.single({ where: { id: 42 } })
const maybeTodo = await todos.maybeSingle({ where: { id: 43 } })

listTables() returns the tables visible to the current Project Auth user, their columns, and their effective permissions.