CollectionsQueries

Queries

Read entries, globals and the page tree from your own views, typed by your registry, cached, and aware of drafts.

View as Markdown

The read API

The reads are Astro live collections. src/live.config.ts names one loader per collection, global item, the pages and the page tree, from smoodly/astro/content:

src/live.config.ts
export const collections = {
  pages: defineLiveCollection({ loader: pageLoader() }),
  pageTree: defineLiveCollection({ loader: pageTreeLoader() }),
  articles: defineLiveCollection({ loader: entriesLoader(articles) }),
  // …
  footer: defineLiveCollection({ loader: globalLoader(footer) }),
  // …
};

A view reads with getLiveCollection and getLiveEntry from astro:content:

src/page-types/articlesIndex.astro
---
import { getLiveCollection } from "astro:content";
// …
const { entries = [] } = await getLiveCollection("articles", { locale: page.locale });
---
getLiveCollection("articles", options)Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent.
getLiveEntry("articles", { path, locale })One entry by its URL path, or by id, with its references resolved.
getLiveEntry("footer", { locale })A global item's value in a language, for a layout.
getLiveEntry("pages", { path, locale })A page by URL path or id.
getLiveCollection("pageTree", { locale })The published page tree in a language, each item with its page fields, for a navigation.

Each result's data is the read shape below. Every read tags the response, so a publish expires the page that made it.

Every read takes locale; without it, the default language. Collection and global names are checked against the registry, so a typo is a type error.

What comes back

Every read returns Smoodly's own keys at the top level and your content under fields, so a collection may have a field called path without a clash. Nothing else leaves the read: other languages' rows, draft pointers and editors' emails stay inside.

ReadShape
An entry`{ id, path, locale, locales, updatedAt, fields, seo? }`. `path` is the entry's URL in that language, or `null` without a collection path; `locales` is its address in every language; `updatedAt` is the last publish on the live site and the last save in draft mode; `seo` is present when the collection turns SEO on.
A page`{ id, title, path, locale, locales, template, fields, seo?, ancestors, children }`. `seo` is present when the page type has `seo: true`.
A global`{ locale, fields, settings?, styles? }`. A visual global adds `settings` and `styles`; an object global has `fields` only.

A collection read returns a list of these, fields typed from the collection, so an item needs no cast:

src/page-types/articlesIndex.astro
      {entries.map(({ data: entry }) => <ArticleCard article={entry.fields} url={href(entry.path!, page.locale)} locale={page.locale} />)}

A reference arrives resolved, as deep as its own field says: a bare f.ref gives { id, path, fields } and its target's references stay ids, .resolve("author") follows the named reference one level, and .resolve() follows the whole chain. Reference and tags has the table. In a list, images and references resolve in one batched pass per referenced collection, so a card has its author's fields and its image URL without a second read. A single entry resolves them the same way.

Filtering and limiting

where matches fields by equality, or by any of several values:

src/entry-pages/articles.astro
---
// …
const { entries: byAuthor = [] } = authorId ? await getLiveCollection("articles", { locale, where: { author: authorId } }) : { entries: [] };
// …
---

where sees every field, localized ones included, and filters the version shown: on the public site the published version, in the editor's preview the draft, so an unpublished edit never touches the live list. slug is not filterable, so find an entry by its path instead. For an array field such as tags or checkboxes, one value matches entries that contain it. The match is exact, case included. A tag is stored in the spelling the collection already uses, so once one entry has Dinner, another that types dinner stores Dinner too: filter with that spelling. limit applies after ordering and after the published-only filter, so it counts entries that are really there, and order overrides the collection's default for one query.

The starter's article page reads the four newest articles and drops itself to show three related ones.

Paging a list

offset skips that many entries after the order and the filter, before limit counts, so page N of a list is limit entries from (N - 1) * limit. The read returns the page's entries and no total: ask for one entry more than you show to know whether a next page exists.

Pass the same two options to getLiveCollection: { locale, limit: perPage + 1, offset: (page - 1) * perPage }, show the first perPage entries, and link to the next page when the read returned one more.

Each page is cached as its own read and expires with the collection, like any other list.

Draft mode and caching

Inside the editor's canvas every query reads the draft rows: an unpublished article shows in the index grid as it will after publish. On the public site queries read published rows only and are cached; publishing an entry, a global or a page expires the queries that showed it, so the live site updates at once. A list is tagged by its collection and by every collection its references resolved into, so editing an author refreshes the article lists that show that author.

Next, Ordering.

Edit this page on GitHubLast updated 13 Nov 2026