Search

Meridian’s search is two halves. The engine owns the query, the locale, what a visitor may see, the query log, zero-result detection, click tracking and the results a template reads. Retrieval is always an external service you run: Meilisearch, Elasticsearch or OpenSearch. With no service configured, the same search page answers in browse mode: results filtered from the published content in the database, not ranked by relevance.

Add a search pageCopy Anchor Link

# config/sites/<site>/routes.yaml
special:
  search: "/search"

{% extends "base.html" %}
{% block body %}
<h1>Search</h1>
<form method="get" action="{{ request.path|url }}" role="search">
  <label for="q">What are you looking for?</label>
  <input id="q" type="search" name="q" value="{{ results.query }}">
  <button type="submit">Search</button>
</form>
{% if results.degraded %}<p role="status">Search is in browse mode: results are filtered, not ranked.</p>{% endif %}
{% if results.facets.type %}
<nav aria-label="Filter by type"><ul>
  {% for f in results.facets.type %}<li><a href="{{ request.path|url }}?q={{ results.query|urlencode }}&amp;type={{ f.value|urlencode }}">{{ f.label|default:f.value }} ({{ f.count }})</a></li>{% endfor %}
</ul></nav>
{% endif %}
{% if results.items %}
<p>{{ results.total }} results</p>
<ol>
  {% for item in results.items %}
  <li>
    <h2><a href="{{ item.clickUrl|default:item.uri|url }}">{{ item.title|default:item.uri }}</a></h2>
    {% if item.image %}{{ item.image.img("thumb") }}{% if item.image.credit %}<small>{{ item.image.credit }}</small>{% endif %}{% endif %}
    {% if item.highlight %}<p>{{ item.highlight }}</p>{% elif item.summary %}<p>{{ item.summary }}</p>{% endif %}
  </li>
  {% endfor %}
</ol>
{% if results.pagination.next %}<a rel="next" href="{{ results.pagination.next|url }}">Next page</a>{% endif %}
{% elif results.query %}
<p>Nothing matched that. Try a shorter phrase.</p>
{% endif %}
{% endblock %}

<header>{{ searchForm() }}</header>

The page is a plain GET form, so it works without JavaScript and every result page has a shareable address. Search pages are never cached, because each search is logged.

Connect a backendCopy Anchor Link

# config/engine.yaml
search:
  driver: meilisearch
  meilisearch:
    url: ${MEILISEARCH_URL}
    api_key: ${MEILISEARCH_API_KEY}     # a secret; set it empty for a server with no key
    index_prefix: riverside

# Elasticsearch, or OpenSearch with driver: opensearch and an opensearch: block
search:
  driver: elasticsearch
  elasticsearch:
    addresses: ["${ES_ADDRESS}"]        # only the first entry is used
    username: ${ES_USERNAME:-}
    password: ${ES_PASSWORD}
    index_prefix: riverside

Elasticsearch and OpenSearch authenticate with a username and password (HTTP basic authentication); an API key is not used by these drivers. addresses is a list, but the drivers send every request to its first entry only: point that entry at a load balancer or a coordinating node when the cluster has several.

Then build the index:

engine-dmo search status          # the backend, its health, what is indexed
engine-dmo search rebuild         # index everything published
engine-dmo search test "harbour walk" --site main

The engine creates one index per site and locale, named from index_prefix, with analysis for the locale’s language. Meilisearch needs url; Elasticsearch and OpenSearch need at least one entry in addresses. engine-dmo search capabilities lists what the configured backend supports.

What is indexedCopy Anchor Link

Every document that is published on a site in a locale and has an address there is indexed in that site and locale’s index. A type that is not on a site never reaches its index. There is no per-type switch: a type’s searchable key is accepted and has no effect, so to keep a type out of search, give it no route on that site. Each entry holds:

Indexing never holds up a publish. Publishing, unpublishing, trashing, restoring, sharing and unsharing each queue an index job for the document, and the index catches up within seconds. Hits that are no longer published are dropped from results even if the index has not caught up yet. A nightly sweep compares each index with what is published, by id and content digest, and repairs any drift; engine-dmo search verify runs the same comparison on demand.

The search routeCopy Anchor Link

The search route reads these query parameters:

A query shorter than search.min_query_length (2 by default, counted in characters as a reader sees them) is not sent to the backend and not logged: the page lists published documents in browse mode, which is what a search page with no q shows.

resultsCopy Anchor Link

search.html receives results:

Each item in results.items:

search() in any templateCopy Anchor Link

The search() function runs the same service from any page: a “nearby” panel, a type’s own search, a results block on a landing page. It is a chain, run by .paginate(n) (reads the page from the request’s page parameter) or .limit(n) (the first n):

{% set found = search(request.query.q).types(["event", "article"]).facets(["type"]).paginate(12) %}
{% if found.degraded %}<p role="status">Showing filtered results.</p>{% endif %}
{% for item in found.items %}<a href="{{ item.uri|url }}">{{ item.title }}</a>{% endfor %}

It returns the same object as results.

Browse modeCopy Anchor Link

Browse mode answers a search from the published projection in the database, through the same filter machinery as a type’s index page: type, tags and distance filters work, facet counts are computed, and results are ordered by the requested sort rather than by relevance.

It is used when:

• search.driver is none (the default);
• the query is shorter than min_query_length;
• the backend fails, or has failed circuit_breaker.failures times within circuit_breaker.window and is resting for circuit_breaker.cooldown, while degraded_mode is browse.

This is the path one request takes:

flowchart TD
  q["GET /search?q=..."] --> short{"q shorter than<br/>min_query_length?"}
  short -->|yes| browse0["Browse mode<br/>not logged, degraded false"]
  short -->|no| log["Log the query"]
  log --> backend{"Backend configured<br/>and breaker closed?"}
  backend -->|yes| ask["Ask the backend"]
  ask -->|answers| live["Drop hits no longer published"]
  live --> ranked["Ranked results<br/>degraded false"]
  ask -->|fails| mode{"degraded_mode"}
  backend -->|no| mode
  mode -->|browse| browse1["Browse mode<br/>degraded true"]
  mode -->|error| err["The site's error page"]

results.degraded is true whenever words were searched and no backend answered, including with driver: none; a short or empty query is browse mode with degraded false, because nothing was asked. With degraded_mode: error, a failed backend answers the page with the site’s error page instead.

What browse mode does not doCopy Anchor Link

Browse mode is a filter, not a search. Write search.html for it as well as for a backend, because a site without one serves it for every query:

• The words are not matched. q is logged and echoed in results.query, but every published document that passes the type, tag and distance filters is listed, in the requested sort (by title when none is given). Say so on the page when results.degraded is true.
• No highlight and no clickUrl. Link to item.clickUrl|default:item.uri.
• Empty titles and summaries show. As with a backend (see What is indexed), an unindexed summary and a type with no title give empty values, and browse mode lists such documents even though no words matched them. Print item.title|default:item.uri so every link has a name.
• Facet labels are empty, as they are with a backend: print f.label|default:f.value, or map the value to your own interface string.

Distance filters read the same location field in both modes, and result images and card fields (item.image, item.fields) are filled the same way.

SynonymsCopy Anchor Link

Synonyms are rules held in the database and pushed to each index’s settings; changing them reindexes nothing. A rule without from makes every term find every other; with from, a search for from also finds each term and not the reverse.

# config/search/synonyms.yaml: a seed, loaded once
synonyms:
  - { locale: en, terms: [gig, concert, performance] }
  - { locale: en, from: kids, terms: [family, children] }
  - { locale: en, sites: [main], terms: [beach, seafront, shore] }

engine-dmo seed apply and engine-dmo search synonyms import load the file; rules already held are left alone. After that, the admin’s Search synonyms screen owns them (search.synonyms). engine-dmo search synonyms list prints what the database holds. A rule without sites applies on every site that enables its locale. engine-dmo check warns when the file exists and no backend is configured.

The query log and zero resultsCopy Anchor Link

Every search of at least min_query_length is logged before the backend is asked: the words as typed, a folded form for grouping (so “Café”, “CAFE” and “cafe” are one row), the backend, the result count and whether it was degraded. No visitor identity is stored. Searches made by engine-dmo render and the warm job are not logged.

engine-dmo search zero-results --site main --since 30d --limit 50

The admin’s Insight search screen (analytics.view) shows the commonest searches, the zero-result searches, and the click-through and average position from clickUrl. Degraded searches are left out of the zero-result report. The log is kept for analytics.search_log_retention_days (400 by default). search.log_queries cannot be false in production.

Running the indexCopy Anchor Link

engine-dmo content reindex queues an index job for every published document, or one type’s. engine-dmo warm repairs the index after a deploy. All of these need the database.

The admin’s Search index screen (search.view) shows each index’s count against what is published, the last rebuild and check, and offers rebuild (search.rebuild) and purge (search.purge).

Configuration referenceCopy Anchor Link

Every key is under search: in config/engine.yaml.

Each backend block also accepts url, addresses, api_key, username and password, but each driver reads only the keys above: Meilisearch reads url, api_key, index_prefix and timeout; Elasticsearch and OpenSearch read addresses, username, password, index_prefix and timeout, and authenticate with basic authentication only.

Headless sitesCopy Anchor Link

A headless frontend searches through the content API, which answers from the same service, log and browse fallback.