Structural

Structural Querying

Use top-level properties to define the scope of your query. This allows you to retrieve entries based on their structural identity such as content type, unique ID or their specific location in the project tree.

1. Using default fields

const pageIds = ['abc123', 'def456', 'ghi789']
await cms.first({
  // Filter by the schema.
  type: BlogPostSchema,

  // When you know the unique id
  id: pageId,
  // You can also use operations in these fields
  id: {in: pageIds},
  id: {notIn: pageIds},

  // Using the path (e.g. querying).
  path: pagePath,

  // Using the url (e.g. docs/content/query)
  url: pageUrl,
  // But sometimes you only need the URL to start with a certain prefix
  // instead of using javascript string manipulation you can use the startsWith field
  url: {startsWith: 'docs/content'}

  // Using the parents id
  parentId: pageParentId  
})

More information about possible operations

2. Using the location in the tree structure

await cms.first({
  // e.g. cms.workspaces.main
  workspace,
  // e.g. cms.workspaces.main.pages
  root,
  // Level: 0 = parent level, 1 = child level, 2 = grandchild level, ...
  level,

  // For Location you can use a Root, Workspace or a Page as input.
  // e.g. cms.workspaces.main | cms.workspaces.main.pages
  location
})

3. Miscellaneous

await cms.first({
  // This can be: 'published', 'draft', 'archived', 'preferDraft', 'preferPublished', 'all' 
  status: 'published',
  // Look for result with the exact locale.
  locale: pageLocale 
  // Look for a result with the locale, but ignore when there are no exact matches
  preferredLocale: pageLocale 
})

Output control

Once you've filtered the results, you can manipulate the output. This can be done in two ways:

1. Data

await cms.first({
  // Return everything from the related type
  type: BlogPostSchema,
  id: BlogPostId
})

await cms.first({
  id: BlogPostId,
  // Only return the selected fields (similar to SQL's SELECT)  
  select: {
    title: Query.title,
    description: Query.description
  }
})

await cms.first({
  id: BlogPostId,
  select: {
    title: Query.title
  },
  // Use include to return extra fields that are not in the queried entry's schema
  include: {
    parent: Query.parent({
      select: {
        url: Query.url,
        title: Query.title
      }
    })
  }
}

2. Sorting

await cms.find({
  type: BlogPostSchema,
  select: {
    id: Query.id,
    title: Query.title
  },
  orderBy: {
    // Use desc or asc to sort by a specific field.
    desc: BlogPost.publishedDate,
    // This will sort the posts in alphabetical order
    asc: BlogPost.title
  },
  // Group results by 1 or more categories
  groupBy: BlogPost.category,

  //skip the first 10 results and return a max of 20
  skip: 10,
  take: 20
})

PreviousQuerying content

NextFiltering