APRENDER. PRATICAR. EVOLUIR.Conceito e mecanismo
SOQL responde a consultas estruturadas sobre objetos e relações conhecidos, incluindo filtros e agregação. SOSL procura expressões textuais em vários objetos e organiza os resultados por tipo. Em Apex, selecionar apenas alguns campos não disponibiliza automaticamente todos os outros: o contrato da consulta deve acompanhar os dados que o código vai ler. Em consultas dinâmicas, binding trata valores; nomes de campos e outras partes estruturais requerem validação separada, normalmente uma allowlist. Escapar aspas não é uma solução universal. DML altera dados e tem regras próprias: upsert pode inserir, atualizar ou falhar por correspondência múltipla, consoante a chave e os registos existentes.
Aplicação guiada
Num carregamento operacional, conservar a correspondência entre cada input e o resultado devolvido. Database.insert com allOrNone false permite observar sucessos e falhas por registo, mas o código tem de inspecionar SaveResult. Um sucesso parcial da operação ainda não prova commit se a transação externa falhar posteriormente. A mensagem ao operador deve distinguir rejeição esperada, falha técnica e conclusão confirmada. Tratar apenas as exceções que se sabe resolver; não devolver sucesso com dados vazios para esconder problemas. Para interfaces Lightning, uma mensagem controlada pode explicar a correção necessária sem expor detalhes internos. Preservar diagnóstico adequado à investigação e apresentar apenas informação útil à pessoa que executou a ação.
Uma pesquisa aceita o valor do cliente por binding e permite ordenar apenas por campos aprovados. No carregamento seguinte, dois registos correspondem à mesma chave: o sistema suspende esse input e pede reconciliação, sem escolher arbitrariamente o mais recente.
Armadilhas comuns
Binding como proteção de identificadores; campos não selecionados tratados como zero; ausência de exceção como sucesso total; SaveResult como garantia de commit final.
Tópicos relacionados: Modelo de dados, identidade e metadados · Coleções e escolha entre configuração e código · Triggers, limites e processamento assíncrono
Consultar explicitamente, validar estrutura dinâmica e reconciliar cada resultado. Mensagens de sucesso devem corresponder a estados confirmados.
Referência: Manipulate Records with DML · Platform Developer guide Summer 25