entity key

An entity key is a property or a set of properties of an entity type that are used to determine identity. The properties that make up an entity key are chosen at design time. The values of entity key properties must uniquely identify an entity type instance within an entity set at run time. The properties that make up an entity key should be chosen to guarantee uniqueness of instances in an entity set.

The following are the requirements for a set of properties to be an entity key:

  • No two entity keys within an entity set can be identical. That is, for any two entities within an entity set, the values for all of the properties that constitute a key cannot be the same. However, some (but not all) of the values that make up an entity key can be the same.

  • An entity key must consist of a set of non-nullable, immutable, primitive type properties.

  • The properties that make up an entity key for a given entity type cannot change. You cannot allow more than one possible entity key for a given entity type; surrogate keys are not supported.

  • When an entity is involved in an inheritance hierarchy, the root entity must contain all the properties that make up the entity key, and the entity key must be defined on the root entity type. For more information, see Entity Data Model: Inheritance.

Example

The diagram below shows a conceptual model with three entity types: Book, Publisher, and Author. The properties of each entity type that make up its entity key are denoted with "(Key)". Note that the Author entity type has an entity key that consists of two properties, Name and Address.

Example model with three entity types

The ADO.NET Entity Framework uses a domain-specific language (DSL) called conceptual schema definition language (CSDL) to define conceptual models. The CSDL below defines the Book entity type shown in the diagram above. Note that the entity key is defined by referencing the ISBN property of the entity type.

<EntityType Name="Book">
  <Key>
    <PropertyRef Name="ISBN" />
  </Key>
  <Property Type="String" Name="ISBN" Nullable="false" />
  <Property Type="String" Name="Title" Nullable="false" />
  <Property Type="Decimal" Name="Revision" Nullable="false" Precision="29" Scale="29" />
  <NavigationProperty Name="Publisher" Relationship="BooksModel.PublishedBy"
                      FromRole="Book" ToRole="Publisher" />
  <NavigationProperty Name="Authors" Relationship="BooksModel.WrittenBy"
                      FromRole="Book" ToRole="Author" />
</EntityType>

The ISBN property is a good choice for the entity key because an International Standard Book Number (ISBN) uniquely identifies a book.

The CSDL below defines the Author entity type shown in the diagram above. Note that the entity key consists of two properties, Name and Address.

<EntityType Name="Author">
  <Key>
    <PropertyRef Name="Name" />
    <PropertyRef Name="Address" />
  </Key>
  <Property Type="String" Name="Name" Nullable="false" />
  <Property Type="String" Name="Address" Nullable="false" />
  <NavigationProperty Name="Books" Relationship="BooksModel.WrittenBy"
                      FromRole="Author" ToRole="Book" />
</EntityType>

Using Name and Address for the entity key is a reasonable choice, because two authors of the same name are unlikely to live at the same address. However, this choice for an entity key does not absolutely guarantee unique entity keys in an entity set. Adding a property, such as AuthorId, that could be used to uniquely identify an author would be recommended in this case.

See also