Skip to main content
View as Markdown

Search Overview

Sovrium search is not a standalone feature domain. It extends the schemas you already use: tables declare what is searchable (field weights, indexing), and page components declare how search behaves (engine, debounce, highlighting, result display). There is no top-level app.search config — configuration lives where it is used.

The backend is built entirely on PostgreSQL: Full-Text Search (tsvector/tsquery) plus the pg_trgm extension for fuzzy, typo-tolerant matching. No Elasticsearch, no Algolia, no external service — search stays inside your own database, in keeping with Sovrium's digital-sovereignty principle.

Search engines

A data source in mode: 'search' selects its backend with searchEngine. The same table can use different engines on different pages.

Engine Where it runs Best for
client Browser JavaScript Small datasets already loaded in the page; instant, no round-trip. Default.
fts PostgreSQL FTS Server-side ranked relevance over indexed text; large datasets.
trigram PostgreSQL pg_trgm Fuzzy matching and typo tolerance; partial/misspelled queries.
hybrid PostgreSQL FTS + trigram FTS for relevance with a trigram fuzzy fallback; best of both.

client — browser filtering

JavaScript filtering in the browser. The records are already fetched, and the query narrows them in-memory. Zero server round-trip, but the whole result set must fit in the page. Use it for small reference lists and pickers.

app.yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: client
    debounceMs: 300

fts — PostgreSQL Full-Text Search

Server-side ranked search using tsvector/tsquery. Results come back ordered by relevance, with every indexed field contributing equally. Requires the searched fields to be indexed: true. Use it for large, text-heavy datasets where ranking matters.

app.yaml
- type: data-table
  dataSource:
    table: articles
    mode: search
    searchFields: [title, body]
    searchEngine: fts
    debounceMs: 300
    limit: 20

trigram — fuzzy matching

Uses the pg_trgm extension to match on character trigrams, tolerating typos and partial words. Ideal when users misspell or type fragments (e.g. prodct still matches product). See full-text-search for indexing details.

app.yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name]
    searchEngine: trigram

hybrid — relevance plus fuzziness

Combines FTS for relevance ranking with trigram as a fuzzy fallback, so exact and ranked matches surface first while misspelled queries still return results. The most forgiving engine for end-user-facing search.

app.yaml
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 50

The search data-source mode

Search is one of three data-source modes (list, single, search). Setting mode: 'search' turns a data-bound component into an interactive, debounced search experience.

Property Description
table Table to query (validated against app.tables).
searchFields Array (≥ 1) of field names to search across. Required for search mode.
searchEngine Backend: client (default), fts, trigram, or hybrid.
debounceMs Debounce delay for the search input in milliseconds (integer ≥ 0), e.g. 300, 500.
limit Maximum number of results to return (integer ≥ 1), e.g. 10, 20, 50.
bindTo ID of a searchInput component whose query drives this data source (cross-component binding).
filter Filter conditions (AND logic) applied alongside the search query.
sort Sort rules applied to results.
refreshMode How results refresh after load: none (default), poll, or realtime.
app.yaml
# Interactive search with debounce and a result limit
- type: data-table
  dataSource:
    table: products
    mode: search
    searchFields: [name, description]
    searchEngine: hybrid
    debounceMs: 300
    limit: 20

For static filtering and ordering of non-search results, use the list mode with filter/sort instead — see records-filtering-sorting.

Choosing an approach

Need Use
Narrow a small list already on the page searchEngine: client
Rank large text datasets by relevance searchEngine: fts + indexed: true
Tolerate typos and partial words searchEngine: trigram
Both relevance ranking and typo tolerance searchEngine: hybrid
Search static page content site-wide pageSearch component — see search-components
Define which fields are searchable and how weighted Field-level config — see full-text-search

Last updated August 11, 2026

Edit this pageReport an issue

This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.

Built with Sovrium