Query Operators

Kadak keeps the base path simple:

await db.users.findMany({ isActive: true, $limit: 50 })

When needed, use operators for advanced filtering.

Core filter rules

• Top-level object = WHERE filter.
• Multiple fields at top level are AND.
• $or creates grouped OR conditions.
• $limit maps to LIMIT.
• $order maps to ORDER BY.

Equality and NULL

await db.users.findMany({ age: 18 })
await db.users.findMany({ deletedAt: null })

SQL equivalent:

• age = 18
• deleted_at IS NULL

Comparison operators

await db.users.findMany({
  age: { $gt: 18, $lte: 65 },
})

SQL equivalent:

• age > 18
• age <= 65

Supported:

• $gt
• $gte
• $lt
• $lte

IN operator

await db.users.findMany({
  email: { $in: ['a@example.com', 'b@example.com'] },
})

SQL equivalent:

• email IN ('a@example.com', 'b@example.com')

Arrays also map to IN:

await db.users.findMany({ id: [1, 2, 3] })

OR groups

await db.users.findMany({
  $or: [{ role: 'admin' }, { isActive: true }],
  $limit: 50,
})

SQL equivalent:

• (role = 'admin' OR is_active = true)

Ordering

await db.users.findMany({
  isActive: true,
  $order: { createdAt: 'desc', id: 'asc' },
  $limit: 50,
})

SQL equivalent:

• ORDER BY created_at DESC, id ASC

Full example

await db.users.findMany({
  age: { $gte: 18, $lt: 65 },
  deletedAt: null,
  $or: [{ role: 'admin' }, { role: 'owner' }],
  $order: { createdAt: 'desc' },
  $limit: 100,
})

Notes

• Kadak auto-maps camelCase fields to snake_case SQL columns by default.
• Use $limit on list queries for predictable performance.
• For unsupported patterns, use db.sql as escape hatch.