Scrivere query SOSL

• Descrivere le differenze tra SOSL e SOQL.
• Cercare campi in più oggetti utilizzando le query SOSL.
• Eseguire query SOSL utilizzando Query Editor nella Developer Console.

Nota

Stai seguendo la formazione in italiano? In questo badge, la convalida delle sfide pratiche di Trailhead funziona in inglese. Le traduzioni sono fornite tra parentesi come riferimento. Nel tuo Trailhead Playground, accertati di (1) selezionare Stati Uniti per le impostazioni internazionali, (2) impostare la lingua su Inglese e (3) copiare e incollare soltanto i valori in lingua inglese. Segui le istruzioni qui.

Visita il badge Trailhead nella tua lingua per informazioni dettagliate su come usufruire dell'esperienza Trailhead in altre lingue.

Differenze e somiglianze tra SOQL e SOSL

Come SOQL, anche SOSL ti permette di eseguire ricerche sui record dell'organizzazione per trovare informazioni specifiche. A differenza di SOQL, però, che può eseguire query su un solo oggetto standard o personalizzato per volta, una singola query SOSL può eseguire una ricerca su tutti gli oggetti.

Un'altra differenza consiste nel fatto che SOSL confronta i campi in base alla corrispondenza di parole, mentre SOQL esegue una corrispondenza esatta per impostazione predefinita (quando non si utilizzano i caratteri jolly). Ad esempio, la ricerca di "Digital" in SOSL restituisce i record i cui valori di campo sono "Digital" o "The Digital Company", ma SOQL restituisce solo i record che contengono campi il cui valore è "Digital".

SOQL e SOSL sono due linguaggi separati con una sintassi diversa. Ciascun linguaggio ha un caso d'uso distinto:

• SOQL viene utilizzato per recuperare i record di un singolo oggetto.
• SOSL viene utilizzato per eseguire ricerche sui campi di più oggetti. Le query SOSL possono eseguire ricerche sulla maggior parte dei campi di testo di un oggetto.

Prerequisiti

Alcune query di questa unità prevedono che l'organizzazione disponga di account e referenti. Se non hai creato i dati di esempio nell'unità SOQL, creali in questa unità. In caso contrario, puoi saltare la creazione dei dati di esempio in questa sezione.

1. Nella Developer Console, apri la finestra Execute Anonymous (Esecuzione anonima) nel menu Debug.
2. Inserisci nella finestra lo snippet riportato di seguito e fai clic su Execute (Esegui).

// 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;

Utilizzare Query Editor

La Developer Console offre la console Query Editor, che permette di eseguire le query SOSL e visualizzare i risultati. Query Editor è uno strumento che consente di ispezionare rapidamente il database. È un valido strumento per testare le query SOSL prima di aggiungerle al codice Apex. Quando si utilizza Query Editor, è necessario fornire solo l'istruzione SOSL senza il codice Apex in cui è inserita.

Proviamo a eseguire il seguente esempio di SOSL:

1. Nella Developer Console, fai clic sulla scheda Query Editor.
2. Copia e incolla quanto segue nella prima casella di Query Editor, quindi fai clic su Execute (Esegui).

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

Tutti i record degli account e dei referenti dell'organizzazione sono visualizzati nella sezione Query Results (Risultati della query) come righe con campi. I risultati sono raggruppati in schede per ciascun oggetto (account o referente). La query SOSL restituisce i record che hanno campi i cui valori corrispondono a Wingo. In base ai nostri dati di esempio, solo un referente ha un campo con il valore Wingo, quindi viene restituito quel referente.

Nota

La query di ricerca in Query Editor e nell'API deve essere racchiusa tra parentesi graffe ({Wingo}). In Apex, invece, la query di ricerca è racchiusa tra virgolette singole (Wingo).

Sintassi SOSL di base

Questa è la sintassi di una query SOSL di base in Apex: 

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

Ricorda che in Query Editor e nell'API la sintassi è leggermente diversa:

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

SearchQuery è il testo da ricercare (una singola parola o frase). I termini di ricerca possono essere raggruppati con operatori logici (AND, OR) e parentesi. Inoltre, i termini di ricerca possono includere caratteri jolly (*, ?). Il carattere jolly * corrisponde a zero o più caratteri al centro o alla fine del termine di ricerca. Il carattere jolly? corrisponde a un solo carattere al centro o alla fine del termine di ricerca.

Le ricerche di testo non fanno distinzione tra maiuscole e minuscole. Ad esempio, la ricerca di Customer (Cliente), customer (cliente) o CUSTOMER (CLIENTE) restituisce sempre gli stessi risultati.

SearchGroup è opzionale. Indica l'ambito dei campi da ricercare. Se non viene specificato, l'ambito di ricerca predefinito include tutti i campi. SearchGroup può assumere uno dei seguenti valori.

• ALL FIELDS
• NAME FIELDS
• EMAIL FIELDS
• PHONE FIELDS
• SIDEBAR FIELDS

ObjectsAndFields è opzionale. Si tratta delle informazioni da restituire nel risultato della ricerca: un elenco di uno o più sObject e, all'interno di ciascun sObject, un elenco di uno o più campi, con valori opzionali da filtrare. Se non viene specificato, i risultati della ricerca contengono gli ID di tutti gli oggetti trovati.

Parole singole e frasi

SearchQuery può contenere due tipi di testo:

• Parola singola: una parola singola, ad esempio test oppure hello (ciao). Le parole nella SearchQuery sono delimitate da spazi, punteggiatura e passaggi da lettere a cifre (e viceversa). Le parole non fanno mai distinzione tra maiuscole e minuscole.
• Frase: un insieme di parole e spazi racchiusi tra virgolette doppie, ad esempio "john smith". È possibile combinare più parole con operatori logici e di raggruppamento per formare una query più complessa.

Esempi di ricerca

Per capire il funzionamento della ricerca SOSL, proviamo a usare diverse stringhe di ricerca e vediamo qual è l'output in base ai nostri dati di esempio. In questa tabella sono riportati vari esempi di stringhe di ricerca e i risultati della ricerca SOSL.

Esempio di query SOSL in Apex

L'esempio seguente mostra come eseguire una query SOSL in Apex. Per prima cosa, alla variabile soslFindClause viene assegnata la query di ricerca, che consiste di due termini (Wingo e SFDC) combinati dall'operatore logico OR. La query SOSL fa riferimento a questa variabile locale facendola precedere dal segno dei due punti, detto anche binding. La query SOSL risultante cerca Wingo o SFDC in qualsiasi campo. Questo esempio restituisce tutti gli account di esempio perché ciascuno di essi ha un campo contenente una delle parole. I risultati della ricerca SOSL vengono restituiti in un elenco di elenchi. Ciascun elenco contiene un array di record restituiti. In questo caso, l'elenco è composto da due elementi. All'indice 0, l'elenco contiene l'array degli account. All'indice 1, l'elenco contiene l'array dei referenti.

Esegui questo snippet nella finestra Execute Anonymous (Esecuzione anonima) della Developer Console. Successivamente, ispeziona il registro di debug per verificare che tutti i record vengano restituiti.

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);
}

Ulteriori informazioni...

Puoi filtrare, riordinare e limitare i risultati restituiti da una query SOSL. Poiché le query SOSL possono restituire più sObject, i filtri vengono applicati a ciascun sObject all'interno della clausola RETURNING.

Puoi filtrare i risultati della query SOSL aggiungendo condizioni nella clausola WHERE relativa a un oggetto. In questo esempio vengono restituiti solo gli account il cui settore è Apparel (Abbigliamento): RETURNING Account(Name, Industry WHERE Industry='Apparel').

Allo stesso modo, l'ordinamento dei risultati per un sObject è supportato dall'aggiunta di ORDER BY per un oggetto. In questo esempio, gli account restituiti vengono ordinati in base al campo Name (Nome): RETURNING Account(Name, Industry ORDER BY Name).

Il numero di record restituiti può essere limitato a un sottoinsieme di record. In questo esempio gli account restituiti sono limitati a 10 soltanto: RETURNING Account(Name, Industry LIMIT 10).