Hierarchy Custom Settings
Hierarchy Custom Settings are a type of Salesforce Custom Setting that store configuration values with per-user, per-profile, and org-wide overrides arranged in a strict precedence hierarchy.
Definition
Hierarchy Custom Settings are a type of Salesforce Custom Setting that store configuration values with per-user, per-profile, and org-wide overrides arranged in a strict precedence hierarchy. When code reads a Hierarchy setting, the platform returns the most specific value available: a value defined for the running user takes precedence over a value defined for their profile, which takes precedence over the org-wide default. The mechanism is a lightweight alternative to building a custom configuration object with sharing rules and ownership.
Hierarchy Custom Settings differ from List Custom Settings (the other type), which store key-value pairs without hierarchy and require explicit lookup by name. Hierarchy is the right choice when configuration legitimately varies by user or profile: a sales rep's default email signature, a profile-specific API endpoint, a feature flag that should be on for everyone except certain user populations. List is the right choice when the configuration is a set of records (currency rates, environment-specific service URLs) that does not vary per user.
How Hierarchy Custom Settings cascade values
The precedence model
When code calls MyHierarchySetting__c.getInstance() with no argument, the platform returns the value matching the running user. If no user-level value is defined, it falls back to the user's profile-level value. If no profile-level value is defined, it falls back to the org-wide default. If even the org default is missing, the method returns null. This cascading lookup happens implicitly; the caller does not need to check each level explicitly.
Configuration through Setup
Setup > Custom Settings > the setting > Manage. The Manage page shows three sections: organization (the org-wide defaults), profiles (per-profile overrides), and users (per-user overrides). Administrators add values at each level as needed. Most orgs have org-wide defaults plus profile overrides for special cases; per-user overrides are rare and reserved for personal preferences.
Apex access patterns
Hierarchy settings have a generated getInstance() method on the sObject class. getInstance() with no argument returns the value for the running user with full hierarchy lookup. getInstance(UserOrProfileId) returns the value for that specific entity with hierarchy lookup. getOrgDefaults() returns just the org-wide default. The methods are static and do not count against SOQL governor limits; they read from cached configuration data.
Performance characteristics
Custom Settings, both Hierarchy and List, are cached in memory at the org level. Reads do not count against SOQL query limits and do not hit the database. This makes them ideal for code paths that need configuration on every transaction. The trade-off is that updates take a few seconds to propagate across all servers; bulk-updating a Custom Setting and immediately reading it in another transaction may return stale values briefly.
When to use Hierarchy versus a custom object
Hierarchy Custom Settings are limited to specific field types (Number, Text up to 300 characters, Email, Checkbox, etc.) and 10 MB of total data across all settings in the org. For configuration that exceeds these limits, or that needs validation rules, triggers, or sharing rules, build a custom configuration object instead. Hierarchy is the right tool for simple per-user or per-profile config; complex configuration belongs in a regular sObject.
Migration to Custom Metadata Types
Salesforce introduced Custom Metadata Types as a more powerful alternative to Custom Settings, with the major advantage of being deployable through changesets and packages (Custom Setting data is not metadata and does not deploy automatically). Custom Metadata Types do not have the per-user hierarchy feature. For configuration that needs to deploy across environments and does not need per-user variance, Custom Metadata Types are better; for per-user feature flags, Hierarchy Custom Settings remain the right choice.
Best practices for production use
Reserve Hierarchy settings for genuine per-user or per-profile configuration. Avoid using them as global feature flags; Custom Metadata Types are better for that. Keep field counts low; large settings load slowly. Document each setting's purpose in field-level help text. Plan deployment: the schema deploys through changesets, but the data does not, so post-deployment scripts must populate values in each environment.
Create and use a Hierarchy Custom Setting
Setting up a Hierarchy Custom Setting involves creating the setting metadata, adding fields, populating values at each hierarchy level, and accessing the values in Apex. The steps below cover the full setup.
- Create the Custom Setting
Setup > Custom Settings > New. Name it descriptively (FeatureFlag__c), set Setting Type to Hierarchy, choose Public or Protected visibility. Save.
- Add fields
From the Custom Setting detail, add fields (Checkbox for feature flags, Text for endpoint URLs). Field types are limited; complex types require a custom object instead.
- Set the org-wide default
From the Custom Setting > Manage, click New (in the organization section). Enter values for each field. Save. This is what every user sees absent any override.
- Add profile-level overrides
Still in Manage, click New (in the profile section). Pick the profile, enter values. Save. Users with that profile now see the override instead of the org default.
- Add per-user overrides if needed
Add specific user overrides only for genuine per-user needs. Most settings do not need this level.
- Access from Apex
In Apex, call MySetting__c.getInstance() to get the running-user value with full hierarchy lookup. Use getOrgDefaults() to bypass hierarchy and read just the org default.
- Plan deployment
The setting schema deploys through changesets. The data (org defaults, profile overrides) does not. Write a post-deployment Apex script or use Data Loader to populate values in each environment.
The base value every user sees absent any override. Set first.
Override for a specific profile. Takes precedence over org default.
Override for a specific user. Highest precedence; takes precedence over profile and org.
Accessible from any Apex code. The standard choice for application settings.
Accessible only from Apex within the same namespace. For managed packages.
- Custom Setting data does not deploy through changesets. The schema does; values must be populated in each environment separately. Plan deployment scripts.
- Custom Setting data is capped at 10 MB total across all settings. Large or many settings hit the cap; plan storage carefully.
- Updates take a few seconds to propagate across all servers. Code that updates and immediately reads may return stale values briefly.
- Per-user overrides should be rare. Reserve for personal preferences; for most settings, profile overrides are sufficient and easier to maintain.
- Custom Settings cannot have validation rules, triggers, or sharing rules. For configuration needing those, use a custom object instead.
Trust & references
Straight from the source - Salesforce's reference material on Hierarchy Custom Settings.
- Create Custom SettingsSalesforce Help
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. What are the three levels of a Hierarchy Custom Setting?
Q2. Why are Hierarchy Custom Settings efficient?
Q3. What's a typical use case?
Discussion
Loading discussion…