> ## Documentation Index > Fetch the complete documentation index at: https://forest-docs-search-extended-search-permission-check.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Search Configuration > Configure which fields are searchable in your collections, how search behaves, and how to extend or replace the default search logic. 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. Extended search reaches columns outside the current collection, so the Node.js agent checks each related collection it reads against the operator's `read` permission. From version 1.97.3 on, the agent refuses an extended search whose fields it cannot enumerate ahead of the query. This governs how you replace the search handler — see [Replacing the Search Handler](#replacing-the-search-handler). ## Default Search Behavior By default, Forest searches only specific field types: | Field type | Default behavior | | ----------- | --------------------------------------------------- | | `String` | Field contains the search string (case-insensitive) | | `Enum` | Field equals the search string (case-insensitive) | | `Number` | Field equals the search string (if numeric) | | `UUID` | Field equals the search string | | Other types | Field is ignored | ## Replacing the Search Handler Use `replaceSearch` in your back-end configuration to define exactly how search strings are translated into filters. The Node.js agent accepts two forms, and they differ in what extended search does: | Form | Extended search | Read permissions on the fields it reads | | --------------------------------------------------- | --------------- | --------------------------------------------------------------------------------------- | | **Field selection** — an object listing the fields | Works | Checked per field; a field whose collection the operator cannot read is refused by name | | **Handler** — a function returning a condition tree | Returns 403 | Not checked on normal search | Reach for a field selection whenever the fields are a fixed list. Reach for a handler when the filter depends on the search string itself, on an external service, or on anything else a list cannot express — and accept that extended search stops working on that collection. **Node.js agent 1.97.3 and later refuse extended search on any collection with a handler.** The agent cannot enumerate which fields a handler reads, so it cannot check them against the operator's `read` permission, and it returns: ``` You cannot run an extended search on the 'products' collection: the fields it reaches cannot be determined, so they cannot be checked against your permissions. ``` Normal search keeps working. Converting the handler to a field selection restores extended search, and requires `@forestadmin/datasource-customizer` 1.71.3 or later. For large datasets, limit searchable fields to columns with database indexes. Searching unindexed fields causes full table scans. The field selection form exists in Node.js only. In Python, the handler receives a `context` with the `generate_search_filter` helper. In Ruby, the `replace_search` block receives `(search_string, extended_search)` and returns a [condition tree](/get-started/connect/relationships-schema) directly: there is no `generate_search_filter` helper, so you build the tree yourself. The Ruby and Python agents do not refuse extended search on a collection with a handler. ### Restricting Which Fields Are Searched ```javascript Node.js / Cloud theme={null} agent.customizeCollection('people', collection => { collection.replaceSearch({ onlyFields: ['firstName', 'lastName', 'email'], }); }); ``` ```ruby Ruby theme={null} include ForestAdmin::Types @create_agent.customize_collection('people') do |collection| collection.replace_search do |search_string, extended_search| { aggregator: 'Or', conditions: ['firstName', 'lastName', 'email'].map do |field| { field: field, operator: Operators::I_CONTAINS, value: search_string } end } end end ``` ```ruby Ruby DSL theme={null} include ForestAdmin::Types @create_agent.collection :people do |collection| collection.replace_search do |search_string, extended_search| { aggregator: 'Or', conditions: ['firstName', 'lastName', 'email'].map do |field| { field: field, operator: Operators::I_CONTAINS, value: search_string } end } end end ``` ```python Python theme={null} def search_in_people(search_string, extended_search, context): return context.generate_search_filter( search_string, extended=extended_search, only_fields=["firstName", "lastName", "email"], ) agent.customize_collection("people").replace_search(search_in_people) ``` ### Excluding Fields from Default Search ```javascript theme={null} agent.customizeCollection('people', collection => { collection.replaceSearch({ excludeFields: ['internalNotes', 'legacyId'], }); }); ``` A field selection also accepts `includeFields`, which adds fields to the default set instead of replacing it. Paths cross relations with a colon, at any depth: `includeFields: ['company:owner:email']`. The agent checks the collection each path ends on — `companies` confers nothing here, `users` needs the `read` permission. A path crossing a `ManyToMany` relation does not resolve and is dropped from the selection without an error; `ManyToOne`, `OneToOne` and `OneToMany` segments all resolve. A field selection narrows the fields on normal search as well as extended search, so the fields it names are checked against the operator's `read` permission on both. An operator who searches `people` without `read` on a collection an included path ends on receives a 403 where a handler returned results. Grant that permission, or drop the path from the selection. ### Context-Dependent Search Different search logic depending on what the operator is searching for. This needs a handler, so extended search returns 403 on the collection: ```javascript Node.js / Cloud theme={null} 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'], }); }); }); ``` ```ruby Ruby theme={null} include ForestAdmin::Types REFERENCE_REGEXP = /\A[a-f]{16}\z/i BARCODE_REGEXP = /\A[0-9]{10}\z/ @create_agent.customize_collection('products') do |collection| collection.replace_search do |search_string, extended_search| next { field: 'reference', operator: Operators::EQUAL, value: search_string } if REFERENCE_REGEXP.match?(search_string) next { field: 'barCode', operator: Operators::EQUAL, value: search_string } if BARCODE_REGEXP.match?(search_string) fields = extended_search ? ['name', 'description', 'brand:name'] : ['name'] { aggregator: 'Or', conditions: fields.map do |field| { field: field, operator: Operators::I_CONTAINS, value: search_string } end } end end ``` ```ruby Ruby DSL theme={null} include ForestAdmin::Types REFERENCE_REGEXP = /\A[a-f]{16}\z/i BARCODE_REGEXP = /\A[0-9]{10}\z/ @create_agent.collection :products do |collection| collection.replace_search do |search_string, extended_search| next { field: 'reference', operator: Operators::EQUAL, value: search_string } if REFERENCE_REGEXP.match?(search_string) next { field: 'barCode', operator: Operators::EQUAL, value: search_string } if BARCODE_REGEXP.match?(search_string) fields = extended_search ? ['name', 'description', 'brand:name'] : ['name'] { aggregator: 'Or', conditions: fields.map do |field| { field: field, operator: Operators::I_CONTAINS, value: search_string } end } end end ``` In Node.js the `extendedMode` branch of this example never runs from version 1.97.3 on: the agent refuses the extended search before the handler executes. The Ruby example still reaches its `extended_search` branch. To keep an extended search on a collection like this one, split the fixed part of the field list into a field selection and drop the handler, or accept normal search only. ### Integrating an External Search Engine If your data is indexed in Algolia, Elasticsearch, or another service, call it directly in the search handler. Extended search returns 403 on such a collection in Node.js, since the agent cannot know which columns the external index reads: ```javascript Node.js / Cloud theme={null} 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) }; }) ); ``` ```ruby Ruby theme={null} require 'algolia' client = Algolia::Search::Client.create('APPLICATION_ID', 'API_KEY') index = client.init_index('products') @create_agent.customize_collection('products') do |collection| collection.replace_search do |search_string, extended_search| hits = index.search(search_string, { attributesToRetrieve: ['id'], hitsPerPage: 50 })['hits'] { field: 'id', operator: 'In', value: hits.map { |hit| hit['id'] } } end end ``` ```ruby Ruby DSL theme={null} require 'algolia' client = Algolia::Search::Client.create('APPLICATION_ID', 'API_KEY') index = client.init_index('products') @create_agent.collection :products do |collection| collection.replace_search do |search_string, extended_search| hits = index.search(search_string, { attributesToRetrieve: ['id'], hitsPerPage: 50 })['hits'] { field: 'id', operator: 'In', value: hits.map { |hit| hit['id'] } } end end ``` ```python Python theme={null} from algoliasearch.search_client import SearchClient client = SearchClient.create("APPLICATION_ID", "API_KEY") index = client.init_index("products") async def search_products(search_string, extended_search, context): results = index.search(search_string, {"attributesToRetrieve": ["id"], "hitsPerPage": 50}) ids = [hit["id"] for hit in results["hits"]] return ConditionTreeLeaf("id", "in", ids) agent.customize_collection("products").replace_search(search_products) ``` ## Disabling Search To remove the search bar from a collection entirely: ```javascript Node.js / Cloud theme={null} agent.customizeCollection('products', collection => { collection.disableSearch(); }); ``` ```ruby Ruby theme={null} @create_agent.customize_collection('products') do |collection| collection.disable_search end ``` ```ruby Ruby DSL theme={null} @create_agent.collection :products do |collection| collection.disable_search end ``` ```python Python theme={null} agent.customize_collection("products").disable_search() ``` This is useful for collections where free-text search doesn't apply, for example, collections that only display computed or joined data. ## Limitations **A handler gives up extended search in Node.js.** A field selection is the only form the agent can enumerate, so it is the only form that keeps extended search on the collection. A handler whose filter genuinely depends on the search string, on an external index, or on a runtime lookup has no equivalent field selection, and extended search stays refused there. Normal search is unaffected. **A field selection replaces a datasource's native search.** On a collection whose datasource searches natively — one calling `enableSearch()`, which no Forest-maintained datasource does — a field selection does not narrow that native search: the agent takes the search over and runs its own per-column one on the selected fields. Matching semantics change with it. **Version requirements.** The refusal starts at `@forestadmin/agent` 1.97.3. The field selection form requires `@forestadmin/datasource-customizer` 1.71.3, shipped in `@forestadmin/agent` 1.98.3. **Agents differ.** The table below states where each behavior applies today: | Agent | Field selection form | Extended search with a handler | | ------------------------- | -------------------- | ------------------------------ | | Node.js, from 1.98.3 | Available | Refused with a 403 | | Node.js, 1.97.3 to 1.98.2 | Not available | Refused with a 403 | | Node.js, before 1.97.3 | Not available | Served | | Ruby | Not available | Served | | Python | Not available | Served | **A handler is exempt from read permissions on normal search.** The operator supplies the text and the handler chooses the fields, so the agent cannot separate a field the customization intended from one the operator's role may not read. A handler pointing at a column of a collection the role cannot read lets that role test values against it, reading each answer from whether rows come back. Prefer a field selection wherever the fields are a fixed list.