Intermediate 20 min read

Your First SOSL Search

By the end of this lesson, you'll be able to:

  • Write a basic SOSL search using FIND and RETURNING
  • Run a SOSL search in Apex and read the result structure
  • Explain what a List<List<sObject>> represents in this context

Prerequisites: "What Is SOSL?"

The basic shape

List<List<sObject>> searchResults = [
    FIND 'Riverbend Farms' IN ALL FIELDS
    RETURNING Account(Id, Name)
];

List<Account> matchingAccounts = searchResults[0];
System.debug(matchingAccounts.size());
  1. List<List<sObject>> searchResults = [ — opens the search, stored as a list of lists.
  2. FIND 'Riverbend Farms' IN ALL FIELDS — FIND names the search text; IN ALL FIELDS means search every searchable text field.
  3. RETURNING Account(Id, Name) — names which fields to return for matching Account records.
  4. ]; — closes the search.
  5. (blank line)
  6. List<Account> matchingAccounts = searchResults[0]; — the first (and only) inner list, holding the Account matches.
  7. System.debug(matchingAccounts.size()); — logs how many matched.

Why a List of Lists

List<List<sObject>> searchResults = [
    FIND 'Riverbend Farms' IN ALL FIELDS
    RETURNING Account(Id, Name), Contact(Id, LastName)
];

List<Account> accounts = searchResults[0]; // matches from Account
List<Contact> contacts = searchResults[1]; // matches from Contact
  1. List<List<sObject>> searchResults = [ — this is exactly Module 16's "Nested Collections" pattern applied to search results.
  2. FIND 'Riverbend Farms' IN ALL FIELDS — the search text and scope.
  3. RETURNING Account(Id, Name), Contact(Id, LastName) — now two object types named, in this order.
  4. ]; — closes the search.
  5. (blank line)
  6. List<Account> accounts = searchResults[0]; — the outer List has one entry per object named in RETURNING, in the same order — index 0 for the first object named.
  7. List<Contact> contacts = searchResults[1]; — index 1 for the second.

sObject typing on the inner Lists

List<Account> matchingAccounts = (List<Account>) searchResults[0];
  1. List<Account> matchingAccounts = (List<Account>) searchResults[0]; — depending on how the result is used, the inner List<sObject> may need casting to its specific type — this is Module 18's sObject polymorphism concept (a specific type can be cast back down from the generic base type) showing up directly in a real SOSL result.

Exercise

Write a SOSL search for 'Acme' returning Id and Name from Account, and debug the number of matches found.

Show hint

FIND 'Acme' IN ALL FIELDS RETURNING Account(Id, Name)

Salesforce: ○ Not connected Connect
APEX

Execution Results

Run your code to see the result.

Your First SOSL Search Quiz

1. What does searchResults[0] represent when RETURNING Account(Id, Name), Contact(Id, LastName) is used?

Log in to submit the quiz and save your score.

My Notes

Log in to keep private notes on this lesson.

Questions about this lesson

No questions yet — be the first to ask.

Log in to ask a question about this lesson.

Summary

A basic SOSL search names the text to find and which object(s) to return matches from — in Apex, the result comes back as a List of Lists, one inner List per object type searched.