Select

By default, FrogBot’s APIs return all fields for a collection. You may only need a few fields for a given query. With the Select API, you can define exactly which fields you’d like to retrieve. This can impact the performance of your queries by affecting the load on the database and the size of the response.

Local API

To specify select in the Local API, you can use the select option in your query:

import type { FrogBot } from 'frogbot'

// Include mode - result type will only contain: id, text, group.number, and array
const getPosts = async (frogbot: FrogBot) => {
  const posts = await frogbot.find({
    collection: 'posts',
    overrideAccess: true,
    select: {
      text: true,
      // select a specific field from group
      group: {
        number: true,
      },
      // select all fields from array
      array: true,
    },
  })

  return posts
}

// Exclude mode - result type will contain all fields except: array and group.number
const getPosts = async (frogbot: FrogBot) => {
  const posts = await frogbot.find({
    collection: 'posts',
    overrideAccess: true,
    // Select everything except for array and group.number
    select: {
      array: false,
      group: {
        number: false,
      },
    },
  })

  return posts
}

Empty select

The id field is always included in the result, regardless of your select query. If you pass an empty select object, only the id will be returned:

const post = await frogbot.findByID({
  collection: 'posts',
  overrideAccess: true,
  id: '1',
  select: {},
})

console.log(post) // { id: '1' }

To perform querying with select efficiently, FrogBot implements your select query on the database level. Because of that, your beforeRead and afterRead hooks may not receive the full doc. To ensure that some fields are always selected for your hooks / access control, regardless of the select query, use a select function on your Collection config.

Entity-level select config

Collections and globals accept a top-level select function that runs before every read and returns the select to apply, replacing the caller’s. It receives { operation, req, select }; return undefined to keep the caller’s select. Use it to make sure hooks and access control always get a field, or to send admin requests less data than API requests. The function runs before the read, so it can’t see the document.

import type { CollectionConfig } from 'frogbot'

export const Posts: CollectionConfig = {
  slug: 'posts',
  // Always include `title`, regardless of the caller's `select`.
  select: ({ select }) => (select ? { ...select, title: true } : undefined),
  fields: [
    // ...
  ],
}

The returned object replaces the caller’s select instead of merging with it, so spread the caller’s select in when you only want to add fields.

REST API

To specify select in the REST API, you can use the select parameter in your query:

fetch(
  'https://localhost:3000/api/posts?select[color]=true&select[group][number]=true',
)
  .then((res) => res.json())
  .then((data) => console.log(data))

To understand the syntax, you need to understand that complex URL search strings are parsed into a JSON object. This one isn’t too bad, but more complex queries get unavoidably more difficult to write. For this reason, we recommend to use the extremely helpful and ubiquitous qs-esm package to parse your JSON / object-formatted queries into query strings:

import { stringify } from 'qs-esm'
import type { Where } from 'frogbot'

const select: Where = {
  text: true,
  group: {
    number: true,
  },
  // This query could be much more complex
  // and QS would handle it beautifully
}

const getPosts = async () => {
  const stringifiedQuery = stringify(
    {
      select, // ensure that `qs` adds the `select` property, too!
    },
    { addQueryPrefix: true },
  )

  const response = await fetch(
    `http://localhost:3000/api/posts${stringifiedQuery}`,
  )
  // Continue to handle the response below...
}

defaultPopulate collection config property

The defaultPopulate property allows you specify which fields to select when populating the collection from another document. This is especially useful for links where only the slug is needed instead of the entire document. With this feature, you can dramatically reduce the amount of JSON populated from Relationship or Upload fields. For example, in your content model, you might have a Link field which links out to a different page. When you go to retrieve these links, you really only need the slug of the page. Loading all of the page content, its related links, and everything else is going to be overkill and will bog down your FrogBot APIs. Instead, you can define the defaultPopulate property on your Pages collection, so that when FrogBot “populates” a related Page, it only selects the slug field and therefore returns significantly less JSON:

import type { CollectionConfig } from 'frogbot'

// The TSlug generic can be passed to have type safety for `defaultPopulate`.
// If avoided, the `defaultPopulate` type resolves to `SelectType`.
export const Pages: CollectionConfig<'pages'> = {
  slug: 'pages',
  // Specify `select`.
  defaultPopulate: {
    slug: true,
  },
  fields: [
    {
      name: 'slug',
      type: 'text',
      required: true,
    },
  ],
}

When using defaultPopulate on a collection with Uploads enabled and you want to select the url field, it is important to specify filename: true as well, otherwise FrogBot will not be able to construct the correct file URL, instead returning url: null.

Populate

Setting defaultPopulate will enforce that each time FrogBot performs a “population” of a related document, only the fields specified will be queried and returned. However, you can override defaultPopulate with the populate property in the Local and REST API: Local API:

import type { FrogBot } from 'frogbot'

const getPosts = async (frogbot: FrogBot) => {
  const posts = await frogbot.find({
    collection: 'posts',
    overrideAccess: true,
    populate: {
      // Select only `text` from populated docs in the "pages" collection
      // Now, no matter what the `defaultPopulate` is set to on the "pages" collection,
      // it will be overridden, and the `text` field will be returned instead.
      pages: {
        text: true,
      },
    },
  })

  return posts
}

REST API:

fetch('https://localhost:3000/api/posts?populate[pages][text]=true')
  .then((res) => res.json())
  .then((data) => console.log(data))

Start here

Basics

Managing Data

Features

Ecosystem

Deployment

Local API

Empty select

Entity-level select config

REST API

defaultPopulate collection config property

Populate

​Local API

​Empty select

​Entity-level select config

​REST API

​defaultPopulate collection config property

​Populate

Local API

Empty select

Entity-level select config

REST API

defaultPopulate collection config property

Populate