Searching your data
One endpoint answers "find me this entity", with three complementary strategies behind it.
The three strategies
Search results. Each row is one entity, whatever strategy matched it.
| Strategy | Good at | Weak at |
|---|---|---|
| Full text | Natural queries across an entity's indexed text | Misspellings |
| Fuzzy label | Typos and near-misses on the entity's display label | Anything not in the label |
| Attribute-scoped | Finding a record by a specific field — an identifier, an email | Broad exploratory queries |
Results can be filtered by entity type and status, sorted, and paged.
Attribute-scoped search and reference data
Searching a specific attribute has a subtlety worth understanding when the attribute is bound to reference data.
The stored value is the code; the label is resolved when reading. A search that only examined stored values could never find a record by its label — you would have to know that a municipality is stored as a numeric code before you could search for it by name.
Attribute-scoped search therefore matches the resolved label as well as the stored value, so searching for a place by its name works as a person would expect.
Access control applies to results
Search is not a side door.
- Row-level isolation means a query can only ever see the caller's tenant.
- ABAC policies that hide individual records hide them from search results too.
- Field masking applies to matched values in results, exactly as it does when reading the entity directly.
If an attribute is masked for you when you read the entity, searching that attribute does not reveal it. The matched value is masked in the result. This was a real defect once, and it is now covered by tests precisely because search is the obvious place for such a leak to hide.
Merged entities
By default search returns current entities. Merged records are excluded unless you ask for them, since a merged record is an alias for its survivor rather than a separate thing.
Advice
- Use attribute-scoped search for identifiers. It is precise and index-served.
- Use fuzzy label search for human lookup, where a name may be misremembered.
- Filter by entity type whenever you know it — it narrows the work substantially.
Next
Last verified against commit 315eb047 (2026-08-03)