Sosl External Object Search Limits

SOSL External Object Search Results Limits

This skill activates when SOSL (or the global search box that runs on SOSL) is pointed at a Salesforce Connect external object and behaves differently from a standard sObject search — returning nothing, erroring on a normally valid operator, or dropping the external object from the results. External objects (__x) map to data that lives outside the org through an OData 2.0/4.0 adapter or a custom Apex Connector Framework adapter, and the SOSL reference documents a narrow set of extra constraints that only apply to them.

The primary authority is the SOQL and SOSL Reference page SOSL Limits on External Object Search Results. That page carries no GA/Beta/Pilot maturity label; treat these as standard platform behavior for external-object search and do not assert a maturity level the docs don't state.

Before Starting

Gather this context before working on anything in this domain:

• Confirm it's actually an external object. External objects end in __x and are backed by an external data source (Salesforce Connect). The rules here do not apply to standard or custom (__c) sObjects — those follow data/sosl-search-patterns.
• Know the adapter type. Three of the limits are adapter-scoped: OData 2.0/4.0 adapters reject logical operators in the FIND clause, and custom (Apex Connector Framework) adapters reject convertCurrency() and generic WITH clauses. Everything else applies to all external objects.
• Verify search is enabled at both layers. An external object is searchable only when search is enabled on both the external object and its external data source. This is the single most common cause of "returns no records."
• Identify the searchable fields. Only Text, Text Area, and Text Area (Long) fields on an external object are searchable. An object with zero searchable fields returns no records — with no error to tell you why.

Core Concepts

Concept 1: Search is enabled at two layers, and Sync overwrites the object layer

To surface an external object in SOSL and global search, enable search on both the external object and the external data source. The trap: syncing the external data source always overwrites the external object's search status to match the data source's. If the data source has search off, every sync silently flips the object's search flag off again — so a search that worked yesterday can stop working after a routine sync with no code or query change.

Concept 2: Only text-type fields are searchable, and "no searchable fields" is silent

Only Text, Text Area, and Text Area (Long) fields on external objects can be searched. Number, date, checkbox, picklist, and lookup fields are never part of the SOSL index for an external object. If an external object has no searchable fields at all, searches on it return no records — the platform does not raise an error. This reads to callers as "the data isn't there," when the real cause is that nothing on the object is indexable.

Concept 3: External objects are opt-in to results — RETURNING is mandatory

For standard objects, FIND {term} IN ALL FIELDS will surface matches across the searchable objects. External objects are different: an external object must be named explicitly in a RETURNING clause or its matches never appear in the results. A SOSL statement with no RETURNING, or a RETURNING that lists only standard objects, will silently exclude the external object even when it matches.

Concept 4: A specific set of operators, functions, and clauses is unsupported

Against external objects, SOSL rejects (for all external objects):

• Operators: INCLUDES, LIKE, EXCLUDES
• Function: toLabel()
• Clauses: UPDATE TRACKING, UPDATE VIEWSTAT, WITH DATA CATEGORY
• Search-string length: the search text must be 100 or fewer characters

And two adapter-scoped groups:

• OData 2.0/4.0 adapters only: logical operators (AND / OR / AND NOT) in the FIND clause are not supported.
• Custom (Apex Connector Framework) adapters only: the convertCurrency() function and generic WITH clauses are not supported.

Getting the adapter scope right matters: convertCurrency() and WITH are a problem for custom adapters, not for OData; logical operators in FIND are a problem for OData, not (by this rule) for custom adapters. Don't flag them universally.

Common Patterns

Pattern: Write an external-object-safe SOSL statement

When to use: any SOSL that targets an external object, in Apex or the Query Editor.

How it works: name the external object explicitly in RETURNING, list only text fields you searched, keep the FIND term at 100 characters or fewer, and use wildcards (*, ?) instead of LIKE.

List<List<SObject>> hits = [
    FIND 'Acme*'
    IN ALL FIELDS
    RETURNING Order__x(ExternalId__c, AccountName__c, Description__c)
];
List<Order__x> orders = (List<Order__x>) hits[0];

Why not the alternative: dropping the RETURNING Order__x(...) (or relying on IN ALL FIELDS alone) makes the external object silently absent from results — the query "works" but returns nothing from that object.

Pattern: Diagnose "external object returns no records"

When to use: the search runs without error but yields nothing from the external object.

How it works: walk the four silent causes in order:

1. Is search enabled on both the external object and the external data source? (Re-check after any recent sync — sync overwrites the object flag.)
2. Does the object have at least one searchable text field?
3. Is the object named explicitly in the RETURNING clause?
4. Is the FIND term within 100 characters and free of unsupported operators?

Why not the alternative: treating it as a data-availability or connectivity problem sends you into the adapter/endpoint when the fix is almost always one of these four query/enablement conditions.

Pattern: Replace an unsupported operator, function, or clause

When to use: SOSL errors on the external object with an unsupported-feature message, or you're porting a standard-object query.

How it works: substitute the supported equivalent:

Why not the alternative: leaving the unsupported token in place fails the whole SOSL statement, not just the external-object portion.

Decision Guidance

Recommended Workflow

Step-by-step for an AI agent or practitioner working an external-object SOSL task:

1. Classify the target. Confirm the object ends in __x and note its adapter type (OData 2.0/4.0 vs custom Apex Connector Framework). If it's a __c/standard object, route to data/sosl-search-patterns instead.
2. Confirm enablement. Verify search is enabled on both the external object and the external data source, and that the object has at least one searchable text field. Flag that a data-source sync overwrites the object's search flag.
3. Build the SOSL statement. Name the external object explicitly in RETURNING with only text fields, keep the FIND term ≤100 characters, and use wildcards rather than LIKE.
4. Strip unsupported tokens. Remove INCLUDES/EXCLUDES, toLabel(), UPDATE TRACKING, UPDATE VIEWSTAT, WITH DATA CATEGORY. For OData remove logical operators from FIND; for custom adapters remove convertCurrency() and generic WITH.
5. Lint it. Run scripts/check_sosl_external_object_search_limits.py against the query or source tree to catch any remaining external-object violations, passing --adapter odata or --adapter custom when the adapter is known.
6. Verify results. Run the search; if it still returns nothing, walk the four silent causes from the diagnose pattern before touching the adapter/endpoint.

Review Checklist

Run through these before marking work in this area complete:

• Search is enabled on both the external object and the external data source (re-verified after any recent sync)
• The object has at least one searchable Text / Text Area / Long Text Area field
• The external object is named explicitly in the RETURNING clause
• The FIND search string is 100 or fewer characters
• No INCLUDES / LIKE / EXCLUDES operator, toLabel(), UPDATE TRACKING, UPDATE VIEWSTAT, or WITH DATA CATEGORY against the external object
• For OData adapters: no logical operators (AND/OR/AND NOT) in the FIND clause
• For custom adapters: no convertCurrency() and no generic WITH clause
• No maturity claim (GA/Beta/Pilot) asserted beyond what the reference states

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Sync silently disables search — syncing the external data source overwrites the external object's search status to match the data source's. A working search can break after a routine sync with no query change and no error.
2. "No searchable fields" returns zero records, not an error — if nothing on the object is a text field (or none are marked searchable), every search comes back empty, masquerading as a data or connectivity problem.
3. External objects are excluded from results unless named in RETURNING — IN ALL FIELDS does not pull an external object into the result set; it must appear explicitly in RETURNING.

Output Artifacts

Related Skills

• data/sosl-search-patterns — general SOSL against standard/custom sObjects; the baseline this skill diverges from for external objects.
• data/sosl-search-result-limits — result-count / SOSL row limits that apply to searches generally (a different limit family than these external-object rules).
• data/sosl-with-clauses — the WITH clauses (SNIPPET, HIGHLIGHT, NETWORK, etc.) that custom-adapter external objects don't support.
• integration/salesforce-connect-external-objects — designing the external object, data source, and adapter this skill searches.
• admin/global-search-configuration — enabling search (the Allow Search toggles, index behavior) that must be on before any of this applies.