Salesforce Custom Metadata getInstance vs SOQL: Key Differences & Best Practices.

Salesforce provides powerful features to handle metadata, allowing you to store and access configuration data in a structured manner. In this blog, we explore Salesforce Custom Metadata getInstance vs SOQL—two key approaches developers use to retrieve custom metadata efficiently. Custom metadata types in Salesforce offer a great way to define reusable and customizable application data without worrying about governor limits that come with other storage solutions, like custom objects. For more details, you can visit the official Salesforce Trailhead Custom Metadata Types module. We will delve into the differences, use cases, and best practices for these two approaches.

What is Custom Metadata in Salesforce?

Custom metadata types are custom objects in Salesforce that store metadata or configuration data. Unlike standard or custom objects, they are intended for storing application configurations that don’t change often. These types are often used for things like:

• Configuration settings for apps
• Defining global values (like API keys)
• Storing environment-specific configurations
• Reusable data for automation or integrations

Custom metadata records can be easily managed via Setup, the Metadata API, or APEX.

Approach 1: Using getInstance()

Build an AI-First Enterprise

From early pilots to enterprise-wide deployment, our award-winning AI consulting and technical services help you build the right foundation, scale responsibly, and deliver meaningful business outcomes.

Learn More

getInstance() is a method that allows you to access a single record of a custom metadata type. It works on a “singleton” basis, meaning that it returns a specific instance of the custom metadata record.

How getInstance() Works

The getInstance() method is typically used when you’re looking to retrieve a single record of custom metadata in your code. This method is not intended to query multiple records or create complex filters. Instead, it retrieves a specific record directly, based on the provided developer name.

Example:

// Get a specific custom metadata record by its developer name
My_Custom_Metadata__mdt metadataRecord = My_Custom_Metadata__mdt.getInstance('My_Config_1');

// Access fields of the record
String configValue = metadataRecord.Config_Value__c;

• Single Record Lookup: If you know the developer name of the record you’re looking for and expect to access only one record.
• Performance: Since getInstance() is optimized for retrieving a single metadata record by its developer name, it can offer better performance than querying all records, especially when you only need one record.
• Static Configuration: Ideal for use cases where the configuration is static, and you are sure that the metadata record will not change often.

Advantages of getInstance()

• Efficiency: It’s quick and easy to retrieve a single metadata record when you already know the developer name.
• Less Complex Code: This approach requires fewer lines of code and simplifies the logic, particularly in configuration-heavy applications.

Limitations of getInstance()

• Single Record: It can only retrieve one record at a time.
• No Dynamic Querying: It does not support complex filtering or dynamic querying like SOQL.

Approach 2: Using SOQL Queries

SOQL (Salesforce Object Query Language) is the standard way to retrieve multiple records in Salesforce, including custom metadata records. By using SOQL, you can query a custom metadata type much like any other object in Salesforce, providing flexibility in how records are retrieved.

How SOQL Queries Work

With SOQL, you can write queries that return multiple records, filter based on field values, or sort the records as needed. For instance:

// Query for multiple custom metadata records with SOQL
List<My_Custom_Metadata__mdt> metadataRecords = [SELECT MasterLabel, Config_Value__c FROM My_Custom_Metadata__mdt WHERE Active__c = TRUE];

// Loop through records and access their values
for (My_Custom_Metadata__mdt record : metadataRecords) {
    System.debug('Label: ' + record.MasterLabel + ', Value: ' + record.Config_Value__c);
}

When to Use SOQL Queries

• Multiple Records: If you need to retrieve more than one record or apply filters to the query.
• Dynamic Queries: When the records you’re querying are dynamic (e.g., based on user input or other logic).
• Complex Criteria: If you need to use conditions like WHERE, ORDER BY, or join metadata with other objects.

Advantages of SOQL Queries

• Flexibility: SOQL queries allow you to retrieve multiple records based on complex conditions.
• Filtering and Sorting: You can easily filter and sort records to get the exact data you need.
• Dynamic Usage: Ideal for cases where the data or records you’re querying may change, such as pulling all active configuration records.

Limitations of SOQL Queries

• Governor Limits: SOQL queries are subject to Salesforce’s governor limits (e.g., the number of records returned and the number of queries per transaction).
• Complexity: Writing and managing SOQL queries might introduce additional complexity in the code, especially when dealing with large datasets.

Key Differences: getInstance() vs. SOQL Queries

Best Practices for Using getInstance() and SOQL

• Use getInstance() when you need to access one specific metadata record and know the developer name beforehand. It’s efficient and optimized for simple lookups.
• Use SOQL when you need to filter, sort, or access multiple metadata records. It’s more flexible and ideal for dynamic scenarios, but you should always be aware of governor limits to avoid hitting them.
• Combine the Two: In some cases, you can use getInstance() for fetching critical single configuration records and SOQL for retrieving a list of configuration settings.

Conclusion

Both getInstance() and SOQL queries have their strengths when it comes to working with custom metadata types in Salesforce. Understanding when to use each will help optimize your code and ensure that your Salesforce applications run efficiently. For simple, static configurations, getInstance() is the way to go. For dynamic, large, or complex datasets, SOQL queries will offer the flexibility you need. By carefully selecting the right approach for your use case, you can harness the full power of Salesforce custom metadata.