Entity
An Entity in Salesforce is the general term for any data structure that can hold records: standard objects (Account, Contact, Case), custom objects (MyCustom__c), external objects (__x), platform events, and a few special metadata types.
Definition
An Entity in Salesforce is the general term for any data structure that can hold records: standard objects (Account, Contact, Case), custom objects (MyCustom__c), external objects (__x), platform events, and a few special metadata types. The term comes from database vocabulary where entity is the abstract concept that table makes concrete. Salesforce uses Entity in API documentation (the SOAP API has EntityDefinition for object metadata), in error messages (FIELD_NOT_FOUND on entity Account), and in the Tooling API where EntityDefinition and EntityParticle return metadata about objects and fields.
Entity is the broader category that includes everything an object is plus things that are not quite objects (platform events, settings hierarchies, big objects). For most everyday work, the platform uses object as the user-facing term and entity for the abstract-metadata layer. Understanding both helps when reading API documentation or building Apex that introspects metadata: EntityDefinition has fields like DurableId, QualifiedApiName, DeveloperName, and IsCustomizable that work across every entity type.
What entity means in Salesforce platform vocabulary
Entity versus Object: the abstract versus the concrete
Object is the user-facing term in Salesforce: Account, Contact, MyCustom__c. Entity is the platform''s internal vocabulary for the same concept extended to all addressable types. Setup uses Object; the Tooling API uses Entity. Both refer to the same underlying constructs in most cases, but Entity covers a slightly broader set (platform events and certain metadata types) that are not standard objects in the everyday sense.
The EntityDefinition object
EntityDefinition is a Tooling API object that exposes metadata about every entity in your org. Query it: SELECT DurableId, QualifiedApiName, Label, DeveloperName, IsCustomizable FROM EntityDefinition WHERE IsCustomizable = true. This returns every customizable entity, including standard objects, custom objects, and platform events. Useful for building introspection-driven UIs and admin tools.
EntityParticle for fields
EntityParticle is the corresponding Tooling API object for fields within entities. Query: SELECT DurableId, QualifiedApiName, Label, DataType, Length FROM EntityParticle WHERE EntityDefinitionId = AccountId-or-similar. The result is every field on the entity with metadata: data type, length, label, requiredness. Together EntityDefinition and EntityParticle let you walk the org''s schema programmatically.
Standard, Custom, External, and Big Object entities
All four categories are entities. Standard objects: Account, Contact, Case, Opportunity. Custom objects: MyObject__c. External objects: AcmeExternal__x. Big Objects: MyBigObject__b. Each has different storage, query, and CRUD semantics, but they all surface in EntityDefinition with their distinguishing characteristics.
Platform events as entities
Platform Events are publish-subscribe message channels that look like objects in some ways: they have an API name (Order_Status_Changed__e), fields, and CRUD operations (you can insert a Platform Event but it does not persist; it just publishes). They appear in EntityDefinition with a specific KeyPrefix and behavior pattern.
Error messages referencing entities
When the platform reports errors, entity is the term used: FIELD_NOT_FOUND on entity Account, INVALID_FIELD on entity MyCustom__c. The vocabulary in error messages predates the modern UI''s use of object, which is a quirk of the platform''s age. Mapping entity Account in an error to Account object in your Setup is part of debugging.
Entities and the metadata API
The Metadata API uses both terms inconsistently. CustomObject deploys an entity; PlatformEventChannel deploys an entity. The XML schema and tooling pick the term that fits the specific use case. Anyone deploying via Salesforce DX or Change Sets sees this mix; it can be confusing but reflects the platform''s evolution.
How to query Entity metadata via the Tooling API
Querying Entity metadata is useful when you need to build introspection-driven UIs, document the schema, or audit customizations. The Tooling API exposes EntityDefinition and EntityParticle for this purpose.
- Open the Developer Console
Click your avatar, then Developer Console. The Query Editor at the bottom lets you run SOQL against the Tooling API.
- Toggle Use Tooling API
At the top of the Query Editor, check Use Tooling API. This switches the query target from the data layer to the metadata layer.
- Query EntityDefinition
Run: SELECT QualifiedApiName, Label, IsCustomizable FROM EntityDefinition LIMIT 50. The result lists every entity in your org with its API name and label.
- Filter for custom entities
Add a filter: WHERE IsCustomizable = true AND IsCustomSetting = false. This narrows to entities you can customize (standard plus custom objects, excluding custom settings).
- Query EntityParticle for a specific entity
Run: SELECT QualifiedApiName, Label, DataType, Length FROM EntityParticle WHERE EntityDefinition.QualifiedApiName = Account AND IsAccessible = true. The result lists every accessible field on Account.
- Use the results in code or documentation
Export the results to CSV. Feed them into Apex for introspection, generate documentation, or audit which entities have specific fields. EntityDefinition and EntityParticle are the foundation of many third-party governance tools.
Tooling API object exposing object-level metadata. One row per addressable entity in the org.
Tooling API object exposing field-level metadata. Many rows per EntityDefinition.
Apex method returning similar metadata at runtime. Use in Apex; pair with EntityDefinition for governance UIs.
Apex method returning all objects. The runtime equivalent of EntityDefinition.
- Tooling API EntityDefinition does not return platform-managed entities like SharingHierarchy or ContentVersion in some contexts. Add specific filters as needed.
- IsCustomizable does not mean the entity is editable by your user. It means the metadata supports custom field additions. Profile permissions are a separate gate.
- EntityParticle returns archived and deprecated fields. Filter for IsAccessible if you only want fields the current user can see.
- Query limits apply to the Tooling API. Massive metadata queries can hit SOQL row limits; paginate with LIMIT and OFFSET.
Trust & references
Straight from the source - Salesforce's reference material on Entity.
- EntityDefinition ReferenceSalesforce Developers
- EntityParticle ReferenceSalesforce Developers
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 does Entity mean in Salesforce development?
Q2. Where do you encounter the term 'entity' most often?
Q3. Are entities and objects the same thing?
Discussion
Loading discussion…