Escrever consultas SOSL

Objetivos de aprendizagem

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

• Compreender como o SOSL se diferencia das alternativas de pesquisa de texto completo.
• Identificar a sintaxe básica do SOSL.
• Descrever as diferenças entre SOSL e SOQL.
• Criar uma consulta SOSL que pesquise em diversos sObjects.

O que é SOSL?

Na última unidade, você conheceu o SOQL e aprendeu a usá-lo para consultar dados nos sObjects e nas tabelas relacionadas a eles. Para realizar consultas baseadas em texto em diversos sObjects, você pode usar o SOSL (linguagem de pesquisa em Salesforce Object, Salesforce Object Search Language), a opção do Salesforce para a pesquisa de texto completo.

Como desenvolvedor .NET, talvez você já conheça os recursos de pesquisa de texto completo disponíveis no Microsoft SQL Server (MS FTS). E também já deve conhecer Lucene.Net, popular biblioteca de mecanismos de pesquisa que foi transportada da versão original em Java para C#.

O SOSL é diferente dessas opções de pesquisa de texto completo e essa notícia é boa e ruim ao mesmo tempo. As maiores diferenças têm a ver com o que é necessário para configurar e manter os índices. O Salesforce usa Lucene, a tecnologia do mecanismo de indexação e pesquisa, de código aberto, no SOSL, mas tudo foi configurado para que você não precise se preocupar em instalar e configurar nada. Você também não é responsável por manter os índices. Na verdade, na maior parte do tempo, você não controla muito a forma como os índices de pesquisa são usados, o que é bom porque significa que é fácil escrever consultas SOSL.

Entretanto, como desenvolvedor .NET, você adora adaptar a ajustar seu código. Então, talvez você fique um pouco desconfortável ao saber que tem pouco controle da configuração e dos índices. Ressaltamos que, mesmo tendo menos controle, você ainda pode fazer coisas para melhorar o desempenho das consultas, sejam elas SOSL, sejam elas SOQL. Logo trataremos desses métodos em detalhes, mas, por enquanto, vamos falar das diferenças da sintaxe SOSL.

Criando uma consulta SOSL

Se você conhece o MS FTS, já sabe que é preciso escrever consultas SELECT que usem um demonstrativo CONTAINS ou FREETEXT. A potente pesquisa CONTAINS, que conta com muitas variações, permite pesquisar correspondências exatas ou parciais e pesquisar palavras que estão próximas de outra palavra.

O SOSL usa uma sintaxe de pesquisa mais simples que dispensa a palavra-chave SELECT do SOQL. Em vez disso, ele usa a palavra-chave FIND. Exemplo de consulta básica:

FIND {"grand*"} IN ALL FIELDS RETURNING Account(Name), Contact(LastName, FirstName, Email)

Decompondo essa consulta, podemos ver que ela tem três partes.

Cláusula FIND com o termo da pesquisa

A cláusula FIND é obrigatória. É ela que torna a pesquisa SOSL única. A cláusula FIND é sucedida pelo termo que você está pesquisando, seja uma palavra isolada, seja uma frase. Nesse caso, é a palavra “grand”. Também é possível incluir caracteres curinga como no exemplo, como esses dois:

* matches zero or more characters at the middle or end of the search term
?matches only one character at the middle or end of the search term

Falaremos mais sobre os caracteres curinga na próxima unidade. Enquanto isso, saiba que é possível usar um coringa no meio e outro no final do termo da pesquisa, mas isso não é aconselhável. De fato, como melhor prática, isso não é uma boa ideia porque pode prejudicar bastante o desempenho da consulta.

Cláusula IN

Use a cláusula IN para especificar um grupo de pesquisa. Ela conta ao Salesforce em quais campos pesquisar. Mas tem um ponto muito importante que você precisa saber; então, tenha paciência com a explicação.

No exemplo cima, especificamos ALL FIELDS. A pessoa pode pensar nisso no sentido mais literal e achar que todos os campos serão pesquisados; porém, dependendo do objeto especificado na cláusula RETURNING, só determinados campos baseados em texto serão inclusos. Como assim?

Como dissemos, tenha paciência. É assim: se o objeto retornado for um artigo, um documento, um comentário de feed, um item de feed, um arquivo, um produto ou uma solução, TODOS os campos serão pesquisados porque é melhor pesquisar em todos os campos quando estamos buscando esses tipos de objeto.

Porém, se a pesquisa for feita na maioria dos objetos personalizados ou padrão, o que abrange todo tipo de campo absurdo que não se baseia em texto, faz mais sentido pesquisar apenas nos campos de nome, email, telefone e barra lateral. A propósito, esse é o comportamento padrão.

Então, digamos que você quer pesquisar apenas nos campos de nome, em vez de especificar ALL FIELDS. Nesse caso, você usaria NAME FIELDS. Para pesquisar apenas nos campos de telefone, usaria PHONE FIELDS. Entendeu como funciona?

Cláusula RETURNING

Use a cláusula RETURNING para especificar quais dados retornar e quais objetos pesquisar. No exemplo acima, retornamos o campo Name de Account e os campos Lastname, FirstName e Email de Contact. A pesquisa examinou todos os campos pesquisáveis em ambos os objetos, mas os resultados retornados incluem somente os campos listados entre parênteses.

Se você especificar o nome de um objeto sem o nome de um campo entre parênteses, a pesquisa retornará apenas a ID desse objeto, caso encontre alguma correspondência.

A sintaxe SOSL tem outras cláusulas opcionais que podem ser interessantes para você. Confira os documentos oficiais para saber mais sobre elas.

Certo, agora você deve estar imaginando como o SOSL se compara a outros mecanismos de pesquisa de texto completo quando se trata de correspondências parciais. Além da palavra-chave LIKE, que pode ser usada na consulta SOQL, e dos curingas, que podem ser usados na consulta SOSL, o Salesforce oferece somente uma pesquisa por sinônimos para buscar apelidos.

SOQL ou SOSL?

Qual deles usar? A resposta não é nada surpreendente: depende do que você está tentando fazer.

Se você precisar de dados de um único objeto e souber quais são os critérios específicos para esse objeto, provavelmente vai preferir o SOQL. Na verdade, é provável que a maioria das suas consultas seja feita em SOQL.

O SOSL é mais útil quando você não sabe em que campos e objetos exatos os dados estão e precisa pesquisar em vários objetos. A sua utilidade se destaca especialmente quando os objetos não são relacionados, porque o SOQL trabalha somente com objetos relacionados.

Executar uma pesquisa SOSL

Agora que você já sabe por que e como usar a pesquisa SOSL, vamos seguir em frente e tentar criar uma.

É possível executar a pesquisa SOSL de mais de uma maneira, mas neste momento vamos nos concentrar na mais fácil delas, que é usar o Query Editor no Developer Console. Provavelmente, você se lembra desse conteúdo da última unidade sobre SOQL.

Pré-requisitos

Antes de executar a pesquisa SOSL, precisamos adicionar dados à organização de desenvolvimento. Primeiro, criaremos um documento de exemplo que podemos carregar na organização de desenvolvimento.

1. No Bloco de Notas ou em qualquer editor baseado em texto, crie um arquivo e digite o texto a seguir:

   First quarter figures were better than expected for new employee Joseph Smith.

2. Salve o arquivo na sua máquina local com o nome TestDocument.txt.
3. Na sua organização Developer Edtion, na guia Arquivos, clique em Carregar arquivos.
4. Navegue até o local onde você salvou o arquivo TestDocument.txt e clique em Abrir.
5. Clique em Concluído.

Também precisamos adicionar dados a alguns dos nossos objetos padrão.

1. No menu Configuração, selecione Developer Console para abrir o Developer Console.
2. No Developer Console, selecione Debug (Depurar) > Open Execute Anonymous Window (Abrir janela Executar no modo anônimo).
3. Exclua o código existente e insira o seguinte trecho:

   // Add Account and related Contact
   Account acct = new Account(
       Name='Test Account',
       Phone='(225)555-8989',
       NumberOfEmployees=10,
       BillingCity='Baton Rouge');
   insert acct;
   // Get the Id of the Inserted Account
   ID acctID = acct.ID;
   // Add a contact to the Account.Contact con = new Contact(
       FirstName='Joseph',
       LastName='Smith',
       Phone='(225)555-8787',
       Email='jsmith@testaccount.com',
       AccountId=acctID);
   insert con;
   

4. Clique em Executar.

Usar o Developer Console

Agora que temos uma amostra de dados para pesquisar, podemos usar o Editor de consulta para executar uma nova pesquisa SOSL.

1. No Developer Console, clique na guia Editor de consulta no painel inferior.
2. Exclua o código existente e insira o seguinte trecho:

   FIND {joey} IN ALL FIELDS RETURNING Account(Name), Contact(LastName, FirstName), ContentVersion(Title)
   

O primeiro ponto a reparar aqui é que as aspas simples que cercavam o termo da pesquisa no exemplo anterior foram substituídas por chaves. Precisamos usar chaves em vez de aspas quando executamos a pesquisa SOSL no Editor de consulta. Se a pesquisa fosse feita em código do Apex, usaríamos aspas simples. Repare também que o termo da pesquisa é a palavra “joey”, um apelido comum de Joseph (o nome real a ser pesquisado é Joseph).

1. Clique em Executar. Os resultados da pesquisa mostram apenas uma guia. O contato que você inseriu é apresentado na guia Contact, pois foi possível encontrar uma correspondência devido ao recurso de apelido disponibilizado no inverno de 2016. Mas o TestDocument carregado por você não aparece na lista porque a pesquisa por apelido só se aplica aos objetos Account, Contact, Lead e User. Vamos revisar o teste e retornar todos os resultados.
2. Substitua o código existente no Editor de consulta pelo seguinte:

   FIND {jos*} IN ALL FIELDS RETURNING Account(Name), Contact(LastName, FirstName), ContentVersion(Title)
   

3. Clique em Executar.
4. Os resultados da pesquisa agora mostram duas guias. A guia Document mostra o nome do documento carregado por você. Repare que usamos uma pesquisa com curinga para retornar todos os resultados desejados.

Quero saber mais

É possível que a pesquisa SOSL NÃO encontre todos os resultados correspondentes por causa dos limites. Lembre-se: o Salesforce é uma plataforma multilocatário. Se todo cliente pudesse consumir o máximo de recursos, o sistema inteiro entraria imediatamente em colapso. Pesquisas que excedam 20.000 caracteres podem sobrecarregar o sistema. Por isso, as pesquisas em SOSL são limitadas, assim como no SOQL. Agora, vamos aprender como otimizar as consultas das pesquisas.