Consultar objetos grandes

Objetivos de aprendizagem

Após concluir esta unidade, você estará apto a:
  • Usar SOQL padrão para consultar objetos grandes.
  • Usar SOQL assíncrono para consultar objetos grandes.
  • Listar as vantagens e desvantagens de usar SOQL assíncrono em vez de SOQL padrão.

SOQL e SOQL assíncrono

Os objetos grandes podem ser consultados usando SOQL ou SOQL assíncrono. O SOQL assíncrono usa um subconjunto de comandos SOQL. E ele foi projetado desde o início para lidar com o grande volume de dados que pode ser armazenado em um objeto grande. Como as consultas SOQL assíncronas são executadas assincronamente, você não precisa se preocupar com o tempo limite das consultas. As consultas SOQL assíncronas são executadas em segundo plano e podem ser executadas em dados da entidade do Salesforce, de objetos padrão, de objetos personalizados e de objetos grandes. O SOQL assíncrono é implantado por meio da API REST do Chatter.

Normalmente, o ideal é usar SOQL assíncrono em vez de padrão na hora de lidar com grandes volumes de dados. Se você só precisa de um pequeno subconjunto de dados de um objeto grande ou se precisa dos resultados imediatamente, use SOQL padrão. O SOQL assíncrono também funciona em objetos padrão e personalizados que não sejam objetos grandes, mas o suporte a esses objetos ainda está na fase piloto.

Lembre-se de que embora objetos grandes personalizados estejam incluídos em todas as licenças, o SOQL assíncrono só está incluído na licença adicional de capacidade de objeto grande.

Use SOQL padrão quando:
  • Quiser exibir os resultados na interface do usuário sem ter que fazer o usuário esperar por eles.
  • Quiser que os resultados sejam retornados imediatamente para manipulação em um bloco do código do Apex.
  • Você sabe que a consulta retornará um pequeno volume de dados.
Use SOQL assíncrono quando:
  • Você estiver executando uma consulta em milhões de registros.
  • Quiser garantir a conclusão da consulta.
  • Não precisar fazer consultas agregadas ou filtrar fora do índice.

É um caso de uso de SOQL assíncrono.

Resumindo: o SOQL assíncrono permite usar os milhões de registros em um objeto grande e extrair dados relevantes para um conjunto de dados de trabalho gerenciável.

Como usar o SOQL para consultar objetos grandes

Se você já está familiarizado com o uso de SOQL, vai se sentir em casa. Existem algumas coisas a se ter em mente na hora de usar SOQL padrão com objetos grandes que são diferentes do uso de SOQL sem ser com objetos grandes. Em consultas SOQL com objetos grandes, você precisa criar sua consulta a partir do primeiro campo definido no índice, sem pular campos entre o primeiro e o último campo da consulta. Assim, por exemplo, se seu índice define três campos, você não pode criar uma consulta usando somente os campos um e três.

Você pode usar estes operadores de comparação, =, <, >, <=, >= ou IN no último campo da sua consulta. Os campos anteriores da sua consulta podem usar somente o operador =. Os operadores !=, LIKE, NOT IN, EXCLUDES e INCLUDES não são válidos em uma consulta envolvendo objetos grandes.

As consultas a seguir assumem que você tem um objeto grande cujo índice é definido por Account__c, Game_Platform__c e Play_Date__c.

Essa consulta especifica todos os três campos no índice. Nesse caso, o filtro em Play_Date_c pode ser um intervalo.
SELECT Account__c, Game_Platform__c, Play_Date__c
FROM Customer_Interaction__b
WHERE Account__c='001R000000302D3' AND Game_Platform__c='PC' AND Play_Date__c=2017-09-06T00:00:00Z
Essa consulta não funciona porque há uma lacuna na consulta onde Game_Platform__c deveria estar.
SELECT Account__c, Game_Platform__c, Play_Date__c
FROM Customer_Interaction__b
WHERE Account__c='001R000000302D3' AND Play_Date__c=2017-09-06T00:00:00Z

Como usar o SOQL assíncrono para consultar objetos grandes

Existem duas maneiras principais de se usar o SOQL assíncrono para obter um conjunto de dados gerenciável de um objeto grande. A primeira é usando filtros. Você pode usar filtros a fim de extrair um pequeno subconjunto dos dados do seu objeto grande para um objeto personalizado. Depois, você pode usá-lo em seus relatórios, painéis ou em outra ferramenta de análise.

A outra maneira de criar um conjunto de dados gerenciável é por meio de agregações genéricas. Estas são as funções de agregação compatíveis com SOQL assíncrono: AVG(field), COUNT(field), COUNT_DISTINCT(field), SUM(field), MIN(field), MAX(field). Essas funções de agregação permitem um controle muito maior sobre os dados que são extraídos do objeto grande.

Como formar sua consulta

Usando o SOQL assíncrono, consultamos seu objeto grande personalizado Customer_Interaction__b e direcionamos os resultados para nosso objeto de destino Customer_Interaction_Analysis__c. Extraímos as informações de conta e de compra no jogo em uma data específica de nosso objeto grande personalizado para nosso objeto de destino, que poderão ser usadas em relatórios e análises.

Campos obrigatórios
Nome Tipo Descrição
query Sequência de caracteres Especifica os parâmetros da consulta SOQL que você deseja executar.
targetObject String Um objeto padrão, personalizado, externo ou objeto grande no qual pode inserir os resultados da consulta.
targetFieldMap Map<String, String>

Define como mapear os campos no resultado da consulta para os campos no objeto de destino.

Ao definir o parâmetro targetFieldMap, verifique se os mapeamentos de tipo de campo estão consistentes. Se os campos de origem e destino não corresponderem, leve em conta estas considerações.
  • Todo campo de origem pode ser mapeado para um campo de texto de destino.
  • Se os campos de origem e destino forem numéricos, o número de casas decimais do campo de destino precisa ser maior ou igual ao número de casas decimais do campo de origem. Do contrário, a solicitação falhará. Esse comportamento tem como objetivo fazer com que nenhum dado se perca na conversão.
  • Se um campo no resultado da consulta for mapeado mais de uma vez, mesmo que seja para campos diferentes no objeto de destino, somente o último mapeamento será usado.
URI de exemplo
https://yourInstance.salesforce.com/services/data/v41.0/async-queries/

Corpo da solicitação de POST

{ 
   "query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",
   
   "operation": "insert",
   
   "targetObject": "Customer_Interaction_Analysis__c", 
        
   "targetFieldMap": {"Account__c":"Account__c",
                      "In_Game_Purchase__c":"Purchase__c"
                      },
   "targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
                      "Copy fields from source to target":"BackgroundOperationDescription__c"
                     }
}
Nesta consulta, estamos pegando as informações de conta e de compra no jogo de nosso objeto grande de interações dos clientes em uma data específica, 6/9/2017, e enviando esses dados para um objeto personalizado que criamos chamado Customer_Interaction_Analysis__c. Como estamos usando o SOQL assíncrono e não o SOQL padrão, podemos filtrar sem nos preocuparmos com a inclusão dos outros campos indexados. Esse novo objeto personalizado é preenchido com todas as informações de conta e de compra no jogo em tal data. A partir desses dados, podemos começar a fazer algumas análises e tentar descobrir por que nosso jogo é esse sucesso todo.

Corpo da resposta POST

O corpo da resposta POST inclui o jobId da consulta, o status da consulta e as mensagens pertinentes.
{ 
   "jobId": "08PD000000003kiT", 
   
   "message": "",
    
   "query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",  
    
   "status": "New",
     
   "targetObject": "Customer_Interaction_Analysis__c", 
     
   "targetFieldMap": {"Account__c":"Account__c", 
                      "In_Game_Purchase__c":"Purchase__c"
                     },
   "targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
                      "Copy fields from source to target":"BackgroundOperationDescription__c"
                     } 
}

Como rastrear o status da sua consulta

Para rastrear o status de uma consulta, especifique o jobID com uma solicitação HTTP GET. O status da consulta é retornado no campo status. Se você não especificar um jobID, retornaremos o status de todas as consultas. O status pode ser:
  • Cancelado— O trabalho foi cancelado antes de ser executado.
  • Êxito— O trabalho foi concluído com sucesso.
  • Falha— O trabalho falhou após o envio pelo sistema ou porque a solicitação excedeu os limites do SOQL assíncrono. O campo de mensagem fornece detalhes sobre o motivo da falha.
  • Executando— O trabalho está sendo executado corretamente e a organização não excedeu nenhum limite.
  • Agendado— O novo trabalho foi criado e agendado, mas ainda não foi executado.

Você também pode cancelar uma consulta usando uma solicitação HTTP DELETE especificando o jobId. O cancelamento de uma consulta concluída não tem nenhum efeito.

Lembre-se: o SOQL assíncrono é feito de forma assíncrona. Isso significa que a sua consulta pode demorar um pouco para ser concluída. Como mencionamos antes, se há pressa e se seu conjunto de dados é pequeno o suficiente, use o SOQL padrão. Como alternativa, podemos pensar em fazer um jogo fictício menos popular para usar nesses exemplos, mas isso não tem graça.

URI de exemplo
https://yourInstance.salesforce.com/services/data/v41.0/async-queries/08PD000000003kiT
Resposta GET de exemplo
{
"jobId": "08PD000000003kiT",
"message": "",
"query": "SELECT Account__c, In_Game_Purchase__c FROM Customer_Interaction__b WHERE Play_Date__c=2017-09-06T00:00:00Z",  
"status": "Success",
"targetObject": "Customer_Interaction_Analysis__c",
"targetFieldMap": {"Account__c":"Account__c",
"In_Game_Purchase__c":"Purchase__c" } 
}
Essa resposta mostra que nossa consulta foi concluída com sucesso. Uhuuu! Hora de aprontar seus relatórios e painéis!

Como lidar com erros

Dois tipos de erro diferentes podem ocorrer durante a execução de uma consulta SOQL.
  • Um erro na execução de uma consulta
  • Um ou mais erros na hora de gravar os resultados no objeto grande de destino

Enviar uma consulta inválida e exceder um dos limites do SOQL assíncrono são exemplos de problemas de execução. Outro exemplo é quando uma consulta causa problemas na estrutura subjacente. Quando esses erros ocorrem, o corpo da resposta inclui um status de Falha. O parâmetro de mensagem oferece mais informações sobre a causa da falha.

Em outros casos, a consulta é executada com sucesso, mas encontra um erro ao tentar gravar os resultados no objeto de destino. Devido ao volume de dados envolvido, a captura de todos os erros não é eficaz. Em vez disso, subconjuntos de erros gerados são capturados no objeto BackgroundOperationResult e guardados por sete dias. Você pode consultar esse objeto com a consulta SOQL assíncrona jobId para filtrar os erros da consulta SOQL assíncrona em questão. As informações do trabalho SOQL assíncrono são guardadas por um ano.

Considerações finais

Agora você conhece tudo o que é necessário para usar objetos grandes personalizados na sua própria organização. Bilhões de registros estão agora sob o seu comando, muahaha!

Mas vimos SOQL assíncrono apenas superficialmente. Verifique a seção de recursos para ver todos os comandos SOQL padrão compatíveis com SOQL assíncrono e outros casos de uso de exemplo. Você também encontrará informações sobre os campos opcionais que podem ser usados nas solicitações POST. Confira também nosso módulo Noções básicas de integração de dados de análise para ver algumas ideias de configuração da análise dos dados extraídos dos objetos grandes. Pense em todos os gráficos e painéis que você pode gerar com esses dados!