Escrever consultas SOSL

• Descrever as diferenças entre SOSL e SOQL.
• Pesquisar por campos em diversos objetos utilizando consultas SOSL.
• Executar as consultas SOSL utilizando o Editor de consulta no Developer Console.

Nota

Deseja aprender em português (Brasil)? Nesse emblema, as validações dos desafios práticos do Trailhead funcionam em inglês. As traduções são fornecidas entre parênteses como referência No Trailhead Playground, (1) mude a localidade para Estados Unidos, (2) mude o idioma para inglês e (3) copie e cole apenas os valores em inglês. Siga as instruções aqui.

Consulte o emblema Trailhead no seu idioma para saber mais sobre como aproveitar a experiência de Trailhead em outros idiomas.

Diferenças e semelhanças entre a SOQL e a SOSL

Assim como a SOQL, a SOSL permite pesquisar informações específicas nos registros da sua organização. Diferentemente da SOQL, que consulta apenas um objeto padrão ou personalizado de cada vez, uma única SOSL pode pesquisar todos os objetos.

Outra diferença é que a SOSL localiza campos com base na palavra, enquanto a SOQL realiza uma combinação exata por padrão (quando não usa curingas). Por exemplo, pesquisar "Digital" na SOSL resulta em registros cujos valores de campo são "Digital" ou "A empresa digital", porém, a SOQL resulta apenas em registros com valores de campo "Digital".

A SOQL e a SOSL são duas linguagens separadas com sintaxes distintas. Cada linguagem tem um caso de uso diferente:

• Use a SOQL para recuperar registros de um único objeto.
• Use a SOSL para pesquisar campos em diversos objetos. As consultas SOSL podem pesquisar a maioria dos campos de texto em um objeto.

Pré-requisitos

Algumas consultas nesta unidade esperam que a organização tenha contas e contatos. Caso você não tenha criado os dados de amostra na unidade de SOQL, crie-os nesta unidade. Caso contrário, você pode ignorar a criação de dados de amostra nesta seção.

1. No Console do desenvolvedor, abra a janela Executar anônimo no menu Depurar.
2. Insira o trecho de código abaixo na janela e clique em Executar.

// Add account and related contact
Account acct = new Account(
    Name='SFDC Computing',
    Phone='(415)555-1212',
    NumberOfEmployees=50,
    BillingCity='San Francisco');
insert acct;
// Once the account is inserted, the sObject will be 
// populated with an ID.
// Get this ID.
ID acctID = acct.ID;
// Add a contact to this account.
Contact con = new Contact(
    FirstName='Carol',
    LastName='Ruiz',
    Phone='(415)555-1212',
    Department='Wingo',
    AccountId=acctID);
insert con;
// Add account with no contact
Account acct2 = new Account(
    Name='The SFDC Query Man',
    Phone='(310)555-1213',
    NumberOfEmployees=50,
    BillingCity='Los Angeles',
    Description='Expert in wing technologies.');
insert acct2;

Usar o editor de consulta

O Developer Console fornece o console do Editor de consulta, que permite executar consultas SOSL e exibir os resultados. O Editor de consulta oferece uma forma rápida de inspecionar o banco de dados. É uma boa maneira de testar as consultas SOSL antes de adicioná-las ao seu código do Apex. Ao usar o Editor de consulta, é necessário fornecer apenas a instrução de SOSL sem o código do Apex que a rodeia.

Tente executar o seguinte exemplo de SOSL:

1. No Console do desenvolvedor, clique na guia Editor de consulta.
2. Copie e cole o seguinte no primeiro campo do Editor de consulta e, em seguida, clique em Executar.

FIND {Wingo} IN ALL FIELDS RETURNING Account(Name), Contact(FirstName,LastName,Department)

Todos os registros de conta e contatos de sua organização que atendam aos critérios serão exibidos na seção Query Results (Resultados da consulta) como linhas com campos. Os resultados são agrupados em guias para cada objeto (conta ou contato). A consulta SOSL retorna registros que têm campos cujos valores correspondem a Wingo. Com base nos seus dados de amostra, somente um contato tem um campo com o valor Wingo e, portanto, esse contato é retornado.

Nota

A consulta da pesquisa no Editor de consulta e a API devem ser mantidas entre chaves ({Wingo}). Em contraste, no Apex, a consulta de pesquisa é mantida entre aspas simples ('Wingo').

Sintaxe SOSL básica

Esta é a sintaxe de uma consulta SOSL básica no Apex: 

FIND 'SearchQuery' [IN SearchGroup] [RETURNING ObjectsAndFields]

Lembre-se que no Editor de consulta e API, a sintaxe é ligeiramente diferente:

FIND {SearchQuery} [IN SearchGroup] [RETURNING ObjectsAndFields]

SearchQuery é o texto a ser pesquisado (uma palavra única ou frase). Os termos de pesquisa podem ser agrupados com operadores lógicos (AND, OR) e parênteses. Além disso, os termos de pesquisa podem incluir caracteres curingas (*, ?). O curinga * corresponde a zero ou mais caracteres no meio ou no fim do termo de pesquisa. O curinga ? corresponde a apenas um caractere no meio ou no fim do termo de pesquisa.

As pesquisas de texto não diferenciam maiúsculas e minúsculas. Por exemplo, pesquisar por Customer (Cliente), customer (cliente) ou CUSTOMER (CLIENTE) gerará os mesmos resultados.

SearchGroup é opcional. É o escopo dos campos a serem pesquisados. Se não especificado, o escopo de pesquisa padrão é todos os campos. SearchGroup pode ter um dos seguintes valores.

• ALL FIELDS (TODOS OS CAMPOS)
• NAME FIELDS (CAMPOS DE NOME)
• EMAIL FIELDS (CAMPOS DE EMAIL)
• PHONE FIELDS (CAMPOS DE TELEFONE)
• SIDEBAR FIELDS (CAMPOS DE BARRA LATERAL)

ObjectsAndFields é opcional. São as informações resultantes da pesquisa – uma lista de um ou mais sObjects e, dentro de cada sObject, uma lista de um ou mais campos, com valores opcionais para filtragem. Se não especificado, os resultados da pesquisa contêm as IDs de todos os objetos encontrados.

Palavras únicas e frases

Um SearchQuery contém dois tipos de texto:

• Palavra única – uma única palavra, como test (teste) ou hello (olá). As palavras no SearchQuery são delimitadas por espaços, pontuação e mudanças de letras para dígitos (e vice-versa). As palavras nunca diferenciam maiúsculas e minúsculas.
• Frase – coleção de palavras e espaços entre aspas, como "john smith". Várias palavras podem ser combinadas com lógica e operadores de agrupamento para formar uma consulta mais complexa.

Exemplos de pesquisa

Para saber como a pesquisa SOSL funciona, teste diferentes strings de pesquisa e veja qual será o resultado com base na sua amostra de dados. Esta tabela lista vários exemplos de strings de pesquisa e os resultados da pesquisa SOSL.

Exemplo de Apex SOSL

Este exemplo mostra como executar uma consulta SOSL no Apex. Primeiro, a variável soslFindClause é atribuída à consulta de pesquisa, que consiste em dois termos (Wingo e SFDC) combinados pelo operador lógico OR. A consulta SOSL faz referência a esta variável local precedendo-a por dois pontos, também chamado de vinculação. A consulta SOSL resultante procura por Wingo ou SFDC em qualquer campo. Este exemplo fornece todas as contas da amostra, pois cada uma contém um campo com uma das palavras. Os resultados da pesquisa SOSL são exibidos em uma lista de listas. Cada lista contém uma ordem de registros encontrados. Neste caso, a lista possui dois elementos. No índice 0, a lista contém a ordem das contas. No índice 1, a lista contém a ordem dos contatos.

Execute este trecho de código na janela Executar anônimo do Console do desenvolvedor. Em seguida, inspecione o registro de depuração para verificar se todos os registros foram fornecidos.

String soslFindClause = 'Wingo OR SFDC';
List<List<sObject>> searchList = [FIND :soslFindClause IN ALL FIELDS
                    RETURNING Account(Name),Contact(FirstName,LastName,Department)];
Account[] searchAccounts = (Account[])searchList[0];
Contact[] searchContacts = (Contact[])searchList[1];
System.debug('Found the following accounts.');
for (Account a : searchAccounts) {
    System.debug(a.Name);
}
System.debug('Found the following contacts.');
for (Contact c : searchContacts) {
    System.debug(c.LastName + ', ' + c.FirstName);
}

Quero saber mais...

É possível filtrar, reorganizar e limitar os resultados encontrados por uma consulta SOSL. Como as consultas SOSL podem retornar vários sObjects, esses filtros são aplicados em cada sObject dentro da cláusula RETURNING.

Filtre os resultados de SOSL ao adicionar condições na cláusula WHERE de um objeto. Por exemplo, isso resulta apenas em contas cuja indústria a ser encontrada é Apparel: RETURNING Account(Name, Industry WHERE Industry='Apparel').

Da mesma forma, a ordem dos resultados de um sObject é suportada pela adição de ORDER BY para um objeto. Por exemplo, isso faz com que as contas encontradas sejam organizadas pelo Campo de nome: RETURNING Account(Name, Industry ORDER BY Name).

O número de registros encontrados pode ser limitado a um subconjunto de registros. Este exemplo limita as contas encontradas a apenas 10: RETURNING Account(Name, Industry LIMIT 10).