Search Is Not Query

🌐 Also in 19 languages

Español · 日本語 · Português (Brasil) · Français · Deutsch · Italiano · 한국어 · 简体中文 · Português (Portugal) · 繁體中文 · Bahasa Indonesia · Türkçe · Polski · Tiếng Việt · ไทย · Українська · Español (México) · Français (Canada) · Deutsch (Schweiz)

Image generated with AI

Module 5 of 5 in the chapter Query and Retrieval Architecture, chapter 8 of the Data Architect course. Each module stands on its own. Previous: How Salesforce Executes a Query · Next: the next chapter, Integration and Data Movement

The question this module answers: When should you search instead of query?

Three modules on queries, indexes, selectivity, query plans and skinny tables all assume one thing: you know what you’re looking for. Today’s deliveries for Redrock. Cases modified since yesterday. The delivery with partner reference DLV-8472914. Structured questions. But people don’t always ask structured questions. Sometimes they say, “I remember the customer mentioned a damaged refrigerator in Tempe. Can you find it?” That isn’t really a query problem. It’s search. And search is not query.

Query Starts With Structure; Search Starts With a Term

SOQL is fantastic when we know the structure: the object, the field, the condition. Work orders where the Retail Partner is Redrock and the scheduled date is today. We know where the information lives, how it’s represented and what we’re testing, and the database can use everything we’ve designed this chapter.

Now: “find the record with the phrase broken refrigerator.” Which object? A case, a work order, a note? Subject, description, another text field? The user doesn’t know, and shouldn’t have to. That’s where SOSL, the Salesforce Object Search Language, comes in. Instead of “which field should I filter?” it starts with “find this text.” A fundamentally different retrieval problem.

I’ve watched developers force search into SOQL. “Let the user type some text and find the customer,” and the query grows: Name LIKE … OR Email LIKE … OR Phone LIKE … OR Description LIKE … OR another field, and another. At some point, stop and ask: are we querying, or searching? If the requirement is text discovery across fields, SOSL may be the cleaner tool. That’s what it’s for. Don’t force a search problem into a query shape because SOQL is the tool you use most.

Remember the hardest case from module 3: contains. Description LIKE '%refrigerator%' has no way into the drawer, so the librarian walks every shelf. Search was built for exactly that question. Salesforce says it directly: “When a given search can use either language, SOSL is generally faster than SOQL if the search expression uses a CONTAINS term,” because “SOSL can tokenize multiple terms within a field (for example, multiple words separated by spaces) and builds a search index off this.” Looking for “John” in “Paul and John Company” is a search question (Using SOQL and SOSL (opens in a new tab), Best Practices for Deployments with Large Data Volumes, Winter ‘27).

Click to enlarge

“Contains” forced into a query: no way into an index. Slow.

Click to enlarge

The same words, asked as a search: straight to the matches. Query knows the structure. Search knows the term.

How Search Works: Tokens First, Then the Fetch

Back to the library. A database index is the catalog for “books by this author” or “books with this identifier.” Now I want every book containing the phrase “broken refrigerator.” Reading every page of every book for each search would be ridiculous, so search builds its own index over the words. “The Salesforce search architecture is based on its own data store, which is optimized for searching for that text” (Search Architecture (opens in a new tab), Winter ‘27): a different engine for a different kind of question.

How does it fill that store? “When you create a record, the search engine breaks up the searchable content into smaller pieces, called tokens. It stores the tokens in a search index. The search index is much like a book index—each token in the index has a link back to the record it came from” (How Einstein Search Works (opens in a new tab), Salesforce Help). When you search, your words are broken into tokens the same way and matched against that index.

And then comes a step people miss. “Salesforce performs indexed searches by first searching the indexes for appropriate records, then narrowing down the results based on access permissions, search limits, and other filters … The result set is then used to query the records from the database to retrieve the fields that a user sees” (Search Architecture (opens in a new tab)). In module 4’s four words: search finds which records in its own index, and then a regular fetch from the database brings back their fields. Two engines, one after the other.

And it’s not only the search box. Salesforce lists search behind “Advanced and global searches”, “Find boxes and lookup fields”, “Suggested Solutions and Knowledge Base”, “Web-to-Lead and Web-to-Case”, “Duplicate lead processing”, and SOSL from Apex and the API (same source). Like the librarian, search is working in places nobody thinks of as “search.”

Freshness Is Part of the Design

That index is asynchronous. New and changed records are queued and indexed by separate servers, and “it could take about 15 minutes or more for the updated text to become searchable” (Search Architecture (opens in a new tab)). Big loads take longer: “If a record is created or updated using bulk API, it may take more than 15 minutes for the record to be searchable … wait for a few hours for it to be indexed” (How Einstein Search Works (opens in a new tab)). So after a migration, the search index is behind for a while, just as module 4’s notebook of statistics is behind until the nightly run.

So search and query have different freshness. Steve Trucking creates a case at 10:00; at 10:01 a SOQL query returns it, while a text search for words in its description depends on whether the search index has caught up. That isn’t a defect. It’s a property of the mechanism. “The moment a delivery exception is created, our automation must find it.” Would I build that on text search? No. The process knows the work order, the exception type, the date and the status, so a structured query is the deterministic choice. “A care agent wants old cases where customers mentioned damaged refrigerators”? Search makes far more sense. Different requirement, different engine, different freshness. Choose the retrieval mechanism from the question, not from habit.

Search Crosses Objects, and Can Find Too Much

One of SOSL’s strengths is that the user doesn’t need to know which object holds the answer. A coordinator searches “Henderson,” and it might be an account, a contact, a work order or a case. The user is looking for the thing, not thinking “first query Contact.LastName, then Account.Name, then the work order’s Recipient, then case descriptions.” Search matches how people actually look for information.

That creates another problem. Make everything searchable (every object, field, historical record, every bit of text) and then search “Smith,” and the user is overwhelmed. Search didn’t fail; it found too much. That’s search crowding, and at scale it matters as much as speed.

Search Crowding, Step by Step

Salesforce defines it plainly: “Search crowding–having too many unhelpful search results–can overwhelm you with irrelevant records and slow down search. To avoid search crowding, the search engine limits the number of records it analyzes” (How Search Crowding Affects Search Results (opens in a new tab), Salesforce Help). The limit is there to protect search. The cost is that the record you wanted can fall outside it.

Let’s walk through one search. A Steve Trucking care agent is looking for a case about a damaged refrigerator for a customer named Henderson. She types Henderson into global search. Henderson is also a city, so the word appears on thousands of delivery addresses. Salesforce’s own example uses these numbers, so let’s use them too:

1. Every record that matches. The search index finds 3,200 records with the word Henderson: accounts, contacts, cases, and a great many work orders.
2. The limit. “Search limits the results to the first 2,000 records found, so 1,200 records aren’t included in your search results” (same source). If her case is among those 1,200, it’s gone before anything else happens.
3. Permissions. Only now does search check what she can see. “Search analyzes only 2,000 records, which can include records you don’t have access to. Of the 2,000 analyzed, you don’t have access to 100 of them so you don’t see them in your results. You only see 1,900 records returned” (same source). Those 100 still took up room in the 2,000. Read that again: the cutoff comes before sharing, so records she will never see can take places in the 2,000 and push the record she needs past the line.
4. Shared out across objects. When a search names several objects, the 2,000 are shared out. In Salesforce’s words: “If you query one object only, a maximum of 250 records are returned. To return up to 2,000 results, include either the WHERE clause or ORDER BY clause. If you query multiple objects, each object returns up to the minimum number between 2,000/n (where n=number of objects) and 250.” Search ten objects at once and each one gets at most 200. And the results aren’t the same for everyone: “Admins (users with the View All Data permission) see the full set of results returned”, while other users see only what they have access to, and “Results sets and order vary by the user issuing the search and can change throughout the day as records are added or removed from the index” (same source). The order varies too: Salesforce ranks results “based on search term frequency, order, uniqueness, record activity, and access permissions. Search result relevance can vary for each user” (How Einstein Search Works (opens in a new tab)). So when someone says “I searched and it wasn’t there,” the first questions are: how many records matched before the limit, and who were you?
5. Ranked. What’s left is put in order of relevance, so even when her case survives, it may be far down the list under 1,900 other Hendersons.

Click to enlarge

The cutoff comes first, sharing second. Records she can’t see take places in the 2,000, and her case lands in the discarded bucket.

Now push it to the worst case the mechanics allow. An object holds 100,000 records, and sharing lets this user see 1,000 of them. She’s looking for 10 specific records, and she can see all 10. Her search term matches 3,000 records. The first 2,000 found are all records she can’t see; her 10 are among the 1,000 past the cutoff, in the discarded bucket. Sharing removes all 2,000 that were kept, and she gets no results, for records she knows are there and is allowed to see.

Click to enlarge

Visible to her, and still not found: the 2,000 places went to records she can’t see.

To be fair to Salesforce, this is the edge, not the everyday. The same Help article says: “The search engine’s priority is to return accessible records for users with limited access in an org” (How Search Crowding Affects Search Results (opens in a new tab)), and relevance takes access into account. Most of the time that keeps users with narrow access out of this trap. But when someone with limited access swears a record is missing from search and then finds it by opening a list view, this is why, and the fix is the same: a more specific search, fewer objects, fewer records that compete.

That’s the heart of it. “The search engine looks for matches to the search term across a maximum of 2,000 records”, and only then applies each user’s permissions, so the user sees only what they’re allowed to (SOSL Limits on Search Results (opens in a new tab), SOQL and SOSL Reference). So 2,000 irrelevant matches, including records this user can’t even see, can crowd out the one they wanted before sharing ever trims the list. The question isn’t only “how fast is search?” It’s did we design search so the useful answer can surface?

So when someone says “I searched and it wasn’t there,” the first questions are: how many records matched before the limit, how many objects were searched, and who was searching?

Mitigating Search Crowding: A Playbook

The fix is always the same idea: fewer, better matches before the limit. Here’s the playbook I’d hand an admin and an architect when someone says “I searched and it wasn’t there.” Work through it in order.

Click to enlarge

Rule out freshness, access and searchability first. Then measure.

Step 1: Rule Out the Other Causes

Not every missing record is crowding. Check the simple causes first:

• Is it too new? Text can take a few minutes to be indexed, and “If a record is created or updated using bulk API, it may take more than 15 minutes for the record to be searchable … wait for a few hours” (How Einstein Search Works (opens in a new tab)). A record loaded this morning may not be searchable yet.
• Can this user see it? Open it from a list view or report as that user. If they can’t, it’s access, not search. “Admins can also check profile and permission settings for access to objects” (How Search Crowding Affects Search Results (opens in a new tab)).
• Is the object searchable at all? “By default, search is disabled for new custom objects. Admins enable Allow Search when setting up new custom objects” (though “A custom object that’s associated with a custom tab is searchable by default”) (Searchable Fields: Custom Object (opens in a new tab)). And remember the 120-day rule: an unsearched custom object can lose searchability.
• Does an exact, unique term find it? Search for something only that record has, like its full name or reference number. If that works and the broad term doesn’t, you’re looking at crowding.

Step 2: Measure the Crowd

Search the broad term again, then search it in one object at a time. If a search comes back at the limit, 2,000 overall or 250 for a single object without a WHERE or ORDER BY, the results were cut off. Note which object supplies most of the matches. In the Henderson example, it’s the work orders, whose delivery addresses are full of the word.

Step 3: Cut the Noise at the Source

Data can deserve to exist without deserving to appear in search. These are Setup changes, made in Search Manager (“To use Search Manager: Customize Application AND View Setup”). Do them in this order, from the cheapest to the most structural:

1. Turn off objects these users don’t search, by profile. “You can manage searchable objects for each profile in global search.” From Setup, enter Search Manager, select Query Configurations, select the configuration, and “in the Objects List, select an object and turn searchability on or off” (Manage Searchable Objects and Fields (opens in a new tab)). If care agents never look for work order line items, their profile shouldn’t search them.
2. Take noisy custom fields out of the index. From Setup, enter Search Manager, select Index Management, choose the object, and next to the field choose Remove from search index. “Removed fields don’t appear in search results and aren’t used to match results. You can’t remove standard fields,” and “Your changes can take a few hours” (Manage the Search Index (opens in a new tab)). A long description or address field that matches everything is a good candidate.
3. For an object nobody should search, disable its search index. That stops “making its data searchable and stop[s] index credit consumption for that object” (Explore the Search Index with Search Manager (opens in a new tab)).
4. Archive history that no longer needs to be found. Old completed work orders stay in the index and keep competing. Archiving (chapter 7 and module 4’s wrap-up) shrinks the crowd for search and for queries.
5. Put identifiers where search looks first. A lookup searches only the record name, and a NAME search group only name fields. If people find a delivery by its partner reference, make sure that value lives in a field search treats as a name or identifier.

Step 4: Fix the Searches You Build

For every custom search, in Apex, in a component or in an agent’s tool:

• Return only the objects the question needs, each with a WHERE: “For SOSL, selective filters reduce the number of irrelevant results” (SOQL and SOSL (opens in a new tab), best practices, Winter ‘27).
• Use a search group: IN NAME FIELDS, EMAIL or PHONE, so an address field full of “Henderson” doesn’t match a name search.
• Prefer specific terms to wildcards, and single-object searches “for greater speed and accuracy” (Searching (opens in a new tab), best practices, Winter ‘27). The next section, Asking Search Well, has the details.

Step 5: Teach the People Searching

Put three habits in the training and the help text:

• A more specific term: “Use a more specific search term, such as Industrial Computing San Francisco” (How Search Crowding Affects Search Results (opens in a new tab)). For our agent, Henderson refrigerator, or the customer’s full name.
• One kind of record: “if you’re looking for an account record, search for Industrial Computing in Accounts” (same source).
• The complete name in a lookup: “A lookup search uses only the record name”, so “enter Jupiter Hotels instead of just Hotels” (same source).

Click to enlarge

The same search, done well: a specific term in one object, and her case comes through.

Step 6: Verify as That User

Index changes “can take a few hours”, so check the next day, not the next minute. Repeat the original search as a user with that profile, not as an admin. An admin with View All Data sees results other users don’t, so an admin’s search proves nothing about crowding.

Step 7: Keep It Healthy

Searchability drifts as an org grows, so make it part of the regular review:

• When a new object or a big text field arrives, decide on purpose whether it’s searchable, and for which profiles.
• Watch the 120-day rule for custom objects people search only rarely.
• Keep sensitive fields out of the index. Search applies field-level security only to “up to 100 searchable custom fields per object” (Explore the Search Index with Search Manager (opens in a new tab)), and Salesforce’s advice is direct: “If a field contains sensitive information and you couldn’t apply field-level security to it, remove the field from the index” (Manage the Search Index (opens in a new tab)).

Click to enlarge

Fewer, better matches before the limit. Three people can make that happen.

Asking Search Well

You don’t need to write SOSL to be an architect, but you should recognize the levers, because they’re how you keep the right answer from being crowded out:

• Search groups. Search only the kinds of fields that matter: “Search groups include NAME, EMAIL, and PHONE fields. For example, FIND ‘Avery Smith’ IN NAME FIELDS RETURNING Account(Id,Name), Lead(Id,Name)” (same source).
• RETURNING. Name the objects, and the fields to bring back, and add a WHERE or ORDER BY to get past the 250-record default for one object.
• Specific terms. “Keep searches specific and avoid using wildcards, if possible. For example, search with Michael instead of Mi*.” And “Use single-object searches for greater speed and accuracy” (Searching (opens in a new tab), best practices, Winter ‘27).
• Wildcards and operators. An asterisk matches “zero or more characters at the middle or end of your search term”, and a question mark exactly one. Quotes keep a phrase in order, and AND, OR and AND NOT combine terms (FIND {SearchQuery} (opens in a new tab), SOQL and SOSL Reference). Notice: the middle or the end. Like the index in module 3, search does best when it knows how a word starts.
• Divisions. SOSL can be limited to one division (WITH DivisionFilter), the partitioning tool from module 4.

And a few limits worth knowing. A transaction in Apex can run “Total number of SOSL queries issued: 20”, and “Total number of records retrieved by a single SOSL query: 2,000” (Execution Governors and Limits (opens in a new tab), Apex Developer Guide, Winter ‘27). One quiet trap: “If SearchQuery is longer than 4,000 characters, any logical operators are removed. For example, the AND operator in a statement with a SearchQuery that’s 4,001 characters defaults to the OR operator, which could return more results than expected” (SOQL and SOSL Limits for Search Queries (opens in a new tab)).

Test knowledge. Know SOSL’s limits: at most 2,000 records searched, then permissions applied; 250 for one object unless you add WHERE or ORDER BY; up to 2,000 divided by the number of objects (and no more than 250 each) when you search several; 20 SOSL queries per Apex transaction. Know the levers: search groups (NAME, EMAIL, PHONE), RETURNING, specific terms over wildcards, and wildcards only in the middle or at the end.

Search Runs as Someone

Search reaches across many objects and returns text, so who it runs as matters. In Apex, that changed recently. “Apex database operations, such as SOSL and SOQL queries, DML statements, and Database methods, now run in user mode by default. In user mode, database operations enforce the sharing rules, field-level security, and object permissions of the current user. In earlier API versions, database operations default to system mode” (Database Operations Run in User Mode by Default (opens in a new tab), release notes, API version 67.0 and later). Code can still say which mode it wants: “To indicate an access mode for a SOQL or SOSL query, insert a WITH USER_MODE or WITH SYSTEM_MODE clause” (Set an Access Mode for Database Operations (opens in a new tab), Apex Developer Guide).

And because a search screen takes whatever the user types, it’s a door for injection. Salesforce’s Well-Architected guidance names it: “SOQL or SOSL injections are scoped to a reading that discloses records or fields that the caller shouldn’t be able to reach by widening query conditions”, and asks you to “Validate and sanitize all user input that prevents injection across SOQL, SOSL, and HTML contexts” (Trust (opens in a new tab)).

Search in Other Languages

If your org works in more than one language, search doesn’t behave the same in all of them. “Search is available for Fully Supported Languages. However, not all features, including lemmatization and synonym groups, are available in all languages and for all objects. Only exact matches are returned for searches in End-User Languages” (How Einstein Search Works (opens in a new tab)). Lemmatization is what lets a search for “deliveries” find “delivery”; without it, only the exact word matches. And for languages written without spaces, the engine uses “morphological tokenization” to find the words, so a search for Kyoto (京都) doesn’t match Tokyo Prefecture (東京都) (FIND {SearchQuery} (opens in a new tab)). For a global care team, test search in each language people actually use.

Search to Discover, Query to Operate

It isn’t either/or. The agent remembers “damaged refrigerator Henderson”; search finds the case or work order; once you have its identity, structured retrieval takes over. Search to discover; query to operate.

But there are traps on both sides. Once search gets good, teams get lazy about structure: “we don’t need to model that, people can search for it.” No. If information drives automation, integration, security, reporting, business rules, matching or deterministic retrieval, give it structure. If the Retail Partner is a meaningful relationship, model it; don’t bury its name in a description and hope search finds it. Search is great for discovery; it isn’t a data model. And the reverse: if people genuinely need to discover text across fields and objects, don’t force them through a maze of structured filters because that’s easier for the development team.

Salesforce’s own case study shows the pattern for a custom search screen. A customer let users search on any of 20 fields, with wildcards, across several objects, and performance suffered. The fixes: “Use only essential search fields”, “De-normalize the data from the multiple objects into a single custom object”, and “Dynamically determine the use of SOQL or SOSL to perform the search based on both the number of fields searched and the types of values entered. For example, very specific values (i.e., no wild cards) used SOQL to query, which allowed indexes to enhance performance” (Custom Search Functionality (opens in a new tab)). Exact values go to the librarian; words go to search.

Search Is Interesting Again

For years I haven’t seen SOSL used anywhere near as much as SOQL on Salesforce projects; transactional development starts with structured records and structured queries. AI is making search architecture interesting again. An agent doesn’t always start with WHERE Retail_Partner__c = 'Redrock'. Someone asks, “which customers have complained about damaged appliances?” or “anything about delivery problems at the Henderson location?” Now we’re moving from exact structured retrieval toward finding by words, and eventually by meaning.

And keyword search still isn’t semantic search. SOSL finds words. “Find customers unhappy because deliveries keep arriving late” may match records that say “missed window,” “driver arrived after closing,” “third reschedule” or “came two days later,” none of them using the words in the question. Now we’re asking about meaning, which brings in semantic retrieval, and, combined with structure, hybrid retrieval. The grounding chapter takes that up in Choosing How the Agent Gets the Data (coming soon).

Agents search too. Salesforce’s hosted MCP server gives AI agents a find tool alongside soqlQuery: it “Executes a text search across multiple Salesforce objects simultaneously … Returns a maximum of 2,000 records total. Use search groups to narrow scope” (SObject All (opens in a new tab), Hosted MCP Servers, checked 2026-10-22). The same limits, the same crowding, the same need for specific terms, now asked by a machine that doesn’t get tired of asking.

Steve Trucking: Which Tool?

• “Give me today’s Redrock deliveries.” Object, partner, date: structured. SOQL.
• “Find the record where somebody mentioned loading dock damaged.” Known words, unknown field or object: text discovery. SOSL.
• “Find customers who seem frustrated about repeated delays.” Similar meaning, different words: semantic retrieval.
• “Find frustrated Redrock customers with active deliveries this week.” Meaning plus structured filters: hybrid retrieval.

What an Architect Decides Here

• Whether a requirement is structured retrieval, text discovery or something else, instead of defaulting to SOQL; and whether a “contains” belongs in search.
• Which objects and content deserve to be searchable, so high-volume noise doesn’t crowd out useful results.
• Whether search-index freshness is acceptable, including after bulk loads, or the process needs deterministic structured retrieval.
• How the 2,000-record limit, its split across objects, and permissions affect search quality at production volume.
• Who search runs as, in code and for agents, and how user input is protected from injection.
• How search behaves in each language the business uses.
• Where search should discover records and structured query take over.

If they ask for work orders where the partner is Redrock and the date is today, that’s a structured question: query. If they ask for the record where somebody wrote about a broken refrigerator, they’re searching: search. Don’t build ten ORs because SOQL is familiar, and don’t search the universe because turning search on everywhere is easy. Search is not query. And the next question gets easier: do I know the structure, the words, or the meaning?

Explore

• Salesforce Developers, Best Practices for Deployments with Large Data Volumes (Winter ‘27), checked 2026-11-01: Search Architecture (opens in a new tab), Using SOQL and SOSL (opens in a new tab), best practices for Searching (opens in a new tab) and SOQL and SOSL (opens in a new tab), and the Custom Search Functionality (opens in a new tab) case study.
• Salesforce Developers, SOQL and SOSL Reference, SOSL Limits on Search Results (opens in a new tab) and FIND {SearchQuery} (opens in a new tab), checked 2026-11-01.
• Salesforce Help, How Einstein Search Works (opens in a new tab), checked 2026-11-01: tokens, indexing time, the 120-day rule, ranking, languages.
• Salesforce Developers, SOQL and SOSL Limits for Search Queries (opens in a new tab) (Limits Quick Reference) and Apex Developer Guide, Execution Governors and Limits (opens in a new tab) and Set an Access Mode for Database Operations (opens in a new tab), Winter ‘27, checked 2026-11-01.
• Salesforce Help, release notes, Database Operations Run in User Mode by Default, Not System Mode (opens in a new tab), API version 67.0, checked 2026-11-01.
• Salesforce Architects, Well-Architected, Trust (opens in a new tab), checked 2026-11-01: SOQL and SOSL injection.
• Salesforce Developers, Hosted MCP Servers, SObject All (opens in a new tab), checked 2026-11-01: the find tool.
• Salesforce Help, How Search Crowding Affects Search Results (opens in a new tab), checked 2026-11-01: the definition, the numbers and the suggestions.
• Salesforce Help, Search Manager: Manage Searchable Objects and Fields (opens in a new tab), Manage the Search Index (opens in a new tab), Explore the Search Index with Search Manager (opens in a new tab), and Searchable Fields: Custom Object (opens in a new tab), checked 2026-11-01.