Écriture de requêtes SOSL

• Décrire les différences entre SOSL et SOQL
• Rechercher des champs dans plusieurs objets en utilisant des requêtes SOSL
• Exécuter des requêtes SOSL en utilisant l'éditeur de requête de la Developer Console

Remarque

Vous souhaitez apprendre en français ? Dans ce badge, les validations de défi pratique Trailhead se font en anglais. Les traductions sont fournies entre parenthèses à titre de référence. Dans votre Trailhead Playground, veillez (1) à définir les États-Unis comme région, (2) à sélectionner l’anglais comme langue, et (3) à copier et coller uniquement les valeurs en anglais. Suivez les instructions ici.

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

Différences et similitudes entre SOQL et SOSL

De la même façon que SOQL, SOSL permet de rechercher des informations spécifiques dans les enregistrements de votre organisation. Contrairement à SOQL, qui peut interroger un seul objet standard ou personnalisé à la fois, une requête SOSL unique peut effectuer une recherche dans tous les objets.

Autre différence, SOSL mappe les champs à l'aide d'une correspondance sur un mot, alors que SOQL effectue une correspondance exacte par défaut (quand aucun caractère générique n'est utilisé). Par exemple, le fait de rechercher « Numérique » dans SOSL renvoie les enregistrements où des champs contiennent les valeurs « Numérique » ou « La société numérique », alors que SOQL renvoie uniquement les enregistrements où des champs contiennent la valeur « Numérique ».

SOQL et SOSL sont deux langages distincts avec des syntaxes différentes. Chaque langage a une utilisation spécifique :

• Utilisez SOQL pour récupérer les enregistrements d'un objet unique.
• Utilisez SOSL pour effectuer des recherches au sein des champs de plusieurs objets. Les requêtes SOSL peuvent effectuer des recherches au sein de la plupart des champs de texte d'un objet.

Prérequis

Certaines requêtes de cette unité supposent que l'organisation possède des comptes et des contacts. Si vous n'avez pas créé l’exemple de données dans l'unité relative à SOQL, créez un exemple de données dans le cadre de cette unité. Sinon, vous pouvez ignorer l’étape de création d'un exemple de données de cette section.

1. Dans la Developer Console, ouvrez la fenêtre Execute Anonymous (Exécution anonyme) depuis le menu Debug (Débogage).
2. Insérez l'extrait ci-dessous dans la fenêtre, puis cliquez sur Execute (Exécuter).

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

Utilisation de l’éditeur de requête

La Developer Console fournit la console Query Editor (Éditeur de requête), qui permet d'exécuter des requêtes SOSL et d'afficher les résultats. L'éditeur de requête permet d'inspecter rapidement la base de données. Il est efficace pour tester les requêtes SOSL avant de les ajouter à un code Apex. Lorsque vous utilisez l'éditeur de requête, vous devez indiquer uniquement l'instruction SOSL, sans le code Apex qui l'entoure.

Essayons d'exécuter l'exemple SOSL suivant :

1. Dans la Developer Console, cliquez sur l’onglet Query Editor (Éditeur de requête).
2. Copiez et collez l'élément ci-dessous dans la première zone sous Query Editor (Éditeur de requête), puis cliquez sur Execute (Exécuter).

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

Tous les enregistrements de compte et de contact de votre organisation qui remplissent les critères sont affichés dans la section Query Results (Résultats de requête), sous forme de lignes avec des champs. Les résultats sont regroupés dans des onglets pour chaque objet (compte ou contact). La requête SOSL renvoie les enregistrements dont les champs ont des valeurs correspondant à Wingo. Avec notre exemple de données, un seul contact a un champ avec la valeur Wingo. Par conséquent, ce contact est renvoyé.

Remarque

Dans l'éditeur de requête et dans l'API, la requête de recherche doit être entre accolades ({Wingo}). Par contre, dans Apex, la requête de recherche est entre guillemets simples ('Wingo').

Syntaxe SOSL de base

La syntaxe d’une requête SOSL de base dans Apex est la suivante : 

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

N’oubliez pas que dans l’éditeur de requête et l’API, la syntaxe est légèrement différente :

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

SearchQuery est le texte à rechercher (un mot unique ou une phrase). Les termes de recherche peuvent être regroupés avec des opérateurs logiques (AND, OR) et des parenthèses. Les termes de recherche peuvent également inclure des caractères génériques (*, ?). Le caractère générique * correspond à aucun ou à d'autres caractères au milieu ou à la fin des termes recherchés. Le caractère générique ? correspond à un seul caractère au milieu ou à la fin des termes recherchés.

Les recherches de texte sont insensibles à la casse. Par exemple, les recherches portant sur Customer (Client), customer (client) ou CUSTOMER (CLIENT) renvoient toutes les mêmes résultats.

SearchGroup est facultatif. Il correspond à l'étendue des champs à rechercher. S'il n'est pas défini, l'étendue de recherche par défaut est All fields (Tous les champs). SearchGroup doit contenir l'une des valeurs suivantes :

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

ObjectsAndFields est facultatif. Il correspond aux informations à renvoyer dans les résultat de recherche : une liste d'un ou de plusieurs sObjects et, dans chaque sObject, une liste d'un ou de plusieurs champs, avec des valeurs de filtre facultatives. S'il n'est pas défini, les résultats de recherche contiennent les ID de tous les objets trouvés.

Mots uniques et phrases

Une SearchQuery contient deux types de texte :

• Mot unique : un seul mot, par exemple test ou hello. Les mots de la SearchQuery sont séparés par des espaces, des signes de ponctuation et des alternances entre des lettres et des chiffres (et inversement). Les mots sont toujours insensibles à la casse.
• Phrase : un ensemble de mots et d'espaces entre guillemets, par exemple "john smith". Plusieurs mots peuvent être combinés à l'aide d'opérateurs logiques et de regroupements pour former une requête plus complexe.

Exemples de recherche

Pour comprendre le fonctionnement de la recherche SOSL, essayons différentes chaînes de recherche et examinons la source des résultats avec notre exemple de données. Le tableau ci-dessous présente plusieurs exemples de chaînes de recherche avec les résultats de recherche SOSL.

Exemple de requête Apex SOSL

Cet exemple montre comment exécuter une requête SOSL en Apex. Tout d’abord, la variable soslFindClause se voit attribuer la requête de recherche, composée de deux termes (Wingo et SFDC) combinés par l’opérateur logique OR. La requête SOSL référence cette variable locale en la faisant précéder d’un signe deux-points, également appelé liaison. La requête SOSL résultante recherche Wingo ou SFDC dans n’importe quel champ. Cet exemple renvoie tous les exemples de compte, car ils ont chacun un champ qui contient l'un des termes. Les résultats de la recherche SOSL sont renvoyés dans une liste de listes. Chaque liste contient un tableau des enregistrements renvoyés. Dans cet exemple, la liste contient deux éléments. À l'index 0, la liste contient le tableau des comptes. À l'index 1, la liste contient le tableau des contacts.

Exécutez l'extrait ci-dessous dans la fenêtre Execute Anonymous (Exécution anonyme) de la Developer Console. Examinez ensuite le journal de débogage pour vérifier que tous les enregistrements sont renvoyés.

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

En savoir plus…

Vous pouvez filtrer, réorganiser et limiter les résultats renvoyés d'une requête SOSL. Les requêtes SOSL peuvent renvoyer plusieurs sObjects. Par conséquent, ces filtres sont appliqués dans chaque sObject dans la clause RETURNING.

Vous pouvez filtrer les résultats SOSL en ajoutant des conditions dans la clause WHERE d'un objet. Dans cet exemple, seuls les comptes dont le secteur d'activité est Apparel (Habillement) sont renvoyés : RETURNING Account(Name, Industry WHERE Industry='Apparel').

De la même façon, le classement des résultats d'un sObject est pris en charge en ajoutant ORDER BY pour un objet. L'exemple suivant entraîne le classement des comptes renvoyés en fonction du champ Name (Nom) : RETURNING Account(Name, Industry ORDER BY Name).

Le nombre d'enregistrements renvoyés peut être limité à un sous-ensemble d'enregistrements. Cet exemple limite les comptes renvoyés à 10 : RETURNING Account(Name, Industry LIMIT 10).