Repository: feast-dev/feast

Issue:
Entity types as a higher-level concept
## Introduction
Currently an entity, or more formally an entity type, is treated as a special type of field within a feature set. There has been an attempt to simplify the creation and management of entities and to keep them consistent with features, however some challenges exist with our current approach.

Note: The terms entity and entity type will be used interchangeable in the following issue.

## How are entities created?
- Users define an entity as part of a feature set. An entity in this case is a field like any other within the feature set. More than one entity can exist within a feature set.
- An entity's name must be unique within a feature set.
- There are no constraints on entities outside of a feature set, either at the project or global level. This means that multiple feature sets can define the same entities again.

## How are entities used?
- Retrieving feature values: Entities are used as a key for retrieving features. In order to retrieve feature values within a feature set, all entities must be provided as part of the lookup.
- Joining feature sets: In the event that feature values are being retrieved from multiple feature sets, entities are used to look up these feature values. Entities are also used to join across these feature sets to construct a single result set.

## What is the problem?
1. Discovery: It seems intuitive that users would start their discovery experience from the point of view of an entity type, since their business problem is generally framed around one or more entities. By nesting entities within feature sets and within projects and not providing a discovery means, it makes discovery harder. 
2. Consistency: Entities are typically consistent across all projects and systems in most organizations. This consistency is not enforced in Feast at the moment. Users are bound to redefine entities in their local projects if no consistency is enforced at an organizational level. Failure would occur when lookups happen or when joins happen across feature sets, especially when joins need to happen across projects. 
3. Key building: If entities and features maintain mutual compatibility in terms of supported data types, then support must be maintained for building keys from all feature value types. This adds a lot of complexity to key building since support must be maintained to serialize complex composite data structures in order to build these keys. 

## Proposals
### 1. Project-level entities
Functionality
- Entities are created outside of feature sets, but they still reside in a specific project namespace. 
- Entities have their own distinct API and supported data types (which may be more limited than features)
- Entities must be unique within a project namespace, but can be duplicated across an organization. Uniqueness is ensured through a full entity reference (`gojek/customer`).
- Entities are still defined as part of a feature set, but this is a selection process instead of creation.

Advantages
- Entities receive all the sharing and isolation benefits of "projects". Entities would not have to be treated separately from a logical and/or development standpoint. There would also be no explosion of a global entity namespace
- Users are free to experiment and develop within their projects without affecting other users, since duplication is allowed across projects.
- No need for a central team to gate-keep the creation of entities.

Disadvantages
- By not elevating entities to the global level, end users would be required to know which projects contain the entities they should be referencing. This means an organizational process must exist in order to select these entities.
- Most projects would have to reference entities from another more authoritative project. In fact, it's likely that an organization will have a central project which contains only entities. This could be a little counter-intuitive if a feature set contains fields that are referencing an external project. 

### 2. Global-level entities
Functionality
- Entities are defined globally for a Feast deployment.
- Entities have their own distinct API and supported data types (which may be more limited than features).
- Entities must be globally unique.
- Entities are still defined as part of a feature set, but this is a selection process instead of creation.

Advantages
- Central authoritative listing of entities within an organization.
- Easier to discover which entities should be used, without needing an organizational policy.
- Easy to reason about and easier to understand when referencing an entity within a feature set.

Disadvantages 
- Requires development of separate logic from projects, feature sets, and features. 
- Requires a team and process to manage the creation of entities.
- No way to isolate conflicts. If one team wants to use a `float` and another wants to use a `string` for an entity data type, then it would likely result in two entities being created. This would still be the case in the Project-level entity proposal, but at least in that proposal the unorthodox approach (maybe `string`) could be isolated to a specific project.

### 3. Default project entities
Functionality
- If a user does not specify a project, then they are automatically located inside of the `default` project. This would be similar to how Kubernetes does namespacing.
- All other functionality would be the same as the `project level entities` proposal, except users don't actually have to create an entity inside of a named project.
- Feature references could be created that allow users to reference entities without a project. So instead of having `my_company/customer`, it would be possible to refer to "global" entities by either using `customer` or `default/customer`. 

Advantages
- All of the advantages of `project-level entities`.
- Most of the advantages of `global-level entities`, except that this default project would still not be a true global namespace. There would still need to be an organizational process that informs users to use the entities in this `project`.
- Simplifies development since `project-level` sharing and isolation can be reused.

Disadvantages
- Still requires access control on the default namespace.


Discussion:
> Most projects would have to reference entities from another more authoritative project

What would be an example scenario where this approach is the most sensible? For Gojek at least, i would imagine that project based entities make more sense. One project per service type (food, ride, gopay), each having entities which might share the same name (customer id, driver id).
> > Most projects would have to reference entities from another more authoritative project
> 
> What would be an example scenario where this approach is the most sensible? For Gojek at least, i would imagine that project based entities make more sense. One project per service type (food, ride, gopay), each having entities which might share the same name (customer id, driver id).

The example you are referring to would be for `project-level entities`. Meaning an organization could have authoritative projects like:
- gojek/customer
- gopay/customer

It seems to provide a cleaner isolation, but it is also the case that "users" would have to define their own projects and feature sets from which they would reference these authoritative entities. 

So I am only seeing one option here, not two. The disadvantage comes from having to know whether to use either of these two projects.

Another possible solution would be a hybrid model between global and project level entities. I have added this as (3) in the comment above, titled `3. Default project entities`

I am in favour of 3. Option 2 (unique global entity name) may lead to complicated entity management for some cases. For example, let say we have drivers for different countries. Option no 2 dictates that we cannot have the same entity for all country (eg. driver), but instead, multiple different entities. (eg. driver_vn, driver_th, driver_sg). It is likely that in an end to end machine learning workflow, the code section involving the drivers will be similar regardless of country (eg. Extracting driver entity value from JSON request during prediction step). So, for option no 2, the pipeline will need to know that driver_vn, driver_sg and driver_ th all belongs to the same group and should be handled the same way, which leads to extra configurations on the user side.
Though, if we go for option 3, we might want to explore if the concept of default project should be extended to feature retrieval as well, for consistency. For example,  if no project / default project has been set and project is not explicitly specified in feature ref, then the fallback would be the 'default' project.
> I am in favour of 3. Option 2 (unique global entity name) may lead to complicated entity management for some cases. For example, let say we have drivers for different countries. Option no 2 dictates that we cannot have the same entity for all country (eg. driver), but instead, multiple different entities. (eg. driver_vn, driver_th, driver_sg). It is likely that in an end to end machine learning workflow, the code section involving the drivers will be similar regardless of country (eg. Extracting driver entity value from JSON request during prediction step). So, for option no 2, the pipeline will need to know that driver_vn, driver_sg and driver_ th all belongs to the same group and should be handled the same way, which leads to extra configurations on the user side.

Its not clear what you mean here. What prevents you from having simply `driver` as a global entity?
> Though, if we go for option 3, we might want to explore if the concept of default project should be extended to feature retrieval as well, for consistency. For example, if no project / default project has been set and project is not explicitly specified in feature ref, then the fallback would be the 'default' project.

Absolutely, that was my hope as well!
> > I am in favour of 3. Option 2 (unique global entity name) may lead to complicated entity management for some cases. For example, let say we have drivers for different countries. Option no 2 dictates that we cannot have the same entity for all country (eg. driver), but instead, multiple different entities. (eg. driver_vn, driver_th, driver_sg). It is likely that in an end to end machine learning workflow, the code section involving the drivers will be similar regardless of country (eg. Extracting driver entity value from JSON request during prediction step). So, for option no 2, the pipeline will need to know that driver_vn, driver_sg and driver_ th all belongs to the same group and should be handled the same way, which leads to extra configurations on the user side.
> 
> Its not clear what you mean here. What prevents you from having simply `driver` as a global entity?

Actually, yeah you are correct, I can just have driver in a global project instead of having the entity defined in each regional project. Too entrenched in the code base that I am currently working on and didn't consider this possibility.
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

Moving this out of the 0.6 milestone because I think we can live without it for the time being.
Isn't 3. the same as 1. with just a special project called default?  The fact there is a special default project doesn't change the fact that all entities are scoped to a project ie 1. Right?
> Isn't 3. the same as 1. with just a special project called default? The fact there is a special default project doesn't change the fact that all entities are scoped to a project ie 1. Right?

Correct.

Resolving patch:
diff --git a/sdk/python/feast/cli.py b/sdk/python/feast/cli.py
--- a/sdk/python/feast/cli.py
+++ b/sdk/python/feast/cli.py
@@ -25,6 +25,7 @@
 from feast.config import Config
 from feast.contrib.job_controller.client import Client as JCClient
 from feast.core.IngestionJob_pb2 import IngestionJobStatus
+from feast.entity import EntityV2
 from feast.feature_set import FeatureSet, FeatureSetRef
 from feast.loaders.yaml import yaml_loader
 
@@ -114,6 +115,99 @@ def config_set(prop, value):
         sys.exit(1)
 
 
+@cli.group(name="entities")
+def entity():
+    """
+    Create and manage entities
+    """
+    pass
+
+
+@entity.command("apply")
+@click.option(
+    "--filename",
+    "-f",
+    help="Path to an entity configuration file that will be applied",
+    type=click.Path(exists=True),
+)
+@click.option(
+    "--project",
+    "-p",
+    help="Project that entity belongs to",
+    type=click.STRING,
+    default="default",
+)
+def entity_create(filename, project):
+    """
+    Create or update an entity
+    """
+
+    entities = [
+        EntityV2.from_dict(entity_dict) for entity_dict in yaml_loader(filename)
+    ]
+    feast_client = Client()  # type: Client
+    feast_client.apply_entity(entities, project)
+
+
+@entity.command("describe")
+@click.argument("name", type=click.STRING)
+@click.option(
+    "--project",
+    "-p",
+    help="Project that entity belongs to",
+    type=click.STRING,
+    default="default",
+)
+def entity_describe(name: str, project: str):
+    """
+    Describe an entity
+    """
+    feast_client = Client()  # type: Client
+    entity = feast_client.get_entity(name=name, project=project)
+
+    if not entity:
+        print(f'Entity with name "{name}" could not be found')
+        return
+
+    print(
+        yaml.dump(
+            yaml.safe_load(str(entity)), default_flow_style=False, sort_keys=False
+        )
+    )
+
+
+@entity.command(name="list")
+@click.option(
+    "--project",
+    "-p",
+    help="Project that entity belongs to",
+    type=click.STRING,
+    default="",
+)
+@click.option(
+    "--labels",
+    "-l",
+    help="Labels to filter for entities",
+    type=click.STRING,
+    default="",
+)
+def entity_list(project: str, labels: str):
+    """
+    List all entities
+    """
+    feast_client = Client()  # type: Client
+
+    labels_dict = _get_labels_dict(labels)
+
+    table = []
+    for entity in feast_client.list_entities(project=project, labels=labels_dict):
+        table.append([entity.name, entity.description, entity.value_type])
+
+    from tabulate import tabulate
+
+    print(tabulate(table, headers=["NAME", "DESCRIPTION", "TYPE"], tablefmt="plain"))
+
+
 @cli.group(name="features")
 def feature():
     """
diff --git a/sdk/python/feast/client.py b/sdk/python/feast/client.py
--- a/sdk/python/feast/client.py
+++ b/sdk/python/feast/client.py
@@ -19,7 +19,6 @@
 import tempfile
 import time
 import uuid
-from collections import OrderedDict
 from math import ceil
 from typing import Any, Dict, List, Optional, Tuple, Union, cast
 
@@ -43,16 +42,22 @@
     FEAST_DEFAULT_OPTIONS,
 )
 from feast.core.CoreService_pb2 import (
+    ApplyEntityRequest,
+    ApplyEntityResponse,
     ApplyFeatureSetRequest,
     ApplyFeatureSetResponse,
     ArchiveProjectRequest,
     ArchiveProjectResponse,
     CreateProjectRequest,
     CreateProjectResponse,
+    GetEntityRequest,
+    GetEntityResponse,
     GetFeastCoreVersionRequest,
     GetFeatureSetRequest,
     GetFeatureSetResponse,
     GetFeatureStatisticsRequest,
+    ListEntitiesRequest,
+    ListEntitiesResponse,
     ListFeatureSetsRequest,
     ListFeatureSetsResponse,
     ListFeaturesRequest,
@@ -62,8 +67,9 @@
 )
 from feast.core.CoreService_pb2_grpc import CoreServiceStub
 from feast.core.FeatureSet_pb2 import FeatureSetStatus
+from feast.entity import EntityV2
 from feast.feature import Feature, FeatureRef
-from feast.feature_set import Entity, FeatureSet
+from feast.feature_set import FeatureSet
 from feast.grpc import auth as feast_auth
 from feast.grpc.grpc import create_grpc_channel
 from feast.job import RetrievalJob
@@ -287,6 +293,8 @@ def project(self) -> Union[str, None]:
         Returns:
             Project name
         """
+        if not self._config.get(CONFIG_PROJECT_KEY):
+            raise ValueError("No project has been configured.")
         return self._config.get(CONFIG_PROJECT_KEY)
 
     def set_project(self, project: Optional[str] = None):
@@ -353,6 +361,130 @@ def archive_project(self, project):
         if self._project == project:
             self._project = FEAST_DEFAULT_OPTIONS[CONFIG_PROJECT_KEY]
 
+    def apply_entity(
+        self, entities: Union[List[EntityV2], EntityV2], project: str = None
+    ):
+        """
+        Idempotently registers entities with Feast Core. Either a single
+        entity or a list can be provided.
+
+        Args:
+            entities: List of entities that will be registered
+
+        Examples:
+            >>> from feast import Client
+            >>> from feast.entity import EntityV2
+            >>> from feast.value_type import ValueType
+            >>>
+            >>> feast_client = Client(core_url="localhost:6565")
+            >>> entity = EntityV2(
+            >>>     name="driver_entity",
+            >>>     description="Driver entity for car rides",
+            >>>     value_type=ValueType.STRING,
+            >>>     labels={
+            >>>         "key": "val"
+            >>>     }
+            >>> )
+            >>> feast_client.apply_entity(entity)
+        """
+
+        if project is None:
+            project = self.project
+
+        if not isinstance(entities, list):
+            entities = [entities]
+        for entity in entities:
+            if isinstance(entity, EntityV2):
+                self._apply_entity(project, entity)  # type: ignore
+                continue
+            raise ValueError(f"Could not determine entity type to apply {entity}")
+
+    def _apply_entity(self, project: str, entity: EntityV2):
+        """
+        Registers a single entity with Feast
+
+        Args:
+            entity: Entity that will be registered
+        """
+
+        entity.is_valid()
+        entity_proto = entity.to_spec_proto()
+
+        # Convert the entity to a request and send to Feast Core
+        try:
+            apply_entity_response = self._core_service.ApplyEntity(
+                ApplyEntityRequest(project=project, spec=entity_proto),  # type: ignore
+                timeout=self._config.getint(CONFIG_GRPC_CONNECTION_TIMEOUT_DEFAULT_KEY),
+                metadata=self._get_grpc_metadata(),
+            )  # type: ApplyEntityResponse
+        except grpc.RpcError as e:
+            raise grpc.RpcError(e.details())
+
+        # Extract the returned entity
+        applied_entity = EntityV2.from_proto(apply_entity_response.entity)
+
+        # Deep copy from the returned entity to the local entity
+        entity._update_from_entity(applied_entity)
+
+    def list_entities(
+        self, project: str = None, labels: Dict[str, str] = dict()
+    ) -> List[EntityV2]:
+        """
+        Retrieve a list of entities from Feast Core
+
+        Args:
+            project: Filter entities based on project name
+            labels: User-defined labels that these entities are associated with
+
+        Returns:
+            List of entities
+        """
+
+        if project is None:
+            project = self.project
+
+        filter = ListEntitiesRequest.Filter(project=project, labels=labels)
+
+        # Get latest entities from Feast Core
+        entity_protos = self._core_service.ListEntities(
+            ListEntitiesRequest(filter=filter), metadata=self._get_grpc_metadata(),
+        )  # type: ListEntitiesResponse
+
+        # Extract entities and return
+        entities = []
+        for entity_proto in entity_protos.entities:
+            entity = EntityV2.from_proto(entity_proto)
+            entity._client = self
+            entities.append(entity)
+        return entities
+
+    def get_entity(self, name: str, project: str = None) -> Union[EntityV2, None]:
+        """
+        Retrieves an entity.
+
+        Args:
+            project: Feast project that this entity belongs to
+            name: Name of entity
+
+        Returns:
+            Returns either the specified entity, or raises an exception if
+            none is found
+        """
+
+        if project is None:
+            project = self.project
+
+        try:
+            get_entity_response = self._core_service.GetEntity(
+                GetEntityRequest(project=project, name=name.strip()),
+                metadata=self._get_grpc_metadata(),
+            )  # type: GetEntityResponse
+        except grpc.RpcError as e:
+            raise grpc.RpcError(e.details())
+        entity = EntityV2.from_proto(get_entity_response.entity)
+
+        return entity
+
     def apply(self, feature_sets: Union[List[FeatureSet], FeatureSet]):
         """
         Idempotently registers feature set(s) with Feast Core. Either a single
@@ -528,18 +660,6 @@ def list_features_by_ref(
 
         return features_dict
 
-    def list_entities(self) -> Dict[str, Entity]:
-        """
-        Returns a dictionary of entities across all feature sets
-        Returns:
-            Dictionary of entities, indexed by name
-        """
-        entities_dict = OrderedDict()
-        for fs in self.list_feature_sets():
-            for entity in fs.entities:
-                entities_dict[entity.name] = entity
-        return entities_dict
-
     def get_historical_features(
         self,
         feature_refs: List[str],
diff --git a/sdk/python/feast/entity.py b/sdk/python/feast/entity.py
--- a/sdk/python/feast/entity.py
+++ b/sdk/python/feast/entity.py
@@ -12,8 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from typing import Dict, MutableMapping, Optional
+
+import yaml
+from google.protobuf import json_format
+from google.protobuf.json_format import MessageToDict, MessageToJson
+from google.protobuf.timestamp_pb2 import Timestamp
+
+from feast.core.Entity_pb2 import Entity as EntityV2Proto
+from feast.core.Entity_pb2 import EntityMeta as EntityMetaProto
+from feast.core.Entity_pb2 import EntitySpecV2 as EntitySpecProto
 from feast.core.FeatureSet_pb2 import EntitySpec as EntityProto
 from feast.field import Field
+from feast.loaders import yaml as feast_yaml
 from feast.types import Value_pb2 as ValueTypeProto
 from feast.value_type import ValueType
 
@@ -44,3 +55,273 @@ def from_proto(cls, entity_proto: EntityProto):
         """
         entity = cls(name=entity_proto.name, dtype=ValueType(entity_proto.value_type))
         return entity
+
+
+class EntityV2:
+    """
+    Represents a collection of entities and associated metadata.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str,
+        value_type: ValueType,
+        labels: Optional[MutableMapping[str, str]] = None,
+    ):
+        self._name = name
+        self._description = description
+        self._value_type = value_type
+        if labels is None:
+            self._labels = dict()  # type: MutableMapping[str, str]
+        else:
+            self._labels = labels
+
+        self._created_timestamp: Optional[Timestamp] = None
+        self._last_updated_timestamp: Optional[Timestamp] = None
+
+    def __eq__(self, other):
+        if not isinstance(other, EntityV2):
+            raise TypeError("Comparisons should only involve EntityV2 class objects.")
+
+        if isinstance(self.value_type, int):
+            self.value_type = ValueType(self.value_type).name
+        if isinstance(other.value_type, int):
+            other.value_type = ValueType(other.value_type).name
+
+        if (
+            self.labels != other.labels
+            or self.name != other.name
+            or self.description != other.description
+            or self.value_type != other.value_type
+        ):
+            return False
+
+        return True
+
+    def __str__(self):
+        return str(MessageToJson(self.to_proto()))
+
+    @property
+    def name(self):
+        """
+        Returns the name of this entity
+        """
+        return self._name
+
+    @name.setter
+    def name(self, name):
+        """
+        Sets the name of this entity
+        """
+        self._name = name
+
+    @property
+    def description(self):
+        """
+        Returns the description of this entity
+        """
+        return self._description
+
+    @description.setter
+    def description(self, description):
+        """
+        Sets the description of this entity
+        """
+        self._description = description
+
+    @property
+    def value_type(self):
+        """
+        Returns the type of this entity
+        """
+        return self._value_type
+
+    @value_type.setter
+    def value_type(self, value_type: ValueType):
+        """
+        Set the type for this entity
+        """
+        self._value_type = value_type
+
+    @property
+    def labels(self):
+        """
+        Returns the labels of this entity. This is the user defined metadata
+        defined as a dictionary.
+        """
+        return self._labels
+
+    @labels.setter
+    def labels(self, labels: MutableMapping[str, str]):
+        """
+        Set the labels for this entity
+        """
+        self._labels = labels
+
+    @property
+    def created_timestamp(self):
+        """
+        Returns the created_timestamp of this entity
+        """
+        return self._created_timestamp
+
+    @property
+    def last_updated_timestamp(self):
+        """
+        Returns the last_updated_timestamp of this entity
+        """
+        return self._last_updated_timestamp
+
+    def is_valid(self):
+        """
+        Validates the state of a entity locally. Raises an exception
+        if entity is invalid.
+        """
+
+        if not self.name:
+            raise ValueError("No name found in entity.")
+
+        if not self.value_type:
+            raise ValueError("No type found in entity {self.value_type}")
+
+    @classmethod
+    def from_yaml(cls, yml: str):
+        """
+        Creates an entity from a YAML string body or a file path
+
+        Args:
+            yml: Either a file path containing a yaml file or a YAML string
+
+        Returns:
+            Returns a EntityV2 object based on the YAML file
+        """
+
+        return cls.from_dict(feast_yaml.yaml_loader(yml, load_single=True))
+
+    @classmethod
+    def from_dict(cls, entity_dict):
+        """
+        Creates an entity from a dict
+
+        Args:
+            entity_dict: A dict representation of an entity
+
+        Returns:
+            Returns a EntityV2 object based on the entity dict
+        """
+
+        entity_proto = json_format.ParseDict(
+            entity_dict, EntityV2Proto(), ignore_unknown_fields=True
+        )
+        return cls.from_proto(entity_proto)
+
+    @classmethod
+    def from_proto(cls, entity_proto: EntityV2Proto):
+        """
+        Creates an entity from a protobuf representation of an entity
+
+        Args:
+            entity_proto: A protobuf representation of an entity
+
+        Returns:
+            Returns a EntityV2 object based on the entity protobuf
+        """
+
+        entity = cls(
+            name=entity_proto.spec.name,
+            description=entity_proto.spec.description,
+            value_type=ValueType(entity_proto.spec.value_type).name,  # type: ignore
+            labels=entity_proto.spec.labels,
+        )
+
+        entity._created_timestamp = entity_proto.meta.created_timestamp
+        entity._last_updated_timestamp = entity_proto.meta.last_updated_timestamp
+
+        return entity
+
+    def to_proto(self) -> EntityV2Proto:
+        """
+        Converts an entity object to its protobuf representation
+
+        Returns:
+            EntityV2Proto protobuf
+        """
+
+        meta = EntityMetaProto(
+            created_timestamp=self.created_timestamp,
+            last_updated_timestamp=self.last_updated_timestamp,
+        )
+        if isinstance(self.value_type, ValueType):
+            self.value_type = self.value_type.value
+
+        spec = EntitySpecProto(
+            name=self.name,
+            description=self.description,
+            value_type=self.value_type,
+            labels=self.labels,
+        )
+
+        return EntityV2Proto(spec=spec, meta=meta)
+
+    def to_dict(self) -> Dict:
+        """
+        Converts entity to dict
+
+        Returns:
+            Dictionary object representation of entity
+        """
+
+        entity_dict = MessageToDict(self.to_proto())
+
+        # Remove meta when empty for more readable exports
+        if entity_dict["meta"] == {}:
+            del entity_dict["meta"]
+
+        return entity_dict
+
+    def to_yaml(self):
+        """
+        Converts a entity to a YAML string.
+
+        Returns:
+            Entity string returned in YAML format
+        """
+        entity_dict = self.to_dict()
+        return yaml.dump(entity_dict, allow_unicode=True, sort_keys=False)
+
+    def to_spec_proto(self) -> EntitySpecProto:
+        """
+        Converts an EntityV2 object to its protobuf representation.
+        Used when passing EntitySpecV2 object to Feast request.
+
+        Returns:
+            EntitySpecV2 protobuf
+        """
+
+        if isinstance(self.value_type, ValueType):
+            self.value_type = self.value_type.value
+
+        spec = EntitySpecProto(
+            name=self.name,
+            description=self.description,
+            value_type=self.value_type,
+            labels=self.labels,
+        )
+
+        return spec
+
+    def _update_from_entity(self, entity):
+        """
+        Deep replaces one entity with another
+
+        Args:
+            entity: Entity to use as a source of configuration
+        """
+
+        self.name = entity.name
+        self.description = entity.description
+        self.value_type = entity.value_type
+        self.labels = entity.labels
+        self._created_timestamp = entity.created_timestamp
+        self._last_updated_timestamp = entity.last_updated_timestamp


Test patch:
diff --git a/core/src/test/java/feast/core/service/SpecServiceIT.java b/core/src/test/java/feast/core/service/SpecServiceIT.java
--- a/core/src/test/java/feast/core/service/SpecServiceIT.java
+++ b/core/src/test/java/feast/core/service/SpecServiceIT.java
@@ -68,6 +68,27 @@ public static void globalSetUp(@Value("${grpc.server.port}") int port) {
   public void initState() {
     SourceProto.Source source = DataGenerator.getDefaultSource();
 
+    apiClient.simpleApplyEntity(
+        "default",
+        DataGenerator.createEntitySpecV2(
+            "entity1",
+            "Entity 1 description",
+            ValueProto.ValueType.Enum.STRING,
+            ImmutableMap.of("label_key", "label_value")));
+    apiClient.simpleApplyEntity(
+        "default",
+        DataGenerator.createEntitySpecV2(
+            "entity2",
+            "Entity 2 description",
+            ValueProto.ValueType.Enum.STRING,
+            ImmutableMap.of("label_key2", "label_value2")));
+    apiClient.simpleApplyEntity(
+        "project1",
+        DataGenerator.createEntitySpecV2(
+            "entity3",
+            "Entity 3 description",
+            ValueProto.ValueType.Enum.STRING,
+            ImmutableMap.of("label_key2", "label_value2")));
     apiClient.simpleApplyFeatureSet(
         DataGenerator.createFeatureSet(
             source,
@@ -88,7 +109,7 @@ public void initState() {
             "project1",
             "fs3",
             ImmutableList.of(
-                DataGenerator.createEntity("user_id", ValueProto.ValueType.Enum.STRING)),
+                DataGenerator.createEntitySpec("user_id", ValueProto.ValueType.Enum.STRING)),
             ImmutableList.of(
                 DataGenerator.createFeature(
                     "feature1", ValueProto.ValueType.Enum.INT32, Collections.emptyMap()),
@@ -101,7 +122,7 @@ public void initState() {
             "project1",
             "fs4",
             ImmutableList.of(
-                DataGenerator.createEntity("customer_id", ValueProto.ValueType.Enum.STRING)),
+                DataGenerator.createEntitySpec("customer_id", ValueProto.ValueType.Enum.STRING)),
             ImmutableList.of(
                 DataGenerator.createFeature(
                     "feature2",
@@ -114,7 +135,7 @@ public void initState() {
             "project1",
             "fs5",
             ImmutableList.of(
-                DataGenerator.createEntity("customer_id", ValueProto.ValueType.Enum.STRING)),
+                DataGenerator.createEntitySpec("customer_id", ValueProto.ValueType.Enum.STRING)),
             ImmutableList.of(
                 DataGenerator.createFeature(
                     "feature3",
@@ -199,6 +220,51 @@ public void shouldThrowExceptionGivenMissingFeatureSetName() {
     }
   }
 
+  @Nested
+  class ListEntities {
+    @Test
+    public void shouldFilterEntitiesByLabels() {
+      List<EntityProto.Entity> entities =
+          apiClient.simpleListEntities("", ImmutableMap.of("label_key2", "label_value2"));
+
+      assertThat(entities, hasSize(1));
+      assertThat(entities, hasItem(hasProperty("spec", hasProperty("name", equalTo("entity2")))));
+    }
+
+    @Test
+    public void shouldUseDefaultProjectIfProjectUnspecified() {
+      List<EntityProto.Entity> entities = apiClient.simpleListEntities("");
+
+      assertThat(entities, hasSize(2));
+      assertThat(entities, hasItem(hasProperty("spec", hasProperty("name", equalTo("entity1")))));
+    }
+
+    @Test
+    public void shouldFilterEntitiesByProjectAndLabels() {
+      List<EntityProto.Entity> entities =
+          apiClient.simpleListEntities("project1", ImmutableMap.of("label_key2", "label_value2"));
+
+      assertThat(entities, hasSize(1));
+      assertThat(entities, hasItem(hasProperty("spec", hasProperty("name", equalTo("entity3")))));
+    }
+
+    @Test
+    public void shouldThrowExceptionGivenWildcardProject() {
+      CoreServiceProto.ListEntitiesRequest.Filter filter =
+          CoreServiceProto.ListEntitiesRequest.Filter.newBuilder().setProject("default*").build();
+      StatusRuntimeException exc =
+          assertThrows(StatusRuntimeException.class, () -> apiClient.simpleListEntities(filter));
+
+      assertThat(
+          exc.getMessage(),
+          equalTo(
+              String.format(
+                  "INVALID_ARGUMENT: invalid value for project resource, %s: "
+                      + "argument must only contain alphanumeric characters and underscores.",
+                  filter.getProject())));
+    }
+  }
+
   @Nested
   class ApplyFeatureSet {
     @Test
@@ -547,7 +613,8 @@ public void shouldUpdateLabels() {
                   "project1",
                   "fs4",
                   ImmutableList.of(
-                      DataGenerator.createEntity("customer_id", ValueProto.ValueType.Enum.STRING)),
+                      DataGenerator.createEntitySpec(
+                          "customer_id", ValueProto.ValueType.Enum.STRING)),
                   ImmutableList.of(
                       DataGenerator.createFeature(
                           "feature2",
@@ -574,7 +641,8 @@ public void shouldAcceptFeatureSetLabels() {
                   "",
                   "some",
                   ImmutableList.of(
-                      DataGenerator.createEntity("customer_id", ValueProto.ValueType.Enum.STRING)),
+                      DataGenerator.createEntitySpec(
+                          "customer_id", ValueProto.ValueType.Enum.STRING)),
                   ImmutableList.of(),
                   ImmutableMap.of("label", "some")));
 
@@ -584,6 +652,139 @@ public void shouldAcceptFeatureSetLabels() {
     }
   }
 
+  @Nested
+  class ApplyEntity {
+    @Test
+    public void shouldThrowExceptionGivenEntityWithDash() {
+      StatusRuntimeException exc =
+          assertThrows(
+              StatusRuntimeException.class,
+              () ->
+                  apiClient.simpleApplyEntity(
+                      "default",
+                      DataGenerator.createEntitySpecV2(
+                          "dash-entity",
+                          "Dash Entity description",
+                          ValueProto.ValueType.Enum.STRING,
+                          ImmutableMap.of("test_key", "test_value"))));
+
+      assertThat(
+          exc.getMessage(),
+          equalTo(
+              String.format(
+                  "INTERNAL: invalid value for %s resource, %s: %s",
+                  "entity",
+                  "dash-entity",
+                  "argument must only contain alphanumeric characters and underscores.")));
+    }
+
+    @Test
+    public void shouldThrowExceptionIfTypeChanged() {
+      String projectName = "default";
+
+      EntityProto.EntitySpecV2 spec =
+          DataGenerator.createEntitySpecV2(
+              "entity1",
+              "Entity description",
+              ValueProto.ValueType.Enum.FLOAT,
+              ImmutableMap.of("label_key", "label_value"));
+
+      StatusRuntimeException exc =
+          assertThrows(
+              StatusRuntimeException.class, () -> apiClient.simpleApplyEntity("default", spec));
+
+      assertThat(
+          exc.getMessage(),
+          equalTo(
+              String.format(
+                  "INTERNAL: You are attempting to change the type of this entity in %s project from %s to %s. This isn't allowed. Please create a new entity.",
+                  "default", "STRING", spec.getValueType())));
+    }
+
+    @Test
+    public void shouldReturnEntityIfEntityHasNotChanged() {
+      String projectName = "default";
+      EntityProto.EntitySpecV2 spec = apiClient.simpleGetEntity(projectName, "entity1").getSpec();
+
+      CoreServiceProto.ApplyEntityResponse response =
+          apiClient.simpleApplyEntity(projectName, spec);
+
+      assertThat(response.getEntity().getSpec().getName(), equalTo(spec.getName()));
+      assertThat(response.getEntity().getSpec().getDescription(), equalTo(spec.getDescription()));
+      assertThat(response.getEntity().getSpec().getLabelsMap(), equalTo(spec.getLabelsMap()));
+      assertThat(response.getEntity().getSpec().getValueType(), equalTo(spec.getValueType()));
+    }
+
+    @Test
+    public void shouldApplyEntityIfNotExists() {
+      String projectName = "default";
+      EntityProto.EntitySpecV2 spec =
+          DataGenerator.createEntitySpecV2(
+              "new_entity",
+              "Entity description",
+              ValueProto.ValueType.Enum.STRING,
+              ImmutableMap.of("label_key", "label_value"));
+
+      CoreServiceProto.ApplyEntityResponse response =
+          apiClient.simpleApplyEntity(projectName, spec);
+
+      assertThat(response.getEntity().getSpec().getName(), equalTo(spec.getName()));
+      assertThat(response.getEntity().getSpec().getDescription(), equalTo(spec.getDescription()));
+      assertThat(response.getEntity().getSpec().getLabelsMap(), equalTo(spec.getLabelsMap()));
+      assertThat(response.getEntity().getSpec().getValueType(), equalTo(spec.getValueType()));
+    }
+
+    @Test
+    public void shouldCreateProjectWhenNotAlreadyExists() {
+      EntityProto.EntitySpecV2 spec =
+          DataGenerator.createEntitySpecV2(
+              "new_entity2",
+              "Entity description",
+              ValueProto.ValueType.Enum.STRING,
+              ImmutableMap.of("key1", "val1"));
+      CoreServiceProto.ApplyEntityResponse response =
+          apiClient.simpleApplyEntity("new_project", spec);
+
+      assertThat(response.getEntity().getSpec().getName(), equalTo(spec.getName()));
+      assertThat(response.getEntity().getSpec().getDescription(), equalTo(spec.getDescription()));
+      assertThat(response.getEntity().getSpec().getLabelsMap(), equalTo(spec.getLabelsMap()));
+      assertThat(response.getEntity().getSpec().getValueType(), equalTo(spec.getValueType()));
+    }
+
+    @Test
+    public void shouldFailWhenProjectIsArchived() {
+      apiClient.createProject("archived");
+      apiClient.archiveProject("archived");
+
+      StatusRuntimeException exc =
+          assertThrows(
+              StatusRuntimeException.class,
+              () ->
+                  apiClient.simpleApplyEntity(
+                      "archived",
+                      DataGenerator.createEntitySpecV2(
+                          "new_entity3",
+                          "Entity description",
+                          ValueProto.ValueType.Enum.STRING,
+                          ImmutableMap.of("key1", "val1"))));
+      assertThat(exc.getMessage(), equalTo("INTERNAL: Project is archived: archived"));
+    }
+
+    @Test
+    public void shouldUpdateLabels() {
+      EntityProto.EntitySpecV2 spec =
+          DataGenerator.createEntitySpecV2(
+              "entity1",
+              "Entity description",
+              ValueProto.ValueType.Enum.STRING,
+              ImmutableMap.of("label_key", "label_value", "label_key2", "label_value2"));
+
+      CoreServiceProto.ApplyEntityResponse response = apiClient.simpleApplyEntity("default", spec);
+
+      assertThat(response.getEntity().getSpec().getLabelsMap(), equalTo(spec.getLabelsMap()));
+    }
+  }
+
   @Nested
   class UpdateStore {
     @Test
@@ -624,6 +825,25 @@ public void shouldThrowExceptionGivenMissingFeatureSet() {
     }
   }
 
+  @Nested
+  class GetEntity {
+    @Test
+    public void shouldThrowExceptionGivenMissingEntity() {
+      StatusRuntimeException exc =
+          assertThrows(
+              StatusRuntimeException.class, () -> apiClient.simpleGetEntity("default", ""));
+
+      assertThat(exc.getMessage(), equalTo("INVALID_ARGUMENT: No entity name provided"));
+    }
+
+    public void shouldRetrieveFromDefaultIfProjectNotSpecified() {
+      String entityName = "entity1";
+      EntityProto.Entity entity = apiClient.simpleGetEntity("", entityName);
+
+      assertThat(entity.getSpec().getName(), equalTo(entityName));
+    }
+  }
+
   @Nested
   class ListStores {
     @Test
diff --git a/sdk/python/tests/test_entity.py b/sdk/python/tests/test_entity.py
new file mode 100644
--- /dev/null
+++ b/sdk/python/tests/test_entity.py
@@ -0,0 +1,86 @@
+# Copyright 2020 The Feast Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import socket
+from concurrent import futures
+from contextlib import closing
+
+import grpc
+import pytest
+
+from feast.client import Client
+from feast.core import CoreService_pb2_grpc as Core
+from feast.entity import EntityV2
+from feast.value_type import ValueType
+from feast_core_server import CoreServicer
+
+
+def find_free_port():
+    with closing(socket.socket(socket.AF_INET, socket.SOCK_STREAM)) as s:
+        s.bind(("", 0))
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return s.getsockname()[1]
+
+
+free_port = find_free_port()
+
+
+class TestEntity:
+    @pytest.fixture(scope="function")
+    def server(self):
+        server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
+        Core.add_CoreServiceServicer_to_server(CoreServicer(), server)
+        server.add_insecure_port(f"[::]:{free_port}")
+        server.start()
+        yield server
+        server.stop(0)
+
+    @pytest.fixture
+    def client(self, server):
+        return Client(core_url=f"localhost:{free_port}")
+
+    def test_entity_import_export_yaml(self):
+
+        test_entity = EntityV2(
+            name="car_driver_entity",
+            description="Driver entity for car rides",
+            value_type=ValueType.STRING,
+            labels={"team": "matchmaking"},
+        )
+
+        # Create a string YAML representation of the entity
+        string_yaml = test_entity.to_yaml()
+
+        # Create a new entity object from the YAML string
+        actual_entity_from_string = EntityV2.from_yaml(string_yaml)
+
+        # Ensure equality is upheld to original entity
+        assert test_entity == actual_entity_from_string
+
+
+def test_entity_class_contains_labels():
+    entity = EntityV2(
+        "my-entity",
+        description="My entity",
+        value_type=ValueType.STRING,
+        labels={"key1": "val1", "key2": "val2"},
+    )
+    assert "key1" in entity.labels.keys() and entity.labels["key1"] == "val1"
+    assert "key2" in entity.labels.keys() and entity.labels["key2"] == "val2"
+
+
+def test_entity_without_labels_empty_dict():
+    entity = EntityV2("my-entity", description="My entity", value_type=ValueType.STRING)
+    assert entity.labels == dict()
+    assert len(entity.labels) == 0