# Queries

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

## The read API

**Astro**

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`:

File: `src/live.config.ts`

```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`:

File: `src/page-types/articlesIndex.astro`

```astro
---
import { getLiveCollection } from "astro:content";
// …
const { entries = [] } = await getLiveCollection("articles", { locale: page.locale });
---
```

| Name | Description |
| --- | --- |
| `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.

**Next.js**

`smoodly/server.ts` exports `q`, a set of read functions typed by the collections and globals you registered:

File: `smoodly/server.ts`

```ts
export const q = (): Queries =>
  new Proxy({} as Queries, {
    get: (_, name) => async (...args: unknown[]) => {
      await buildGate();
```

Each call passes the build gate before it reads the keys: while `next build` prerenders it waits for a request, so the build needs no keys; at run time it does nothing, so a page that calls `q()` stays cacheable.

Call it in a server component, a page type's view or a route:

File: `components/pages/Articles.tsx`

```tsx
import { q } from "@/smoodly/server";
// …
  const items = await q().getEntries("articles", { locale });
```

| Name | Description |
| --- | --- |
| `getEntries(collection, options)` | Published entries of a collection, in the collection's order. Options: locale, where, order, limit, offset, parent. |
| `getEntry(collection, idOrPath, options)` | One entry by id or by its URL path, with its references resolved. |
| `getGlobal(name, options)` | A global's value in a language, for a layout or a page frame. |
| `getPage(pathOrId, options)` | A page by URL path or id. |
| `getPageTree(options)` | The published page tree in a language, each item with its page fields, for a navigation. |

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.

| Read | Shape |
| --- | --- |
| `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:

**Astro**

File: `src/page-types/articlesIndex.astro`

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

**Next.js**

File: `components/pages/Articles.tsx`

```tsx
          {items.map((entry) => (
            <ArticleCard key={entry.id} article={entry.fields} url={url(entry.path!)} locale={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](https://smoodly.io/docs/fields/reference-and-tags.md) 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:

**Astro**

File: `src/entry-pages/articles.astro`

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

**Next.js**

File: `components/RecentNews.tsx`

```ts
import { q } from "@/smoodly/server";

export async function recentNews(locale: string) {
  const items = await q().getEntries("articles", { locale, where: { date: "2026-09-02" }, limit: 3 });
  return items.map((item) => item.fields.title);
}
```

`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.

**Astro**

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.

**Next.js**

File: `components/ArticlePage.tsx`

```ts
import { q } from "@/smoodly/server";

export async function articlePage(locale: string, page: number, perPage = 10) {
  const items = await q().getEntries("articles", { locale, limit: perPage + 1, offset: (page - 1) * perPage });
  return { items: items.slice(0, perPage), hasNext: items.length > perPage };
}
```

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](https://smoodly.io/docs/collections/ordering.md).
