Pesquisando seus dados
Um endpoint responde "encontre esta entidade", com três estratégias complementares por trás.
As três estratégias
Resultados de busca. Cada linha é uma entidade, qualquer que tenha sido a estratégia que a encontrou.
| Estratégia | Boa em | Fraca em |
|---|---|---|
| Texto completo | Consultas naturais sobre o texto indexado de uma entidade | Erros de grafia |
| Rótulo tolerante | Erros de digitação e quase-acertos no rótulo de exibição | Qualquer coisa fora do rótulo |
| Escopada a atributo | Encontrar um registro por um campo específico — um identificador, um e-mail | Consultas exploratórias amplas |
Resultados podem ser filtrados por tipo de entidade e situação, ordenados e paginados.
Busca escopada a atributo e dados de referência
Pesquisar um atributo específico tem uma sutileza que vale entender quando o atributo é vinculado a dados de referência.
O valor armazenado é o código; o rótulo é resolvido na leitura. Uma busca que examinasse apenas valores armazenados nunca encontraria um registro pelo rótulo — você teria de saber que um município é armazenado como um código numérico antes de conseguir pesquisá-lo pelo nome.
Por isso a busca escopada a atributo casa também com o rótulo resolvido, e pesquisar um lugar pelo nome funciona como uma pessoa esperaria.
O controle de acesso se aplica aos resultados
A busca não é uma porta lateral.
- O isolamento em nível de linha garante que uma consulta só enxergue a organização de quem consulta.
- Políticas ABAC que ocultam registros individuais também os ocultam dos resultados de busca.
- O mascaramento de campos se aplica aos valores correspondidos exatamente como na leitura direta da entidade.
Se um atributo está mascarado para você ao ler a entidade, pesquisá-lo não o revela. O valor correspondido vem mascarado no resultado. Isso já foi um defeito real, e hoje é coberto por testes justamente porque a busca é o lugar óbvio para um vazamento desses se esconder.
Entidades consolidadas
Por padrão a busca devolve entidades atuais. Registros consolidados são excluídos salvo pedido explícito, já que um registro consolidado é um apelido do seu sobrevivente e não uma coisa separada.
Conselhos
- Use busca escopada a atributo para identificadores. É precisa e servida por índice.
- Use busca tolerante de rótulo para consulta humana, quando um nome pode ser lembrado incorretamente.
- Filtre por tipo de entidade sempre que souber — reduz o trabalho substancialmente.
A seguir
Última verificação no commit d3c2586b (2026-08-03)