Skip to content

Querying content

Read content with the methods on your CMS instance. Queries are plain objects, typed from your schema, and run on the server: in server components, route handlers, generateMetadata and generateStaticParams. They read from a local copy of your content that ships with your deploy and is kept in sync when the content changes, see Instant publishing.

app/page.tsx
import {cms} from '@/cms'
import {HomePage} from '@/schema'

export default async function Page() {
  const home = await cms.get({type: HomePage})
  return <h1>{home.title}</h1>
}

Methods

import {cms} from '@/cms'
import {BlogPost} from '@/schema'

// All matches, as an array (possibly empty)
const posts = await cms.find({type: BlogPost})

// The first match, or null
const latest = await cms.first({
  type: BlogPost,
  orderBy: {desc: BlogPost.publishDate}
})

// The first match, or throws "Entry not found"
const post = await cms.get({type: BlogPost, path: 'hello-world'})

// The number of matches
const total = await cms.count({type: BlogPost})

Use first when a missing entry is a normal case, such as a url that may not exist (call notFound() when it returns null), and get for entries that must exist, like a seeded home page.

What a query returns

Without a select, you get the fields of the type you passed as type, plus the entry's own properties, prefixed with an underscore. A query without type returns only those properties.

import {cms} from '@/cms'
import {BlogPost} from '@/schema'

const post = await cms.get({type: BlogPost, path: 'hello-world'})
post.title // a field of the type
post.publishDate // "2026-09-23"
post.author // link fields are resolved: {title, url, ...} or null
post._id // the entry id
post._url // "/blog/hello-world"
post._locale // "en", or null in roots without i18n

The entry properties are _id, _type, _index, _workspace, _root, _status, _parentId, _locale, _path, _url, _createdAt and _updatedAt.

With select you get exactly what you ask for, in the shape you ask for. Select fields through the type (BlogPost.publishDate) and entry properties through Query:

import {cms} from '@/cms'
import {BlogPost} from '@/schema'
import {Query} from 'alinea'

const cards = await cms.find({
  type: BlogPost,
  select: {
    title: Query.title,
    url: Query.url,
    date: BlogPost.publishDate,
    cover: BlogPost.cover
  }
})
// Array<{title: string, url: string, date: string, cover: ImageLink | null}>

// A single expression returns plain values
const urls = await cms.find({type: BlogPost, select: Query.url})
// Array<string>

Query has id, title, type, index, workspace, root, status, parentId, locale, path, url, aliases, createdAt and updatedAt, plus the relation helpers such as Query.children and Query.referencedBy described in Related content and Query.snippet for search results.

Query fields and type fields

There are two kinds of references you can select. Query.* are the built-in properties every entry has, whatever its type: Query.id, Query.title, Query.url and the others above. The fields you define are selected through their type: BlogPost.intro is the intro field of BlogPost, BlogPost.cover its cover image. Type fields are typed from their definition and resolved like they are without a select, so BlogPost.cover returns an ImageLink. Combine both in one select:

import {cms} from '@/cms'
import {BlogPost} from '@/schema'
import {Query} from 'alinea'

const posts = await cms.find({
  type: BlogPost,
  select: {
    // Built-in properties of the entry
    id: Query.id,
    title: Query.title,
    url: Query.url,
    // Fields of the BlogPost type
    intro: BlogPost.intro,
    cover: BlogPost.cover
  }
})
// Array<{id: string, title: string, url: string, intro: string, cover: ImageLink | null}>

A type field only has a value on entries of that type, so select it in a query for that type (or one filtered on _type). Query fields work in any query, also one without a type, such as a search across all entries. Fields that Config.document adds, like title and path, are available both ways: Query.title and BlogPost.title return the same value.

Fields inside an object field are selected through the object: Page.seo.title returns the title of the seo object, typed like the field. That works wherever a field can be selected, also inside relations such as Query.children, and in orderBy:

import {cms} from '@/cms'
import {Config, Field, Query} from 'alinea'

export const Page = Config.document('Page', {
  fields: {
    seo: Field.object('SEO', {
      fields: {
        title: Field.text('SEO title'),
        description: Field.text('SEO description')
      }
    })
  }
})

const pages = await cms.find({
  type: Page,
  select: {url: Query.url, title: Page.seo.title},
  orderBy: {asc: Page.seo.title}
})
// Array<{url: string, title: string}>

Selecting only what a page needs keeps the data you pass to client components small, and TypeScript infers the result either way. To name the type of a result, use Awaited<ReturnType<typeof yourQueryFunction>>.

Query options

  • Which entries: type, id, path, url, parentId, workspace, root, location, level, locale, status and more, see Structural queries.

  • Matching content: filter on field values and search for full text, see Filtering.

  • Shape and order: select, include, orderBy, groupBy, skip and take, see Structural queries.

  • Related entries: parents, children, siblings, translations and linked entries in the same query, see Related content.

Options you pass as undefined are ignored, which makes it easy to build a query from optional parameters.

Drafts and previews

Queries return published content by default. When Next.js draft mode is on, for example while an editor looks at a live preview, Alinea switches to drafts where they exist and applies the unsaved changes of the preview, without any change to your queries. Pass status to override this.

Example schema

The examples in this chapter use this schema:

schema.ts
import {Config, Field} from 'alinea'

export const Author = Config.document('Author', {
  fields: {
    avatar: Field.image('Avatar'),
    bio: Field.text('Bio', {multiline: true})
  }
})

export const Category = Config.document('Category', {fields: {}})

export const Blog = Config.document('Blog', {
  contains: ['BlogPost'],
  fields: {}
})

export const BlogPost = Config.document('Blog post', {
  fields: {
    publishDate: Field.date('Publish date'),
    intro: Field.text('Intro', {multiline: true, searchable: true}),
    featured: Field.check('Featured'),
    cover: Field.image('Cover image'),
    author: Field.entry('Author', {condition: {_type: 'Author'}}),
    categories: Field.entry.multiple('Categories', {
      condition: {_type: 'Category'}
    }),
    tags: Field.select.multiple('Tags', {
      options: {news: 'News', release: 'Release', tutorial: 'Tutorial'}
    }),
    body: Field.richText('Body', {searchable: true})
  }
})

In this section