Query Builder
Supabase-style type-safe query builder
Query Builder
Access the per-collection query builder via the client.from(collection) method.
Client.from() returns a ReadOnlyQueryBuilder (read-only), while ServerClient.from() returns the full CollectionQueryBuilder (read + write).
Read Operations
find() - List Query
const { docs, totalDocs, hasNextPage } = await client.from('posts').find({
limit: 10,
page: 1,
sort: '-createdAt',
where: { _status: { equals: 'published' } },
depth: 2,
select: { title: true, slug: true },
})Return type: PayloadFindResponse<T> — see Response Format for the full type definition.
findById() - Find by ID
const post = await client.from('posts').findById('post_id')
// Returns: T (document object directly)count() - Document Count
const { totalDocs } = await client.from('posts').count({
where: { _status: { equals: 'published' } }
})Write Operations
Write operations are only available on ServerClient.
create()
const { doc, message } = await serverClient.from('posts').create({
title: 'New Post',
_status: 'draft',
})
// Returns: PayloadMutationResponse<T> { doc, message, errors? }update()
const { doc } = await serverClient.from('posts').update('post_id', {
title: 'Updated Post',
})remove()
const deleted = await serverClient.from('posts').remove('post_id')
// Returns: T (deleted document)updateMany() / removeMany()
await serverClient.from('posts').updateMany(
{ _status: { equals: 'draft' } }, // where
{ _status: 'published' }, // data
)
await serverClient.from('posts').removeMany(
{ _status: { equals: 'draft' } }, // where
)Query Options
| Option | Type | Description |
|---|---|---|
page | number | Page number (default: 1) |
limit | number | Items per page (default: 10) |
sort | string | Sort order (-createdAt = descending) |
where | Where | Filter conditions (see Filtering) |
depth | number | Relationship query depth (0-10, default: 1) |
select | Record<string, boolean> | Field selection |
populate | Record<string, boolean | Record<string, boolean>> | Per-collection field selection for populated relationships |
joins | Record<string, object | false> | false | Join field control (pagination, filter, or disable) |
Metadata Query
Generate Next.js metadata from collection documents. See the Metadata docs for details.
const metadata = await client.from('posts').findMetadata(
{ where: { slug: { equals: 'my-post' } } },
{ siteName: 'My Site' },
)
const metadata = await client.from('posts').findMetadataById('post_id')Response Type Summary
| Operation | Response |
|---|---|
find() | PayloadFindResponse<T> - { docs, totalDocs, hasNextPage, ... } |
findById() | T |
findMetadata() | Metadata | null |
findMetadataById() | Metadata |
create() | PayloadMutationResponse<T> - { doc, message } |
update() | PayloadMutationResponse<T> - { doc, message } |
remove() | T |
count() | { totalDocs: number } |