Usar variáveis bind e funções agregadas

Objetivos de aprendizagem

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

• Tornar uma consulta dinâmica com a inserção de variáveis bind do Apex.
  
• Usar uma função agregada para totalizar e resumir os dados em uma consulta.
  
• Aplicar agrupamento aos resultados de consulta.
  
• Reconhecer quando usar a cláusula WHERE e quando usar a cláusula HAVING.
  

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.

(Este clipe começa na marca dos 01:10:42 minutos, caso você queira retroceder e ver o início da etapa novamente.)

Introdução

Falamos sobre como escrever uma consulta SOQL básica e como formular consultas que incluam campos em objetos pais ou filhos. Mas, como você sabe, cada projeto de desenvolvimento de aplicativos é único. Saber como adaptar a lógica de negócios para resolver um problema específico é importante.

Variáveis bind

O uso de variáveis bind é uma maneira de fazer seu código sob medida. É semelhante a abrir um formulário na interface do usuário e modificar um campo de entrada para pesquisar certos resultados. Vejamos um exemplo no aplicativo DreamHouse. Você é um corretor de imóveis que vende casas e quer rever seu inventário de imóveis com preço abaixo de US$ 200.000. Para isso, você escreve esta consulta:

List<Property__c> property = [SELECT Id, Name, Price__c FROM Property__c WHERE Price__c < 200000];

Isso é muito simples. Para você. Mas a consulta é estática. Essa consulta sempre devolve casas abaixo de US$ 200.000. E quanto a outros corretores de imóveis e possíveis compradores que não podem escrever consultas SOQL e executá-las no Developer Console? Eles precisam de uma maneira mais fácil de filtrar casas pelo preço certo para eles. Como você pode escrever uma consulta que funcione para um comprador cujo orçamento seja de US$ 200.000 e para outro comprador cujo orçamento seja de US$ 800.000? É aí que entram as variáveis bind. Uma variável bind é uma variável do Apex que você usa em uma consulta SOQL. Use variáveis bind como espaços reservados para valores específicos que serão fornecidos posteriormente.

Esse conceito não é novo. Na Programação orientada a objetos para administradores, você aprendeu a usar um parâmetro como espaço reservado em um método. Quando você chama o método, transmite um argumento que substitui o parâmetro. Uma variável bind em uma consulta é como um parâmetro em um método. A variável bind é substituída por um valor específico quando a consulta é executada.

Considere uma variável bind chamada maxHomeValue. Declaramos a variável no Apex e usamos a variável em uma consulta, desta forma:

Integer maxHomeValue = 200000;
List<Property__c> property = [SELECT Name, Price__c FROM Property__c WHERE Price__c < :maxHomeValue];

Observe que, na consulta, a variável bind é precedida por dois pontos ( : ). Essa consulta retorna o nome e o preço do objeto de propriedade. Mas os resultados são filtrados com base no preço da casa: WHERE Price__c < :maxHomeValue. O valor da variável bind, maxHomeValue, é definido fora da consulta. Vamos ver isso na prática.

1. Em seu Trailhead Playground, clique em , digite Dream na caixa de pesquisa e selecione o aplicativo DreamHouse.
   
2. Clique em Property Explorer (Explorador de propriedade).
   O Property Explorer (Explorador de propriedade) pesquisa as propriedades disponíveis com base em vários filtros, como uma faixa de preço máximo. O controle deslizante Preço máximo aceita valores para as variáveis bind maxHomeValue.
   
3. Mova o controle deslizante Preço máximo para 550K.
   

Cada vez que o controle deslizante se move, seu valor associado é modificado no código por meio da variável bind. A consulta é executada e adiciona os resultados a uma lista de propriedades exibidas na página do Property Explorer.

O uso de variáveis bind na cláusula WHERE permite definir valores de variável em seu código antes que a consulta seja executada. As variáveis bind tornam uma consulta dinâmica. Para personalizar uma consulta para cada usuário, defina valores de variável bind com base na entrada do usuário. À medida que você modifica e revisa o código, vai descobrir muitos tipos de campos cujos dados estão em constante mudança.

Funções agregadas

Nos relatórios, você usa campos de resumo de totalização para calcular valores de registros relacionados. Por exemplo, você pode querer calcular o número total de propriedades ou o valor médio ou mais alto de propriedades em uma cidade. No SOQL, você usa funções agregadas para fazer esses e outros cálculos.

Funções agregadas para consultas SOQL

Vamos usar imóveis em uma cidade como exemplo. Vamos começar com esta consulta simples:

SELECT City__c FROM Property__c

A consulta devolve a cidade para cada um dos 12 imóveis.

Como não queremos toda a lista de cidades, modifique a consulta para usar uma função agregada. Para obter o número total de propriedades, use a função COUNT().

A função agregada entra na cláusula SELECT de uma consulta, assim:

Os parênteses após o nome da função contêm o nome do campo a ser usado no cálculo. Neste exemplo, vamos contar os valores no campo City__c.

Executar uma consulta COUNT()

1. No Editor de consultas, digite o seguinte:
   

   SELECT City__c FROM Property__c

2. Clique em Executar.
   Os resultados da consulta devem ter 12 linhas com a cidade de cada imóvel.
   
3. Edite a consulta para que o campo City__c seja inserido na função COUNT(), assim:
   

   SELECT
   COUNT(City__c)
    FROM Property__c

4. Clique em Executar.
   O resultado da consulta deve ser 12, que é o número de imóveis com base no campo City__c.
   
   
   

Se você notou que todos os 12 imóveis estão em apenas 2 cidades, pode estar se perguntando por que a contagem é de 12 em vez de 2. Isso acontece porque a função COUNT() conta todos os valores, o que muitas vezes inclui vários registros com o mesmo valor.

Suponha que queiramos atribuir um corretor a todas as propriedades de uma cidade. De quantos corretores precisamos? Dito de outra forma, quantas cidades únicas os 12 imóveis representam? Para contar apenas cidades únicas, precisamos de outra função. (Quando você ouvir "único", pense em "diferente".)

COUNT_DISTINCT() é semelhante a COUNT(), exceto que retorna apenas valores únicos (sem duplicatas).

Executar uma consulta COUNT_DISTINCT

1. No Editor de consulta, edite a consulta para usar a função COUNT_DISTINCT(), assim:
   

   SELECT COUNT_DISTINCT(City__c) FROM Property__c

2. Clique em Executar.
   Agora seu resultado deve ser 2, o número de valores únicos de City__c entre todos os imóveis.
   
   
   

Cambridge, Boston e Brookline são os únicos valores únicos encontrados no campo City__c. Observe que as funções COUNT() e COUNT_DISTINCT() diferenciam maiúsculas de minúsculas. Isso significa que Cambridge não é uma duplicata de cambridge. Cambridge e cambridge são considerados dois valores únicos.

MIN(), MAX(), AVG() e SUM()

Outras funções agregadas úteis incluem MIN(), MAX(), AVG() e SUM().

As funções MIN() e MAX() são simples. MIN() encontra o valor mínimo (mais baixo) e o MAX() encontra o valor máximo (mais alto). Mas há algo único nessas funções. Elas podem lidar com datas e horários além de números.

1. No Editor de consultas, digite o seguinte:
   

   SELECT MIN(Date_Listed__c) FROM Property__c

2. Clique em Executar.
   

A função MIN() retorna a data mais antiga. A função MAX() retorna a data mais recente.

As funções MIN() e MAX() também reconhecem a ordem de valores de lista de opções, para que você possa encontrar o primeiro ou o último valor em uma lista de opções.

A função AVG() calcula a média de todos os valores. A função SUM() calcula a soma de todos os valores. Como ambas as funções realizam cálculos, elas trabalham apenas com campos que contenham valores numéricos.

Agrupar os resultados das funções agregadas

Depois de calcular valores com base em dados agregados, você pode querer relatar resultados em grupos, como faz em relatórios de resumo. Para agrupar valores em uma consulta SOQL, use a cláusula GROUP BY. Por exemplo, um cliente da DreamHouse Realty quer saber quais corretores venderam (fecharam) um imóvel.

Ver a cláusula GROUP BY na prática

Em seguida, use a cláusula GROUP BY em uma consulta.

1. No Editor de consultas, digite o seguinte:
   

   SELECT MAX(Status__c), Broker__r.Name
   FROM Property__c
   GROUP BY Broker__r.Name

2. Clique em Executar.
   Seus resultados devem ter oito linhas.
   
   
   

Lembre-se, essa consulta agrupa propriedades por corretor. Nos imóveis de cada corretor, listamos o valor Status__c mais avançado. Esse é o valor de lista de opções de status mais próximo do valor final de lista de opções. Queremos corretores que venderam imóveis, ou seja, vamos restringir ainda mais os resultados. De volta à estaca zero.

Filtrar os resultados das funções agregadas

Outra maneira de reduzir os resultados é usar uma cláusula HAVING. A cláusula HAVING filtra os resultados retornados por uma função agregada.

Hmm... isso soa como algo que podemos usar para encontrar corretores que venderam propriedades. Nossa consulta anterior devolveu uma lista de corretores que têm propriedades em algum status. Tente usar a cláusula HAVING para restringir esses resultados.

1. No Editor de consultas, digite o seguinte:
   

   SELECT MAX(Status__c), Broker__r.Name
   FROM Property__c
   GROUP BY Broker__r.Name
   HAVING MAX(Status__c) = 'Closed'

2. Clique em Consultar. Você deve obter um único corretor.
   
   
   

Sim! É isso aí. O uso da cláusula HAVING restringe os resultados a propriedades com o status Fechado. Ótimo trabalho!

A cláusula WHERE é muito parecida com a cláusula HAVING, certo? Veja como decidir quando usar WHERE e quando usar HAVING.

• A cláusula WHERE filtra registros em uma consulta SOQL que não tenha função agregada.
  
• A cláusula HAVING filtra os resultados após os dados serem agregados por uma função agregada.
  

Como você aprendeu neste módulo, SOQL é uma ótima ferramenta para acessar dados em sua organização do Salesforce. Conforme você for criando e expandindo suas habilidades de codificação em Apex, encontrará muitas oportunidades para usar seu conhecimento sobre SOQL. Lembre-se de que você pode encontrar detalhes, exemplos e mais informações sobre Apex e SOQL nos recursos fornecidos neste módulo. Agora, vá em frente e consulte...com SOQL.

Recursos

• Documentação de desenvolvedores do Salesforce: Como usar variáveis do Apex em consultas SOQL e SOSL
  
• Documentação de desenvolvedores do Salesforce: Funções agregadas
  
• Documentação de desenvolvedores do Salesforce: Exemplos de cláusulas SELECT
  
• Documentação de desenvolvedores do Salesforce: GROUP BY