Search

One search index and one callable serve every search box: the public header, the /search page, the admin header and any box you add. Content is searchable out of the box; you make any other collection searchable by naming it in one file.

What it is

Search is a type-ahead engine built on Firestore. It is good at short fields: names, titles, summaries, cities, product names. Typing "kar" finds "Karun", words match in any order, accents and case are ignored, and a typo fallback retries a query that finds nothing. It is not full-text search over long prose: there is no stemming, no synonyms and no match in the middle of a word.

For a website walkthrough, see Add search.

Turn it on or off

Search is the switchable feature search. It is on by default and needs no other feature. To turn it off, list it in src/custom/features.ts:

export const CUSTOM_FEATURES: FeatureChoice = {
    off: ['search'],
};

When it is off:

• Admin, Settings, Search, the admin header box and /admin/search go.
• The public header box shows nothing, and /search and /{lang}/search show the not-found page.
• The editor's Checks tab offers no link suggestions, and content pages have no Related items.
• Every search function goes at the next deploy of the whole functions codebase.
• The SearchIndex collection stays. Turn search back on, deploy, and press Rebuild everything.

The public header box also needs content: without content there is nothing public to find, so an app without content places its own box. See Feature ids for every feature.

Set it up

Content needs no setup. Published content and drafts are indexed as they are saved and published, in every language the item has. Each content entry indexes its title, summary and author name.

1. Choose extra content fields (optional). In Content, Content types, edit a type and tick fields under Searchable custom fields. Only plain text fields can be ticked; rich text is never indexed. Saving the type rebuilds its part of the index.

2. Build the index once. On a site that has content from before search was deployed, open Admin, Settings, Search and press Rebuild everything. Do the same whenever results look wrong: a rebuild rewrites every entry and deletes entries whose document is gone.

To make another collection searchable, see Extend it.

Use it

Public search

The site header carries <arc-search>. On a published page it becomes a plain form that submits to /search?q= (or /{lang}/search?q=), so it works without JavaScript, and public/assets/js/arc-search.js adds the type-ahead. In the Angular app it is the arc-search-box component. Both search the language being viewed. The box text comes from the site's strings files (src/custom/site/strings/{lang}.json over public/_site/strings/{lang}.json) (keys starting with search_); see Languages.

Admin search

Admins get a search box in the page header. Cmd+K or Ctrl+K focuses it. It searches drafts (not published content, which would show each item twice) and every source admins may read, in every language at once, showing each document once. Enter opens /admin/search with up to 20 results. Without content, the box appears once some source has been rebuilt.

Search settings

Admin, Settings, Search lists what is searchable (with the fields each source indexes, its document and entry counts and a Rebuild button) and every collection in the database with its state:

How results are ranked

For each word of the query, the best match in any indexed field counts: a whole word scores the field's weight, the start of a word scores 0.6 times the weight. Then:

1. A bonus of 4 when every word matched.
2. A bonus of twice the highest field weight when the whole query appears in the title.
3. A small bonus for short titles fully matched, so they beat long titles partly matched.
4. The total is multiplied by the source's boost. Ties go to the newest document.

When nothing matches, the shortest query word of four or more letters loses its last letter and the search runs again, at most twice and never below three letters. The box then says "Showing results for" the shortened word.

Text is lowercased, Latin accents are removed (other scripts keep their marks, so Hindi works), apostrophes are dropped ("karun's" becomes "karuns"), other punctuation becomes a space, and a short list of English stop words is ignored. The same code tokenizes documents and queries, in functions/src/search/tokenizer.ts.

Limits

Extend it

An app makes its own collections searchable in functions/src/custom/search-sources.ts. It exports two lists:

Each named collection, and each code source on one collection, gets its own trigger, arccms-searchSync-{Collection}, which keeps the index in step with every write. A write to any other collection starts no search function. Adding or removing a collection therefore needs a functions deploy; changing its setup in the admin does not.

Name a collection

1. Add its name to functions/src/custom/search-sources.ts:

   export const SEARCH_COLLECTIONS: string[] = ['Directory'];

2. Deploy the functions:

   npm run deploy -- --only functions:arccms

   To deploy less, see Deploy only what changed.

3. In Admin, Settings, Search, press Set up on the collection. It reads up to 20 documents and lists their text fields (strings and lists of strings, at the top level and one level into maps, such as address.city). It ticks a first guess: fields named like title, name, subject, heading or label at High, fields named like summary, description, text, body or notes at Normal, the first of each as the result's title and snippet. Nothing else is ticked.

4. Check the fields (High counts three times as much as Normal and matches as you type), the title and snippet, the link, and Who can search it (Admins by default). The link is a pattern such as /directory/{slug}: {id} is the document id and {field} a field's value. Leave it empty for results that do not open. Look at the preview, then press Save and rebuild.

An admin can also set a collection up before the developer names it: it then waits, and is indexed after the name is added and the functions are deployed.

Write a source in code

Copy functions/src/search/sources/_template.ts into functions/src/custom/. For a Directory collection whose documents look like { name, tagline, city, slug, status, createdAt }:

// functions/src/custom/directory-source.ts
import type { SearchSource } from '../search/source.js';

export const directorySource: SearchSource = {
    id: 'directory',
    label: 'Directory',
    collection: 'Directory',
    scope: 'public',
    fields: [
        { path: 'name', weight: 3, prefix: true },
        { path: 'tagline', weight: 2, prefix: true },
        { path: 'city', weight: 1 },
    ],
    display: (doc) => ({
        title: String(doc['name'] ?? ''),
        snippet: String(doc['tagline'] ?? ''),
        badge: 'Directory',
        link: `/directory/${String(doc['slug'] ?? '')}`,
        sortAt: doc['createdAt'],
    }),
    include: (doc) => doc['status'] === 'active',
};

List it in functions/src/custom/search-sources.ts, deploy the functions, then press Rebuild on it in Admin, Settings, Search, where it shows as Set up in code:

import type { SearchSource } from '../search/source.js';
import { directorySource } from './directory-source.js';

export const SEARCH_COLLECTIONS: string[] = [];
export const CUSTOM_SEARCH_SOURCES: SearchSource[] = [directorySource];

Arc CMS ships one ready-made source you can list the same way: productsSource in functions/src/search/sources/products.ts makes plans on the pricing page searchable.

The source fields

The contract is SearchSource in functions/src/search/source.ts.

Index from your own function

When your Cloud Function writes the data, you can index in the same operation and set trigger: false on the source:

import { buildSearchContext } from '../search/context.js';
import { indexDocument, removeSearchEntries } from '../search/writer.js';
import { directorySource } from './directory-source.js';

const ctx = await buildSearchContext('Directory', docId);
await indexDocument(directorySource, data, ctx);            // write or update
await removeSearchEntries('directory', 'Directory', docId); // on delete

Put a search box on a page

Import SearchBoxComponent from src/shared/components/search-box/search-box.component.ts:

<arc-search-box
    scope="public"
    [sources]="['directory']"
    resultsUrl="/directory/search"
    navigation="router"
    placeholder="Search the directory"
    (picked)="onPicked($event)"></arc-search-box>

Without the component, inject SearchService from src/app/core/services/search.service.ts and call search({ q, lang, scope, sources, limit }). It returns { results, tookMs, fallbackUsed? }, or null when a newer search overtook it. Each result has title, snippet, badge, link, meta, score and highlights (character ranges to bold). The types are in src/shared/models/search.model.ts.

Test a source

A source is plain data. A spec can call buildEntries from functions/src/search/writer.ts with a fixture document and check the tokens and the display.

What it stores

Search uses no Storage. Its Cloud Functions:

Each deploys with the arccms- prefix. Publishing, unpublishing and deleting a content type update the content entries themselves. See Cloud Functions.

Who can do what

A request that names a source its scope cannot reach is refused with permission-denied, not quietly trimmed. See Roles and claims.

Troubleshooting