Consultar objetos grandes
Objetivos de aprendizagem
- 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.
- 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.
- 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.
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.
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
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.
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.
|
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" } }
Corpo da resposta POST
{ "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
- 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.
https://yourInstance.salesforce.com/services/data/v41.0/async-queries/08PD000000003kiT
{ "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" } }
Como lidar com erros
- 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!
Recursos
- Big Object Implementation Guide: Async SOQL
- Big Object Implementation Guide: Running Async SOQL Queries
- Big Object Implementation Guide: Supported SOQL Commands
- Big Object Implementation Guide: SOQL with Big Objects
- Async Query
- Salesforce Object Query Language (SOQL)
- TrailheaDX 2017 Session: Async SOQL—Big Data Computing for Lightning Platform