Skip to main content
Forest includes a free-text search bar on every collection’s table view. By default it searches across text, enum, number, and UUID fields. You can configure exactly which fields are searched, what operators are used, and even replace the default behavior entirely with custom logic.

​
How Search Works

When an operator types in the search bar, Forest sends a query to your back-end with the search string. The back-end applies it as a filter against your data source and returns matching records. Two search modes exist:
  • Normal search, searches fields in the current collection
  • Extended search, also searches fields in directly related collections. Operators can trigger extended search from the footer when normal results are empty.

​
Default Search Behavior

By default, Forest searches only specific field types:
Field typeDefault behavior
StringField contains the search string (case-insensitive)
EnumField equals the search string (case-insensitive)
NumberField equals the search string (if numeric)
UUIDField equals the search string
Other typesField is ignored

​
Replacing the Search Handler

Use replaceSearch in your back-end configuration to define exactly how search strings are translated into filters.
For large datasets, limit searchable fields to columns with database indexes. Searching unindexed fields causes full table scans.
In Node.js and Python, the handler receives a context with the generateSearchFilter helper. In Ruby, the replace_search block receives (search_string, extended_search) and returns a condition tree directly: there is no generate_search_filter helper, so you build the tree yourself.

​
Restricting Which Fields Are Searched

agent.customizeCollection('people', collection => {
  collection.replaceSearch((searchString, extendedMode, context) => {
    return context.generateSearchFilter(searchString, {
      extended: extendedMode,
      onlyFields: ['firstName', 'lastName', 'email'],
    });
  });
});

agent.customizeCollection('people', collection => {
  collection.replaceSearch((searchString, extendedMode, context) => {
    return context.generateSearchFilter(searchString, {
      extended: extendedMode,
      excludeFields: ['internalNotes', 'legacyId'],
    });
  });
});
Different search logic depending on what the operator is searching for: 
const referenceRegexp = /^[a-f]{16}$/i;
const barcodeRegexp = /^[0-9]{10}$/;

agent.customizeCollection('products', collection => {
  collection.replaceSearch(async (searchString, extendedMode, context) => {
    if (referenceRegexp.test(searchString))
      return { field: 'reference', operator: 'Equal', value: searchString };

    if (barcodeRegexp.test(searchString))
      return { field: 'barCode', operator: 'Equal', value: searchString };

    if (!extendedMode)
      return context.generateSearchFilter(searchString, { onlyFields: ['name'] });

    return context.generateSearchFilter(searchString, {
      onlyFields: ['name', 'description', 'brand:name'],
    });
  });
});

​
Integrating an External Search Engine

If your data is indexed in Algolia, Elasticsearch, or another service, call it directly in the search handler: 
const algoliasearch = require('algoliasearch');
const client = algoliasearch('APPLICATION_ID', 'API_KEY');
const index = client.initIndex('products');

agent.customizeCollection('products', collection =>
  collection.replaceSearch(async (searchString) => {
    const { hits } = await index.search(searchString, {
      attributesToRetrieve: ['id'],
      hitsPerPage: 50,
    });

    return { field: 'id', operator: 'In', value: hits.map(h => h.id) };
  })
);
To remove the search bar from a collection entirely: 
agent.customizeCollection('products', collection => {
  collection.disableSearch();
});
This is useful for collections where free-text search doesn’t apply, for example, collections that only display computed or joined data.