SearchSettings Metadata Type in SFDX

Architectural Overview#

SearchSettings is a critical org-level configuration metadata type that governs the search subsystem across an entire Salesforce instance. It defines settings for Einstein Search, lookup autocomplete, document content indexing, English punctuation clustering, and search scope personalization.

In modern enterprise architectures, search performance directly correlates with user productivity. When users enter search terms into the Lightning search bar or execute SOSL queries in integration pipelines, SearchSettings establishes how indexing algorithms tokenize terms, how lookups resolve parent records, and whether natural language queries can decipher intents like “my open opportunities in California”.

Directory and File Conventions#

In SFDX source format, SearchSettings is stored in the settings directory under the filename Search.settings-meta.xml.

Key Metadata Fields#

The SearchSettings XML structure provides comprehensive toggles for platform-level search behavior:

ObjectSearchSetting Subtype Fields#

Declarative XML and Package Manifest Examples#

Below is a production-hardened Search.settings-meta.xml file configured for an enterprise sales and service organization:

<?xml version="1.0" encoding="UTF-8"?>
<SearchSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <documentContentSearchEnabled>true</documentContentSearchEnabled>
    <enableEinsteinSearch>true</enableEinsteinSearch>
    <optimizeSearchForEnglishByDisablingPunctuationClustering>true</optimizeSearchForEnglishByDisablingPunctuationClustering>
    <searchSettingsByObject>
        <name>Account</name>
        <enhancedLookupEnabled>true</enhancedLookupEnabled>
        <lookupAutoCompleteEnabled>true</lookupAutoCompleteEnabled>
    </searchSettingsByObject>
    <searchSettingsByObject>
        <name>Contact</name>
        <enhancedLookupEnabled>true</enhancedLookupEnabled>
        <lookupAutoCompleteEnabled>true</lookupAutoCompleteEnabled>
    </searchSettingsByObject>
    <searchSettingsByObject>
        <name>Opportunity</name>
        <enhancedLookupEnabled>true</enhancedLookupEnabled>
        <lookupAutoCompleteEnabled>true</lookupAutoCompleteEnabled>
    </searchSettingsByObject>
</SearchSettings>

Manifest Definition (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Search</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

Retrieval and Deployment#

Use the Salesforce CLI to retrieve and deploy org search settings:

# Retrieve Search settings
sf project retrieve start --metadata "Settings:Search"

# Deploy Search settings to target environment
sf project deploy start --metadata "Settings:Search"

Senior Architect Deployment Best Practices and Gotchas#

1. Scratch Org Bootstrapping: Always include searchSettings in your config/project-scratch-def.json or deploy Search.settings-meta.xml during scratch org provisioning to avoid subtle UX discrepancies during test automation.
2. Lookup Autocomplete Pre-requisites: When specifying objects in searchSettingsByObject, ensure custom objects exist in the org before deploying SearchSettings. Deploying settings referencing a non-existent object will cause deployment errors.
3. Punctuation Clustering Considerations: Disabling punctuation clustering improves search for alphanumeric serial numbers (e.g. ABC-1234), but may alter search recall for multi-part hyphenated names. Validate search results in sandbox before enabling globally.
4. Content Search Indexing Timelines: Toggling documentContentSearchEnabled does not immediately index historical files. Salesforce initiates a background queue to crawl and index existing documents.

Frequently asked questions

What core capabilities are governed by SearchSettings?

SearchSettings controls Einstein Search, document indexing, lookup autocomplete, limit search to records owned, and search result clustering.

Where is SearchSettings located in SFDX projects?

It is stored in force-app/main/default/settings/Search.settings-meta.xml and retrieved as Settings:Search or SearchSettings.

Does enabling document content search require additional org storage?

Document search indexes files and attachments, which requires standard search index processing but does not consume extra data storage.

How does Einstein Search impact user search experience?

Einstein Search introduces natural language querying, personalized instant results, and recommended actions directly in the global search bar.