# Search with Algolia

> How CMS Orbit keeps published pages in Algolia: the index names, the shape of each record, when records change, and how to query them from your website.

Source: https://docs.bifrostorbit.com/cms/developers/algolia/

When the organisation has connected Algolia in Orbit under **Connections** (Growth or higher), CMS Orbit writes every published page of every space to your Algolia app. Your website searches Algolia directly with its own search-only key; CMS Orbit only writes.

## Index names

One index for each space, environment and language:

```
<prefix>_<space>_<environment>_<language>
```

- `prefix` is the index prefix set in Orbit, such as `northwilds`.
- `space` is the space's slug, `environment` the environment's key and `language` the locale code, such as `en-gb` or `nb`.

Everything is in lower case, and anything other than letters, digits and hyphens becomes a hyphen. The Northwilds website's English pages in production are in `northwilds_website_production_en-gb`, and the same pages on staging in `northwilds_website_staging_en-gb`. Regions that share a language share its index; filter on `region` to tell them apart. **Settings** in the space lists the indices.

## Records

Each published page is one record, with the page's id as `objectID`:

```json
{
  "objectID": "6a1f0c2b9d4e8f7a6b5c4d3e",
  "title": "Lofoten ridge",
  "name": "Lofoten ridge",
  "description": "Five days along the ridge above the fjord, sleeping in mountain huts.",
  "path": "/trips/lofoten-ridge",
  "url": "https://northwilds.com/trips/lofoten-ridge",
  "locale": "en-GB",
  "region": "europe",
  "contentType": "trip",
  "publishedAt": "2026-11-16T09:00:00.000Z",
  "publishedAtTimestamp": 1794819600,
  "text": "Walk the Lofoten ridge & sleep in huts.\nAbove the Arctic Circle"
}
```

- `title` is the page's SEO title, or its name when it has none. `description` is the SEO description.
- `url` is the full address on the domain for the page's region and language, or the path when the space has no domain or preview address.
- `text` holds the words of the page's Text, Long text and Rich text fields, including those in components, with the HTML removed. Other field types are left out.
- Records stay under 10 KB, Algolia's limit on its smallest plans; long text is shortened.

Only published pages are written: drafts, global entries, entries without an address and pages marked **Hide from search engines** are not.

## When records change

CMS Orbit updates the index from the same events as [webhooks](https://docs.bifrostorbit.com/cms/developers/events/): `cms.page.published`, `cms.page.rolledBack`, `cms.page.promoted`, `cms.page.unpublished`, `cms.page.trashed`, `cms.page.restored`, `cms.page.purged`, `cms.release.published` and `cms.folder.moved`. A page that is no longer published is deleted from the index. If Algolia doesn't answer, the change is tried again later, like any other event.

**Rebuild index** in the space's **Settings** writes every index again. It fills a temporary index, `<index>_rebuild`, with your index's settings, synonyms and rules, and moves it into place when it is ready, so search keeps working throughout.

## Configure the index

CMS Orbit never changes an index's settings, so set them in Algolia once:

- **Searchable attributes:** `title`, `description`, `text`.
- **Attributes for faceting:** `contentType`, `region`, `locale`.
- **Custom ranking:** `desc(publishedAtTimestamp)` to prefer newer pages.

## Query from your website

Use a search-only API key, never the admin key you gave Orbit:

```ts
import { liteClient } from 'algoliasearch/lite'

const search = liteClient('NW4LGOL1A', '<search-only key>')

const { results } = await search.search({
  requests: [{ indexName: 'northwilds_website_production_en-gb', query: 'lofoten', hitsPerPage: 10, attributesToSnippet: ['text:30'] }],
})
```

Each hit has the page's `title`, `url` and a snippet of its `text`, enough for a results list. Fetch the full page from the [delivery API](https://docs.bifrostorbit.com/cms/developers/delivery-api/) by its `path` when you need more.

For search by meaning across languages without a third party, see [Search by meaning](https://docs.bifrostorbit.com/cms/developers/search/).
