Introdução a consultas SOQL

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:

Criar uma consulta SOQL válida usando as cláusulas obrigatórias.
Filtrar resultados de consulta com várias condições.
Ordenar resultados da consulta.

Se esta é a sua primeira parada na trilha Criar habilidades de codificação do Apex, você chegou longe demais. Volte um pouco e ganhe os emblemas Noções básicas de Apex para administradores e Programação orientada a objetos para administradores antes de continuar com este módulo.

Já ganhou esses emblemas? Excelente trabalho! Agora que você tem uma compreensão básica de como criar classes, variáveis e sObjects, é hora de aprender sobre a Salesforce Object Query Language (Linguagem de consulta de objetos do Salesforce), também conhecida como SOQL (pronuncia-se sockle).

O que é SOQL?

SOQL é uma linguagem que obtém dados de registro de um banco de dados do Salesforce. Na Programação orientada a objetos para administradores , você aprendeu que você pode usar instruções DML (Data Manipulation Language, Linguagem de Manipulação de Dados) para inserir, atualizar e excluir registros. Mas e se você quiser obter dados que já existem no banco de dados? O SOQL simplifica a recuperação de dados.

A criação de consultas SOQL é semelhante à criação de um relatório. Quando você cria um relatório, responde a perguntas como:

Que campos quero exibir?
Onde estão esses campos?

Você faz as mesmas perguntas quando cria uma consulta SOQL. Em uma consulta, as respostas a essas perguntas são os campos e o objeto.

SELECT Name, Email FROM Contact. SELECT e FROM são palavras-chave SOQL. Name e Email são campos e Contato é um objeto padrão do Salesforce.

Esta consulta contém palavras-chave SOQL (SELECT e FROM), campos de registro (Name e Email) e um objeto (o objeto Contato padrão).

O que a consulta está fazendo? Está recuperando (obtendo) informações específicas sobre registros de contato no banco de dados. Vamos examinar como essas informações se encaixam e praticar a criação de algumas consultas. Primeiro, analisamos as partes obrigatórias de uma consulta SOQL.

Cláusulas SOQL obrigatórias

SELECT

Na base de qualquer consulta SOQL estão duas cláusulas: a cláusula SELECT e a cláusula FROM. Pense em uma consulta como um pedaço de um quebra-cabeças. É parte de uma consulta completa.

SELECT Name, Email FROM Contact. SELECT Name, Email é a cláusula SELECT.

Cada consulta SOQL tem uma cláusula SELECT que começa com a palavra-chave SELECT. A cláusula SELECT especifica um ou mais campos (separados por vírgulas) em um registro do Salesforce. Esta consulta de exemplo retorna dois campos: Nome e Email.

Uma nota sobre nomes de campo: Como administrador, quando você fala com outro administrador, provavelmente se refere a um campo pelo seu rótulo de campo. Mas, em código, os desenvolvedores usam nomes de API no lugar deles. Então, nas consultas SOQL, use sempre nomes de API de campo, não rótulos de campo. Se você não tem certeza do nome de API de um campo, não se preocupe: há maneiras de descobrir isso. Mais sobre isso mais adiante neste módulo.

FROM

A segunda cláusula obrigatória para criar uma consulta SOQL é a cláusula FROM.

SELECT Name, Email FROM Contact. FROM Contact é a cláusula FROM.

Começando com a palavra-chave FROM, a cláusula FROM especifica um objeto no banco de dados do Salesforce. Neste caso, queremos dados do objeto Contato. Vamos ver como ficam os dados quando executamos a consulta.

Acompanhar com o Trail Together

Deseja acompanhar um especialista enquanto trabalha nesta etapa? Veja este vídeo que faz parte da série Trail Together no Trailhead Live. Na seção Recursos, há um link para acessar a seção completa.

Preparado para começar a trabalhar com SOQL?

Nesta unidade, mostramos os passos para criar uma consulta SOQL no Editor de consulta do Developer Console. Não temos um desafio prático nesta unidade, mas se você quiser acompanhar e experimentar as etapas, crie um Trailhead Playground novo agora. Consulte o módulo Gerenciamento do Trailhead Playground para saber como. Normalmente, leva de 3 a 4 minutos para que o Salesforce crie seu Trailhead Playground. Você também poderá utilizar o Trailhead Playground quando for necessário concluir os desafios práticos mais adiante no módulo.

Sim, estamos falando de um Trailhead Playground totalmente novo! Se você estiver usando uma organização ou um Trailhead Playground existente, poderá ter problemas na hora de concluir os desafios.

Criar uma consulta usando o Editor de consulta

Em seu Trailhead Playground, clique em e selecione Developer Console.
Clique em Arquivos | Abrir | Objetos | Contato.
Clique em Abrir.
O objeto Contato abre listando os nomes e tipos de todos os campos associados a ele.
No Developer Console, clique na guia Editor de consulta. (Se você não está vendo guias, clique na seta para cima na parte inferior da janela.)
O Editor de consulta tem três seções. A seção superior esquerda (1) exibe a consulta. Você pode editar a consulta lá. A seção inferior esquerda (2) exibe erros. E a seção direita (3) armazena um histórico de consultas SOQL executadas.
Usando CTRL + clique (Windows) ou CMD + clique (Mac), selecione os campos Email, Name e Languages__c .
Clique em Consultar.
A consulta SOQL, com base no objeto e nos campos selecionados, é exibida no Editor de consulta. Observe que, ao selecionar um campo no Query Builder, o Query Builder insere automaticamente o nome de API de campo na consulta SOQL. Com essa ferramenta, não há necessidade de memorizar nomes de API ou procurá-los.
Clique em Executar.

Após a execução da consulta, os resultados mostram exatamente o que é solicitado. Além disso, quando você usa o Editor de consulta, o ID é devolvido como bônus. Muito legal!

Cláusulas SOQL opcionais

A cláusula SELECT e a cláusula FROM são obrigatórias, mas a SOQL também tem cláusulas opcionais para refinar sua consulta.

As consultas de exemplo que você cria no Trailhead Playground retornam um número bastante pequeno de registros. A última consulta devolveu 20 registros. Mas e se houvesse milhares de registros? A quantidade de poder computacional necessária para processar esses dados seria substancial. Não seria bom se a SOQL tivesse um jeito de retornar um subconjunto de todos os registros? Na verdade, ela tem.

WHERE

A cláusula WHERE estabelece as condições a que um registro deve corresponder para ser selecionado e retornado. Use a cláusula WHERE da mesma forma que você usaria filtros para limitar os dados mostrados em um relatório ou uma exibição de lista. Por exemplo, se estamos procurando um contato cujo primeiro nome seja Stella, podemos adicionar WHERE FirstName = 'Stella' ao final da nossa consulta, assim:

SELECT Name, Email FROM Contact WHERE FirstName = 'Stella'

Você também pode definir a cláusula WHERE para filtrar usando mais de uma condição. Existem várias maneiras de fazer isso usando três operadores: AND, OR e IN. Vamos considerar alguns exemplos.

AND	Use AND para retornar registros que atendam a duas condições. Essa consulta retorna todos os registros que têm o primeiro nome Stella e o sobrenome Pavlova. SELECT Name, Email FROM Contact WHERE FirstName = 'Stella' AND LastName = 'Pavlova'
OR	Use OR para retornar registros que atendam a uma das duas condições. Essa consulta retorna registros com o sobrenome James ou o sobrenome Barr. SELECT Name, Email FROM Contact WHERE LastName = 'James' OR LastName = 'Barr'
IN	Use IN para retornar registros que atendam a pelo menos uma de três ou mais condições. A cláusula IN é comumente usada para retornar os valores de uma lista de opções ou valores de LIST ou SET. IN simplifica uma consulta que de outra forma teria muitas condições OR. Essa consulta retorna todos os registros que tenham o sobrenome James, Barr, Nedaerk ou Forbes. SELECT Name, Email FROM Contact WHERE LastName IN ('James', 'Barr', 'Nedaerk', 'Forbes')

LIMIT

A palavra-chave LIMIT define o número máximo de registros a serem devolvidos. LIMIT é útil quando você está testando e não quer esperar por uma consulta para processar um grande conjunto de dados. À medida que você vai aprendendo mais sobre SOQL, descobrirá maneiras mais relevantes de evitar o retorno de muitos registros, mas até lá, LIMIT é uma solução fácil. Vamos tentar adicionar um limite à nossa consulta.

Retorne ao Editor de consulta no Developer Console.
No final da consulta, digite LIMIT 5 para ficar assim:
```
SELECT Email, Name FROM Contact LIMIT 5
```
Clique em Executar.

O painel Resultados da consulta mostra cinco resultados.

ORDER BY

Agora que você tem algum controle sobre a quantidade de resultados, como pode organizar esses resultados? Use a cláusula ORDER BY para classificar os resultados pelo valor de um campo específico. Opcionalmente, use um qualificador em uma cláusula ORDER BY para especificar ordem crescente (padrão) ou ordem decrescente, assim como faria em uma planilha. Finalmente, se você tiver muitos valores de campo vazios, use o qualificador NULLS para agrupar todos os valores NULL em primeiro (padrão) ou por último.

Sintaxe	Descrição	Exemplo
ASC	Retorna resultados em ordem crescente	SELECT Name, Email FROM Contact ORDER BY Name ASC LIMIT 5
DESC	Retorna resultados em ordem decrescente	SELECT Name, Email FROM Contact ORDER BY Email DESC LIMIT 5
NULLS FIRST \| LAST	Retorna registros nulos no início (NULLS FIRST) ou no final (NULLS LAST)	SELECT Name, Email FROM Contact ORDER BY Email NULLS LAST

No exemplo ASC, SELECT Name, Email FROM Contact ORDER BY Name ASC LIMIT 5 retorna os campos Name e Email de cinco contatos, ordenados em ordem crescente pelo nome.

Resultados de consulta listando os campos de nome (em ordem crescente) e email no objeto Contato.

No exemplo NULLS, SELECT Name, Email FROM Contact ORDER BY Email NULLS LAST retorna o nome e o email em ordem crescente (porque crescente é a ordem padrão de classificação) por email. Os registros sem endereço de email são agrupados no final.

Resultados de consulta listando os campos de nome e email.

Com esta introdução ao poder do SOQL, agora você pode recuperar grandes conjuntos de dados, definir limites para obter resultados muito específicos e organizar os dados retornados para atender às suas necessidades. Maravilha.