What is the difference between Custom Settings and Custom Metadata Types

I’m the original inventor of and lead developer for custom metadata types.

Although we have a variety of use cases in mind, custom metadata types are primarily intended to let you develop peers of Salesforce standard metadata types, such as custom fields, tabs, or workflow rules (obviously in this first release we don’t have the power required to duplicate all the functionality in these types).

Just as you can’t perform CUD on such types in Apex today (you can’t create a new tab, modify a custom field, or delete a workflow rule in Apex), you can’t yet perform CUD on custom metadata types in Apex, short of a metadata API callout. You can help us get that feature prioritized by voting for the idea here. To see how to create tooling using Apex for a custom metadata type, you can look at Jean-Baptiste Pringuey’s sample “configurator.”

Testing is a tricky question, which I address in a blog post I just posted. The use case you describe is definitely a legitimate one. There's been a fair bit of demand for configuration visibility to ftests. See the idea Custom Settings should be treated as a Setup Object for APEX Tests

There’s a lot more planned for custom metadata types than custom settings on steroids. App configurations that don’t have to be re-created in every environment and that can respect managed state (so you can have some that are not deletable or mutable by subscribers) was just a starting place that filled a known need. Aaron’s second blog post gives you a taste of things to come in the near term (safe harbor applies, of course).

Winter `16 features

Layoutable UI for entering and updating records is one of the big features that came out in Winter -- take a look at Custom metadata types: they’re money; actually, even better!

Record-level protection of configuration (as opposed to hiding the entire type, which is both a custom settings and a Summer CMT feature) is another.

The third big feature is field-level control over who can edit values. By setting a field to subscriber editable, you'll be able to default the value in a package and let customers change that value if they need to.

More recent features

It's been a while!

Custom Metadata types now support (as of Summer 17):

  • Picklist fields
  • Relationships to records of other custom metadata types, to SObject types (EntityDefinition), and to SObject fields (FieldDefinition)
  • Text Area (Long) fields
  • Asynchronous (but not requiring remote site settings) upsert in Apex via Metadata.MetadataOperations.enqueueDeployment()
  • Validation formulas (including traversal of relationships)

I came up with the below advantages (and disadvantage). I'd be interested if you see any other ones.

  • Perhaps the biggest advantage Custom Metadata Types have over Custom Settings is that the data themselves are considered to be Metadata. So, essentially, you have Metadata about Metadata. Technically, they are called “Components”, and the reason this is important, is because you can DEPLOY the records!
  • Since the Records themselves are Metadata, they are refreshed to Sandboxes; even those with no data.
  • Since the Records themselves are Metadata, APEX Tests can see them even with “SeeAllData=False”. No more creating Custom Settings for Test Classes! • Custom Metadata
  • Types are more like a custom object than Custom Settings. This means it takes a little more time to create them, but you have more control such as page layouts and other features.
  • Starting with Winter ’16, like a custom object might have, you can Track Audit Trail history! This is a must have feature!
  • Like Custom Settings, Custom Metadata Types do not cost a SOQL when referencing them. Moreover, you can reference a Custom Metadata Type with a standard SOQL instead of using the special Custom Settings Class. For example: Select ID, Field1__c, Field2__c, … From My_CustomMetadataType__mdt
  • Like Custom Settings, all records are Cached. So you don’t need to worry about performance, and indeed, this will provide better performance over a normal table.


  • Unfortunately, at this time, if you want to create a MAP of all of the values for a given Custom Metadata Type, you must query all records and then populate it through a loop, similar to how you would for a normal table. Unlike Custom Settings which have a getAll method to create a MAP for you.
  • Though this is a record (has an ID), it can't be linked to from another object via a Lookup.

I've done quite a bit of research on Custom Metadata Types vs Custom Settings, and I've found that in only a few cases are Custom Settings more useful. Custom Metadata types have a number of advantages that make them the correct choice to implement almost always. A lot of this has already been said, but some things have been added recently, so I thought I'd add my two cents.

Advantages to Custom Metadata:

  • Most importantly, as stated before, they are Metadata and thus deployable! No more annoying configuration after deployment, which you have to do with Custom Settings. They're also refreshed to sandboxes, so you don't need to create Apex classes to generate your default Custom Setting records.
  • They have WAY more options that Custom Settings: picklist fields, long text areas (in Spring '17), page layouts, and validation rules (though as of Winter '17 these are not deployable either by change set or by migration tool - weird!)
  • The beauty that is Metadata Relationships! You can create lookups between Custom Metadata objects. Additionally, you can create an Object Definition lookup - so you're relating Custom Metadata to Standard or Custom Object definitions. Additionally, in Spring '17 you can create a dependent lookup to a Field Definition on that object. (Documentation here)
  • Custom Settings have the same permission to edit the records and to edit the configuration. Both can be done with the "Configure Application" permission. With Custom Metadata, you can edit the records with "Configure Application" but you require "Author Apex" to edit the configuration.
  • Custom Metadata types have a lot of additional features specific to developing managed packages. You can configure the visibility and editability of fields an objects both by the org that installs the package and by upgrades to the package.

Reason why you would use custom settings instead:

  • Hierarchies - Custom metadata types do not purport to replace hierarchy custom settings which allow you to vary values based on users and profiles across the org. These custom settings can also be referenced in formulas, so can be used in formula fields, validation rules, workflow rules, and visualforce. (Documentation here)
  • Web service credentials - If you’re using test credentials in a sandbox, you don’t have any reason to deploy them to production. More importantly, if you create a sandbox, you don’t want the config for the production versions of your Web Services being created automatically and used by default. However, it is usually best to use Named Credentials for this.
  • Custom setting records’ values can be edited in code, while custom metadata cannot. If you will need to modify your configuration programmatically for any reason (say you’re creating a config console for the user), custom metadata will not work.

There's also been some discussion about testing here. I have a different approach which I detail in my answer to Unit Test - Creating Custom Metadata.