| name | sosl-search-patterns |
| description | Use when choosing or implementing SOSL for cross-object or full-text search, especially around SOSL vs SOQL, search groups, result shaping, and injection-safe dynamic search. Triggers: 'SOSL', 'FIND clause', 'cross object search', 'Search.query', 'SOSL injection'. NOT for structured record retrieval where ordinary SOQL filters are the right tool. |
| category | data |
| salesforce-version | Spring '25+ |
| well-architected-pillars | ["Performance","User Experience"] |
| tags | ["sosl","search-query","find-clause","search-layouts","injection","list-view","returning-clause"] |
| triggers | ["when should I use SOSL instead of SOQL","cross object search in Salesforce Apex","Search.query SOSL injection prevention","FIND clause wildcard behavior","search layouts for global search style results","search query isn't working","scope a SOSL search to a single list view","search within a Salesforce list view using SOSL","escape reserved characters in a SOSL FIND clause","escape a special character in a SOQL LIKE query","combine AND, OR, and AND NOT in a SOSL FIND clause","paginate SOSL results with OFFSET inside a RETURNING clause","filter or sort one object's slice in a SOSL RETURNING clause"] |
| inputs | ["search use case and whether it spans one object or many","expected result volume and UI shape","whether the query is static SOSL or dynamic `Search.query`"] |
| outputs | ["SOSL versus SOQL recommendation","review findings for search performance and injection risk","search pattern for result shaping and object grouping"] |
| dependencies | [] |
| version | 1.4.0 |
| author | Pranav Nagrecha |
| updated | "2026-07-08T00:00:00.000Z" |
Sosl Search Patterns
Use this skill when the user experience is search, discovery, or typeahead rather than a structured filter form. SOSL is the right tool when the system needs full-text style search across fields or across multiple objects, and it becomes the wrong tool when the query is actually a precise relational filter that SOQL can express cleanly.
Before Starting
Gather this context before working on anything in this domain:
- Is the use case global or cross-object search, or is it really one-object filtering?
- Does the UI need a few best matches quickly, or does it need exhaustive reporting-style results?
- Will the query be static SOSL with bind variables, or dynamic search text assembled in code?
Core Concepts
SOSL Is For Search, SOQL Is For Structured Retrieval
Use SOSL when the user knows a word, phrase, or partial value and wants matching records across one or more objects. Use SOQL when the app already knows the object and wants relational filters, sorting, and explicit field constraints.
Search Groups And Result Shape Matter
SOSL can search different field groups and return results grouped by object. That makes it a strong fit for search experiences but a poor fit for workflows that expect one neat tabular result set like SOQL.
Injection Safety Changes With Dynamic Search
Static SOSL with bind variables is the clean path. Dynamic Search.query usage needs careful input handling so search strings are not built unsafely from user input.
Search UX Needs Limits And Relevance Discipline
Search is a user-experience feature first. Teams should design for top matches, sensible caps, and clear object grouping instead of flooding the page with everything the platform can return.
A Search Can Be Scoped To One List View
The optional USING ListView=<Name> clause narrows a RETURNING object to the records inside a single named list view instead of the whole object. Salesforce searches only the first 2,000 records of that list view, using the sort order the user has set on the view, so the clause is a scoping decision — the list view defines which records are eligible before the FIND text is matched. Only one list view can be specified, the clause is available in API version 41 or later, and it works in SOAP API, REST API, and Apex.
RETURNING Shapes Each Object's Result Slice
USING ListView is one of several sub-clauses RETURNING can attach to an object; the full per-object shape is ObjectTypeName(FieldList WHERE ... USING ListView=... ORDER BY ... LIMIT n OFFSET n), and the sub-clauses must appear in that order, with at least one field present in before any of them. is a comma-separated list of one or more fields; relationship fields (e.g. ) follow SOQL's format and depth rules. The per-object filters matched rows by field value — distinct from the term, which decides what matched — and sorts that object's slice. Two row caps bite: with no each object returns at most 2,000 rows (API v28+), and an explicit still tops out at 2,000, so SOSL is not a bulk-extraction tool. pages the result set but is legal and must be the last sub-clause. When more than one object is named, each must be distinct. (A separate class of object types — external objects, articles, documents, feed comments, feed items, files, products, and solutions — is invisible unless named explicitly in ; see gotchas.)
