sosl-with-clauses

name	sosl-with-clauses
description	Use when adding result-scoping or result-shaping WITH clauses to a SOSL FIND query — WITH DivisionFilter, WITH DATA CATEGORY, WITH SNIPPET, WITH NETWORK, WITH PricebookId, WITH METADATA, WITH HIGHLIGHT, and WITH SPELL_CORRECTION — including their fixed clause order, supported objects, field-type limits, and API-version floors. Triggers: SOSL snippet, highlight search terms, filter by data category, community/network scoping, spell correction, pricebook filter, division filter. NOT for base FIND/IN/RETURNING mechanics, SOSL-vs-SOQL choice, or injection-safe dynamic search (use data/sosl-search-patterns); NOT for SOSL result-count limits (use data/sosl-search-result-limits).
category	data
salesforce-version	Spring '25+
well-architected-pillars	["Performance","Security"]
triggers	["add a snippet excerpt to my SOSL knowledge search results","highlight the matching search terms in a SOSL query","filter a SOSL knowledge article search by data category","scope a SOSL search to one Experience Cloud site","turn off spell correction in a SOSL FIND query"]
tags	["sosl-with-clauses","sosl","with-snippet","with-highlight","with-data-category","with-network","spell-correction"]
inputs	["The SOSL FIND query (static or dynamic Search.query) you want to scope or shape","The target objects/entities and which channel or surface consumes the results","The API version the query runs under"]
outputs	["A correctly ordered SOSL FIND query with the required WITH clauses","Review findings on clause order, supported objects, field-type limits, and API-version floors"]
dependencies	[]
version	1.0.0
author	Pranav Nagrecha
updated	"2026-07-08T00:00:00.000Z"

SOSL WITH Clauses

This skill activates when a practitioner is composing or reviewing a SOSL FIND query and needs one of the optional WITH clauses that either scope which records match (DivisionFilter, DATA CATEGORY, NETWORK, PricebookId) or shape how matches come back (SNIPPET, HIGHLIGHT, METADATA, SPELL_CORRECTION). The clauses are standard, released SOSL syntax documented in the SOQL and SOSL Reference — the docs do not stamp them with a GA/Beta/Pilot label, so treat them as core syntax and do not assert a maturity level the docs don't state.

---

Before Starting

Gather this context before working on a SOSL WITH clause:

• Know your target objects. Every WITH clause is gated to specific entities. SNIPPET, HIGHLIGHT, and DATA CATEGORY do nothing on objects they don't support, and there is no error — the clause is just ignored. Confirm the object list (see the clause table) before promising the feature will work.
• Know your API version. DATA CATEGORY needs 18.0+, SNIPPET needs 32.0+, HIGHLIGHT needs 39.0+ (40.0+ for custom fields/objects), and SPELL_CORRECTION needs 40.0+. A query running below the floor silently loses the clause. Check the apiVersion of the class, LWC, or REST call that issues the search.
• The most common wrong assumption: that WITH clauses can appear in any order, like SOQL WHERE/ORDER BY. They can't — SOSL enforces a single fixed order and rejects the query otherwise. See Core Concepts.
• Wildcards suppress shaping. If the FIND term contains * or ?, SNIPPET excerpts and HIGHLIGHT markup are not generated. Decide up front whether the search needs wildcards or presentation, because you often can't have both.

---

Core Concepts

Scoping clauses vs shaping clauses

The eight WITH clauses fall into two jobs:

• Result-scoping — narrows which records are returned before they reach you: (Division field), (Knowledge/Question categories), (Experience Cloud site), (a single price book for ).