Skip to content
XenonDocs
Esc
    GitHub
    Docs

    Querying content

    Query published and draft content using the type-safe Local API directly in Next.js Server Components.

    On this page

    Server Component queries

    You can fetch documents directly on the server without making HTTP requests.

    src/app/posts/page.tsx
    import { getXenon } from "xenon-cms/next";
    import config, { type Post } from "@/xenon.config";
    
    export default async function PostsPage() {
      const { docs, totalDocs, totalPages } = await getXenon(config).find({
        collection: "posts",
        sort: "-createdAt",
        limit: 10,
        page: 1,
      });
    
      const posts = docs as Post[];
    
      return (
        <main>
          <h1>Articles ({totalDocs})</h1>
          <ul>
            {posts.map((post) => (
              <li key={post.id}>{post.title}</li>
            ))}
          </ul>
        </main>
      );
    }

    The getXenon(config) function returns a memoized database instance that executes SQL queries directly within the Next.js server runtime.

    Query methods

    The Local API provides three read operations:

    find

    Queries multiple documents with filtering, sorting, and pagination.

    TypeScript
    const result = await getXenon(config).find({
      collection: "posts",
      where: { category: { equals: "engineering" } },
      sort: "-createdAt",
      limit: 20,
      page: 1,
    });

    Returns { docs, totalDocs, limit, page, totalPages, hasNextPage, hasPrevPage }.

    findById

    Fetches a single document by its UUID.

    TypeScript
    const post = await getXenon(config).findById({
      collection: "posts",
      id: "01934c90-9c44-7000-8432-123456789abc",
    });

    Returns the document if found, or null.

    findBySlug

    Fetches a single document by its generated slug.

    TypeScript
    const post = await getXenon(config).findBySlug({
      collection: "posts",
      slug: "announcing-xenon",
    });

    Returns the document if found, or null.

    Filtering with where clauses

    Filter documents using field conditions, comparison operators, and boolean logic.

    TypeScript
    const filtered = await getXenon(config).find({
      collection: "posts",
      where: {
        category: { in: ["engineering", "design"] },
        readingTime: { lte: 10 },
        and: [
          { status: { equals: "published" } },
          { views: { gt: 100 } },
        ],
      },
    });

    Supported operators:

    OperatorTargetDescription
    equalsScalarExact equality check. equals: null matches missing or null values.
    not_equalsScalarNegation of equality.
    inArrayMatches if field value equals any element in the array.
    not_inArrayNegation of in.
    containsString / ArraySubstring match on strings (case-insensitive); element match on arrays.
    gt, gte, lt, lteNumber / StringNumeric comparison on numbers; code-point comparison on strings.
    existsBooleanChecks whether the field exists and is non-null.
    and, orWhere[]Logical AND / OR groupings.

    Sorting and pagination

    Prefix a field key with - to sort in descending order.

    TypeScript
    const sorted = await getXenon(config).find({
      collection: "posts",
      sort: "-createdAt", // descending by creation date
      limit: 25,          // 0 returns all documents
      page: 2,
    });

    Ties in custom sort keys are broken by id ascending to ensure stable pagination across pages.

    Next steps