0020: Global search¶
Status¶
Accepted (2026-10-12). Builds on ADR 0015 (object engine), ADR 0016
(sharing) and ADR 0019 (query language). Issue #305, part of epic #292.
Implemented in platform_objects::search, migration 0019, GET /search and
the shell search bar.
Context¶
Salesforce global search finds records across every searchable object from one box: names and fields marked searchable, results grouped by object, only records the person can see, and instant results while typing. It runs on a separate search index that is updated asynchronously, so a record saved a moment ago may not be found yet.
Limiara's engine already has the pieces search needs: objects and fields
carry a searchable flag (ADR 0015), sharing is a predicate the store can
add to any SQL (ADR 0016, ADR 0019), and record writes maintain typed pivots
in the same transaction. The question was where the index lives and how it
stays current.
Decision¶
1. An inverted index in the engine's own tables¶
record_search_terms holds one row per distinct term of each record:
(tenant_id, term, record_id) as the primary key, with the object and a
weight. It is tenant-first, carries tenant_id, and forces row-level
security on PostgreSQL like every engine table; on SQLite it lives in the
workspace's file.
- What is indexed: the record name (weight 3) and the values of fields marked searchable (weight 1). Only text, long text, email, phone and URL fields can be searchable, as before.
- Terms: values are lowercased (Unicode) and split on anything that is
not a letter or digit; terms are cut to 40 characters, and a record keeps
at most 500 distinct terms, name terms first. Phone numbers also index
their digits run together, so
447946finds+44 7946 0958. - Kept current in the write transaction. Terms are written with the
pivots whenever a record is created, changed, deleted or restored, so a
saved record is findable immediately and the index can never disagree
with the record. Changing a field's
searchableflag reindexes that object's records in the same transaction. The index ignores the object's ownsearchableflag, which is applied at query time, so switching an object off and on needs no reindex.
The issue proposed PostgreSQL full-text search first. We chose our own
table instead because it behaves identically on PostgreSQL and SQLite
(ADR 0013), supports prefix matching on every term with a plain B-tree
range scan on a byte-ordered (COLLATE "C") column, and needs no
language configuration: workspaces write in many languages, and the
simple text-search configuration we would have used does no stemming
anyway. The index is behind the store port, so an external engine can
replace it later (§4).
2. Matching and ranking¶
- The query is split into terms the same way, at most eight. Every term
must match the start of an indexed term (
acm indfinds "Acme Industries"). Queries need at least two characters. - Each record scores, per query term, its best weight for that term plus one when the term matches exactly rather than as a prefix; scores add up across terms. Results sort by score, then name, then ID. Recently viewed records are not boosted yet: that needs the recently viewed service (#285) and is listed in the roadmap.
3. Permissions and sharing¶
- Only active objects that are searchable and that the caller can read are searched.
- Each object's record visibility (ADR 0016) is part of the SQL, the same predicate queries use, so a hidden record is never returned or counted. Records in the recycle bin are never returned.
- Results show the record name and the values of its searchable fields, which the caller can read because they can read the record. Field-level security (#316) will remove fields the caller cannot read.
4. Results and the API¶
GET /api/v1/workspaces/:workspace/search?q=…&object=…&limit=… returns
groups, one per object with matches, ordered by their best result:
{
"data": [
{
"object": "custom:account", "label": "Account", "plural_label": "Accounts",
"records": [{ "id": "0a1000000000000001", "name": "Acme Industries", "fields": { "custom:email": "[email protected]" } }],
"has_more": false
}
]
}
limit is the number of records per object (default 5, at most 50, or 200
with object), and object restricts the search to one object for a full
results page.
5. In the shell¶
The search bar in the header becomes a combobox: after two characters it
shows the top results per object as you type, the arrow keys move through
them, Enter opens one, and "See all results" opens a results page with a
tab per object. / and Ctrl+K (⌘K) focus it.
Alternatives considered¶
- PostgreSQL
tsvectorwith GIN. Fine on PostgreSQL, but it needs a second implementation on SQLite (FTS5) with different tokenising and ranking, so results would differ by backend. Prefix matching needs:*queries, and tenant isolation relies on the GIN index plus a separate tenant filter. - Update the index from change events asynchronously, as Salesforce does. It decouples writes from indexing but makes new records unfindable for a while and needs a worker per backend. Indexing a few hundred short terms per write is cheap enough to do in the transaction; an external engine can still follow the change log (ADR 0018) later.
- Search with
LIKE '%term%'on names. No index can serve it, so it scans every record of every object.
Consequences¶
- Searchable fields cost a few rows per record in
record_search_terms. - Ranking is simple and explainable; relevance features (recency boosts, synonyms, typo tolerance, highlighting on the server) remain open on #305 together with an external engine and plugin objects with typed stores (Contacts) joining the index (#318).