A Developer’s Guide to Key Columns in Dataverse (Entities Reimagined)
Key Columns in Dataverse (Entities Reimagined) play a vital role in ensuring data integrity, uniqueness, and efficient record management within the Microsoft Power Platform. In Dataverse, every table (previously known as an entity) includes a Primary Key that uniquely identifies each record, typically represented by a GUID, and a Primary Name Column, which provides a human-readable name for display in views and lookups. Developers can also define Alternate Keys, which allow external systems to identify and update records using natural business data—such as an email address, employee ID, or product code—rather than system-generated IDs. This feature is especially useful for integrations, upsert operations, and data migrations, as it simplifies record matching and reduces duplication. By leveraging these key columns effectively, Dataverse ensures consistency across related data, enhances performance, and provides developers with a flexible foundation for building scalable and reliable business applications.
“Entities Reimagined” means that Dataverse tables are the next evolution of entities, redefined for today’s low-code and AI-driven app development world—more open, more flexible, and more aligned with standard data modeling concepts.
In Microsoft Dataverse, key columns are special fields used to uniquely identify each record in a table (formerly called an entity). While they serve a similar purpose to primary keys in traditional databases, they are more flexible, powerful, and integrated within the Dataverse environment.
1. Primary Key (Default Key Column)
- Every table in Dataverse automatically includes a primary key column, which uniquely identifies each record.
- This column typically follows the format:
- <tablename>id (e.g., accountid, contactid, incidentid).
- It’s a GUID (Globally Unique Identifier)—ensuring uniqueness across not just one table or database, but across environments and integrations.
- You cannot modify or remove the primary key column.
How it differs from traditional databases:
- Traditional databases often use integer-based keys (like auto-increment IDs), which are unique only within one database.
- Dataverse uses GUIDs, making it ideal for distributed systems, cloud replication, and integration with Power Platform, Dynamics 365, and Azure services.
2. Alternate Keys
- Dataverse allows you to define additional keys (alternate keys) to uniquely identify records based on one or more other columns.
- Example: You could define an alternate key on Email Address for Contacts or Account Number for Accounts.
Benefits:
- Useful when integrating with external systems that use natural keys (like CustomerID or SKU).
- Improves data import performance by letting Dataverse locate records based on alternate keys instead of record IDs.
- Ensures data consistency without relying only on GUIDs.
Difference from traditional databases:
- In SQL, you might define a composite key or unique constraint.
- In Dataverse, alternate keys are managed and enforced at the application layer through the platform’s metadata, not through direct SQL constraints.
3. Logical and Physical Differences
- The primary key in Dataverse is system-managed and cannot be manually updated.
- Alternate keys are user-defined and can be changed or removed.
- Dataverse stores keys in a way that supports low-code development, data synchronization, and API-based integrations, whereas traditional databases rely purely on schema definitions.
Comparison
1. In Plugins (C# / .NET Development)
Primary Key
- The Primary Key (accountid, contactid, etc.) is the main identifier used in plugin logic.
- It’s always available in the plugin’s context (Target.Id) and is used to retrieve, update, or delete records.
Example:
// Get the target record ID
Guid accountId = ((Entity)context.InputParameters["Target"]).Id;
// Retrieve account details using the primary key
Entity account = service.Retrieve("account", accountId, new ColumnSet("name", "accountnumber"));
Use Case:
- Used in almost every plugin for lookups, relationships, and updates.
- Critical for cascading operations and validations.
Primary Name Column
- Used for logging, tracing, or displaying readable names in plugin logs.
- Not used for data relationships (since it’s not unique).
Example:
string accountName = account.GetAttributeValue<string>("name");
tracingService.Trace($"Processing Account: {accountName}");
Use Case:
- Helpful for debugging or audit logs.
- Provides human-readable info in plugin traces or notifications.
Alternate Keys
- Used to locate or reference records without needing their GUID.
- Especially useful for integration-friendly plugins.
Example:
EntityReference accountRef = new EntityReference("account", "accountnumber", "ACCT-001");
Entity retrievedAccount = service.Retrieve(accountRef.LogicalName, accountRef.Id, new ColumnSet(true));
Use Case:
- Simplifies upsert (update or create) operations.
- Makes plugins resilient to data migrations or system GUID changes.
2. In Power Automate (Cloud Flows)
Primary Key
- Used behind the scenes by Dataverse connectors.
- When selecting a record from a dynamic dropdown, Power Automate actually uses the record’s GUID.
Example:
In “Update a row” → Power Automate stores the record’s GUID even though you see the name in the dropdown.
Use Case:
- Used internally for all CRUD operations.
Primary Name Column
- This is what you see in Power Automate dropdowns.
- It provides user-friendly display names, not unique values.
Example:
When choosing “Account” in a lookup, you see “Contoso Ltd.” (the Primary Name Column), but Power Automate uses the underlying GUID.
Use Case:
- Display in dropdowns and dynamic content for readability.
Alternate Keys
- Used in “Update or Add a row” (Upsert) actions.
- Lets you reference or create records using a business key instead of GUID.
Example:
You can configure the flow to match accountnumber instead of accountid.
Use Case:
- Simplifies data integration flows between systems (e.g., from ERP or SAP to Dataverse).
- Enables idempotent (non-duplicate) data imports.
3. In Web API Calls (Dataverse REST API / OData)
Primary Key
- The standard way to retrieve, update, or delete records via Web API.
Example:
GET https://org.crm.dynamics.com/api/data/v9.2/accounts(3F7A1C9B-22E3-4D0B-A132-3C91A73D7)
Use Case:
Most direct and fastest way to target records in APIs.
Primary Name Column
- Appears in the response payload and can be used for display, but not for identification.
Example (response):{"accountid": "3F7A1C9B-22E3-4D0B-A132-51C3C91A73D7","name": "Contoso Ltd.","accountnumber": "ACCT-001"}
Use Case:
- Used for UI representation and logging.
Alternate Keys
- Used in OData URLs to identify records by business values.
Example:
GET https://org.crm.dynamics.com/api/data/v9.2/accounts(accountnumber='ACCT-001')
Use Case:
- Cleaner, readable URLs.
- Easier integration with external systems that don’t know the GUID.
4. In Integrations (e.g., Azure Functions, Logic Apps, or External Systems)
Primary Key
- Often used when Dataverse is the master system.
- The external system stores the GUID to keep a direct reference.
Use Case:
- One-way integrations from Dataverse → external systems.
Primary Name Column
- Used in reports, dashboards, or messages for readability.
Use Case:
Display record names in Power BI or emails.
Alternate Keys
- Used when external systems (ERP, HR, etc.) already have unique identifiers.
- Allows mapping between systems using natural business keys.
Example:
ERP has CustomerCode = ACCT-001 → Dataverse uses the same field as an Alternate Key (accountnumber) for upsert and sync.
Use Case:
- Enables seamless data synchronization and prevents duplication.
- Simplifies integration mappings (no need to store GUIDs externally).
Summary:
In Microsoft Dataverse, three key column types—Primary Key, Primary Name Column, and Alternate Keys—play distinct but complementary roles in solution design.
The Primary Key (a GUID) uniquely identifies every record in the system and is essential for internal operations, relationships, and plugin logic. It is automatically generated and never changes. The Primary Name Column serves as the user-friendly identifier (like “Account Name” or “Contact Full Name”) used for display purposes in lookups, views, and Power Apps. However, it is not unique and should not be used for system logic or integrations.
The Alternate Keys act as business identifiers, allowing developers to use real-world fields (like Employee ID or Account Number) for upserts, data synchronization, and integration with external systems. These keys ensure consistency when GUIDs are unavailable, making them ideal for APIs and cross-platform data mapping.
For developers, the best practice is to rely on the Primary Key for system-level operations, use Primary Name Columns for display and reporting, and define Alternate Keys for integrations and unique business logic. Together, they make Dataverse solutions scalable, reliable, and integration-ready.
Published on:
Learn more