---
schema_version: "1"
id: 13230d7d686a6afa828431f3d9745aecb8b2b0dbc8101aaff3db7b350e1f43ab
title: Access Custom Metadata Records Programmatically
collection: admin
version: current
locale: en-us
portal_url: https://docs.salesforce.com/admin/current/en-us/platform/264-0-0/custommetadatatypes_accessing.md
canonical_url: https://help.salesforce.com/s/articleView?id=platform.custommetadatatypes_accessing.htm&release=264.0.0&type=5
source_site: help.salesforce.com
content_type: documentation
content_hash: f5bffab11b8de212449e18397d06d5d3d7d627e935d9124796b8c5faa6f49547
description: Use SOQL to access your custom metadata types and to retrieve the API names of the records of those types.
products:
  - Salesforce Platform
release: "264"
---
# Access Custom Metadata Records Programmatically

Use SOQL to access your custom metadata types and to retrieve the API names of the records of those types.

### Required Editions

<table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small edition">
      <colgroup>
        <col>
      </colgroup>
      <tbody>
        <tr class="">
          <td class="slds-cell-wrap" style="vertical-align:top;">Available in: Salesforce Classic and Lightning Experience</td>

        </tr>
        <tr class="">
          <td class="slds-cell-wrap" style="vertical-align:top;">
            <p>Available in: <strong>Enterprise</strong>, <strong>Performance</strong>, <strong>Unlimited</strong>, and
              <strong>Developer</strong> Editions
            </p>
            <p style="margin-bottom:0;">You can create, edit, and delete custom metadata type
              records from installed packages in: <strong>Group</strong> and <strong>Professional</strong>
              Editions</p>
          </td>

        </tr>
      </tbody>
    </table> <table class="slds-table slds-table_bordered slds-max-medium-table_stacked slds-m-bottom_small permission">
      <colgroup>
        <col style="width:50%">
        <col style="width:50%">
      </colgroup>
      <thead class="slds-text-title_caps ">
        <tr class="">
          <th scope="colgroup" class="slds-cell-wrap" colspan="2" style="text-align:center;vertical-align:top;" id="d28146e78">User Permissions
            Needed</th>
        </tr>
      </thead>
      <tbody>
        <tr class="">
          <td data-label="User Permissions Needed" class="slds-cell-wrap" style="vertical-align:top;" headers="d28146e78 ">To create or edit custom metadata types:</td>

          <td class="slds-cell-wrap" style="vertical-align:top;" headers="d28146e78 ">Author Apex</td>

        </tr>
      </tbody>
    </table>

Apex code can create, read, and update (but not delete) custom metadata records, as long as the metadata is subscriber-controlled and visible from within the code's namespace. DML operations aren’t allowed on custom metadata in the Partner or Enterprise APIs. With unpackaged metadata, both developer-controlled and subscriber-controlled access behave the same: like subscriber-controlled access. For information about the Custom Metadata Type\_\_mdt sObject, see [Custom Metadata Type\_\_mdt](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_custommetadatatype__mdt.htm) in the Object Reference for Salesforce . Refer to [Trust, but Verify: Apex Metadata API and Security](https://developer.salesforce.com/blogs/engineering/2017/06/apex-metadata-api-security.html) to learn more about package access in developer-controlled and subscriber-controlled orgs.

The following example declares the Apex variable custMeta of the custom metadata type `MyCustomMetadataType__mdt`, which is in your namespace.

```java
MyCustomMetadataType__mdt custMeta;
```

Declare the custMeta variable of the custom metadata type `TheirCustomMetadataType__mdt`, which isn’t in your namespace but is in the `their_ns` namespace.

```java
their_ns__TheirCustomMetadataType__mdt custMeta;
```

The following example is a simple query that returns standard and custom fields for all records of the `Threat_Tier_Mapping` custom metadata type and accesses some of their fields.

```java
Threat_Tier_Mapping__mdt[] threatMappings = [SELECT MasterLabel, QualifiedApiName, Field_Mapping__c ,Minimum_Support_Level__c FROM Threat_Tier_Mapping__mdt];

for (Threat_Tier_Mapping__mdt threatMapping : threatMappings) {
    System.debug(threatMapping.MasterLabel + ‘: ‘ +
                 threatMapping.Field_Mapping__c + ‘ from ‘ +
                 threatMapping.Team_Building_to_SFA_Field_Mapping__c + ‘ to ‘
                 threatMapping.Minimum_Support_Level__c);
}
```

To provide an entity that looks more like a `Schema.SObjectDescribeResult` than SOQL, make the Apex class `vacations.ThreatTierMappingDescribeResult` encapsulate the information queried from `vacations__ThreatTierMappingDescribeResult__mdt`. Then create the class `vacations.Vacations` with methods such as:

```java
vacations.ThreatTierMappingDescribeResult describeThreatTierMappings(String qualifiedApiName) {
    Threat_Tier_Mapping__mdt threatMapping = [SELECT <fields> FROM Threat_Tier_Mapping__mdt WHERE QualifiedApiName = :qualifiedApiName];
    return new ThreatTierMappingDescribeResult(<fieldValues>);
}
```

In the preceding example, `<fields>` refers to the fields you want to include in the `_describe_` and `<fieldValues>` refers to the values of those fields.

The next example uses a metadata relationship that references another custom metadata type, `Team_Building_to_SFA_Field_Mapping__mdt`, to do a simple right outer join.

```java
ThreatTierMapping threatMapping = 
    [SELECT MasterLabel, Team_Building_to_SFA_Field_Mapping__r.MasterLabel FROM Threat_Tier_Mapping__mdt WHERE QualifiedApiName=‘Easy_Vacations’];

System.debug(threatMapping.MasterLabel + ‘ is part of ‘ + Team_Building_to_SFA_Field_Mapping__r.MasterLabel);
```

The following example shows a left outer join starting from `EntityDefinition`. This query uses a relationship field called `Team_Building_Object__c` on `Team_Building_to_SFA_Field_Mapping__mdt`. The child relationship name of this relationship field is `Field_Mappings_From`.

```java
for (EntityDefinition entity : allObjects) {
    System.debug(‘Processing mappings for: ‘ + entity.QualifiedApiName);
    for (Team_Building_to_SFA_Field_Mapping__mdt fieldMapping : entity.FieldMappingsFrom__r) {
    System.debug(‘  Field ‘ + fieldMapping.Team_Building_Field__c + 
        ‘ has mapping ‘ + fieldMapping.QualifiedApiName);
    }
}
```

#### See Also

- [Custom Metadata Types](https://help.salesforce.com/s/articleView?id=platform.custommetadatatypes_overview.htm&release=264.0.0&type=5 "You can create your own declarative developer frameworks for internal teams, partners, and customers. Rather than building apps from data, you can build apps that are defined and driven by their own types of metadata. Metadata is the information that describes the configuration of each customer’s organization.")