0
# Entities
1

2
Entities define the primary keys and identifiers around which features are organized in Feast. They establish the join keys used to associate features with specific instances and enable proper data relationships across different feature views.
3

4
## Capabilities
5

6
### Entity Definition
7

8
Create entity definitions that specify the join keys, data types, and metadata for feature groupings.
9

10
```python { .api }
11
class Entity:
12
    def __init__(
13
        self,
14
        *,
15
        name: str,
16
        join_keys: Optional[List[str]] = None,
17
        value_type: Optional[ValueType] = None,
18
        description: str = "",
19
        tags: Optional[Dict[str, str]] = None,
20
        owner: str = ""
21
    ):
22
        """
23
        Define an entity for feature organization.
24
        
25
        Parameters:
26
        - name: Unique entity name
27
        - join_keys: List of properties for joining (defaults to [name] if not specified)
28
        - value_type: Data type of the entity key (inferred if not specified)
29
        - description: Human-readable description
30
        - tags: Key-value metadata tags
31
        - owner: Entity owner/maintainer identifier
32
        """
33
```
34

35
### Entity Properties
36

37
Access and modify entity attributes for runtime inspection and configuration.
38

39
```python { .api }
40
@property
41
def name(self) -> str:
42
    """Entity name."""
43

44
@property  
45
def value_type(self) -> ValueType:
46
    """Entity value type."""
47

48
@property
49
def join_keys(self) -> List[str]:
50
    """Join keys for feature associations."""
51

52
@property
53
def description(self) -> str:
54
    """Entity description."""
55

56
@property
57
def tags(self) -> Dict[str, str]:
58
    """Entity tags."""
59

60
@property
61
def owner(self) -> str:
62
    """Entity owner."""
63
```
64

65
### Entity Serialization
66

67
Convert entities to and from protocol buffer format for registry storage and network communication.
68

69
```python { .api }
70
def to_proto(self) -> EntityProto:
71
    """Convert entity to protocol buffer format."""
72

73
@classmethod
74
def from_proto(cls, entity_proto: EntityProto) -> "Entity":
75
    """Create entity from protocol buffer."""
76
```
77

78
## Value Types
79

80
Entity value types specify the data type of entity keys for proper type checking and serialization.
81

82
```python { .api }
83
class ValueType(Enum):
84
    """Supported entity value types."""
85
    UNKNOWN = 0
86
    BYTES = 1
87
    STRING = 2
88
    INT32 = 3
89
    INT64 = 4
90
    DOUBLE = 5
91
    FLOAT = 6
92
    BOOL = 7
93
    UNIX_TIMESTAMP = 8
94
    BYTES_LIST = 11
95
    STRING_LIST = 12
96
    INT32_LIST = 13
97
    INT64_LIST = 14
98
    DOUBLE_LIST = 15
99
    FLOAT_LIST = 16
100
    BOOL_LIST = 17
101
    UNIX_TIMESTAMP_LIST = 18
102
    NULL = 19
103
    PDF_BYTES = 20
104
```
105

106
## Usage Examples
107

108
### Basic Entity Creation
109

110
```python
111
from feast import Entity, ValueType
112

113
# Create a customer entity
114
customer = Entity(
115
    name="customer",
116
    value_type=ValueType.INT64,
117
    description="Customer identifier",
118
    tags={"team": "marketing", "pii": "false"}
119
)
120

121
# Create a product entity with custom join keys
122
product = Entity(
123
    name="product",
124
    value_type=ValueType.STRING,
125
    join_keys=["product_id"],
126
    description="Product SKU identifier",
127
    owner="product-team@company.com"
128
)
129

130
# Create a location entity
131
location = Entity(
132
    name="location",
133
    value_type=ValueType.STRING,
134
    description="Geographic location code"
135
)
136
```
137

138
### Entity Usage in Feature Views
139

140
```python
141
from feast import FeatureView, Field, FileSource
142
from datetime import timedelta
143

144
# Use entities in feature view definitions
145
customer_features = FeatureView(
146
    name="customer_features",
147
    entities=[customer],  # Reference the entity
148
    ttl=timedelta(days=1),
149
    schema=[
150
        Field(name="age", dtype=ValueType.INT64),
151
        Field(name="income", dtype=ValueType.DOUBLE),
152
        Field(name="city", dtype=ValueType.STRING)
153
    ],
154
    source=FileSource(path="data/customers.parquet", timestamp_field="ts")
155
)
156

157
# Multi-entity feature view
158
order_features = FeatureView(
159
    name="order_features", 
160
    entities=[customer, product],  # Multiple entities
161
    ttl=timedelta(hours=24),
162
    schema=[
163
        Field(name="quantity", dtype=ValueType.INT32),
164
        Field(name="price", dtype=ValueType.DOUBLE)
165
    ],
166
    source=FileSource(path="data/orders.parquet", timestamp_field="order_time")
167
)
168
```
169

170
### Entity Inspection and Metadata
171

172
```python
173
# Inspect entity properties
174
print(f"Entity name: {customer.name}")
175
print(f"Value type: {customer.value_type}")  
176
print(f"Join keys: {customer.join_keys}")
177
print(f"Description: {customer.description}")
178
print(f"Tags: {customer.tags}")
179

180
# Convert to protocol buffer for storage
181
entity_proto = customer.to_proto()
182

183
# Recreate from protocol buffer
184
restored_entity = Entity.from_proto(entity_proto)
185
```
186

187
### Entity Validation Patterns
188

189
```python
190
# Entity with comprehensive metadata
191
user_entity = Entity(
192
    name="user",
193
    value_type=ValueType.STRING,
194
    join_keys=["user_id"],
195
    description="Unique user identifier across all systems",
196
    tags={
197
        "data_classification": "internal",
198
        "retention_policy": "7_years", 
199
        "source_system": "user_management",
200
        "team": "identity"
201
    },
202
    owner="identity-team@company.com"
203
)
204

205
# Validate entity configuration
206
assert user_entity.name == "user"
207
assert user_entity.value_type == ValueType.STRING
208
assert user_entity.join_keys == ["user_id"]
209
```