Entities and Join Keys
An Entity is a Tecton abstraction over a set of primary keys used for looking up feature data. An Entity represents a real-world "thing" that has data associated with it. Examples include Customer, Transaction, Product, and Product Category.
In Tecton, every Feature is associated with one or more entities. For example:
- A customer's lifetime transaction count is associated with just one Entity: Customer.
- A lifetime transaction count of how many purchases a customer has made within a product category is associated with two entities: Customer and Product Category.
Entities provide a way to:
- Organize Features. An Entity can belong to any number of Features, and a Feature can be associated with any number of Entities. A Feature associated with a Customer Entity, for example, can be described as being a feature derived from or of a Customer.
- Prevent duplication. When creating an Entity, Feature Store users must agree on what to call it. For example, a commercial interaction with an e-commerce provider could be called a Transaction or a Purchase. Assume you decide on the term Transaction for this Entity. Once the Entity is created, all Features having to do with commercial interactions with an e-commerce provider must include the Transaction Entity.
- Join Features that are associated with the same Entity. In Tecton, Entities have regularized keys to relate Features that are based on the same Entities (described below). Tecton stores these keys as attributes of an Entity and enforces their integrity.
- Discover associated Features. Features that share Entities represent different information about that Entity. Use Tecton's Web UI to filter for Features of an Entity of interest.
Defining an Entity​
Define an Entity using the Entity
class. Entity
objects are configured by
the following attributes:
name
is a unique identifier for the Entity class. For example: Customer or Transaction.join_keys
are the names of primary key columns that uniquely identify anEntity
instance. All Features that share an Entity identify that Entity Instance using the same primary key column. For example, ifuser_id
identifies a Customer, then all Features derived from Customer refer to customers with auser_id
primary key.
More information can be found in the Entity API reference.
Example: Entities​
This example defines two Entities, Customer and Transaction:
/feature_store/entities.py
customer = Entity(name="Customer", join_keys=[Field("customer_id", String)])
transaction = Entity(name="Transaction", join_keys=[Field("transaction_id", String)])
The Entity
object defines the join_key
columns. This definition is
independent of a data source or Feature transformation.
You might need to define two different Features calculated from two raw data
sources that use different primary key columns. This is no problem, and is in
fact one of the reasons to use Entities. For example, assume one raw data source
uses customer_id
as the primary key column and another uses
customer_identifier
(You could name the join key either of these, or something
altogether different. We recommend you unify those to one key in your
transformations. E.g. SELECT customer_id as customer_identifier
.) Both
Features are associated with the Customer Entity, and both use the Customer
join key to search Customer instances.
Example: Entity with Two Join Keys​
This example defines one Entity, Company Employee, defined by two join keys:
/feature_store/entities.py
customer = Entity(name="Company Employee", join_keys=[Field("company_id", String), Field("employee_id", String)])
When you define an entity with two join keys, the entity is uniquely defined by
both join keys, and you can define a feature that is associated with the
Company Employee Entity. This feature will then use both company_id
and
employee_id
to search for Company Employee instances.
Using Entities in Feature Views​
In this example, my_feature_view
defines Features derived from Transactions,
so it must include the transaction
Entity in its definition.
transaction = Entity(name="Transaction", join_keys=[Field("transaction_id", String)])
@batch_feature_view(
entities=[transaction],
# ...
)
def my_feature_view(input_data):
pass
Join Keys in Feature Services​
When you define a Feature Service that includes multiple feature views, the feature services will need the join keys for all entities in the feature views to query.
For example you might have two entities:
customer = Entity(name="Customer", join_keys=[Field("customer_id", String)])
transaction = Entity(name="Transaction", join_keys=[Field("transaction_id", String)])
You might define two feature views: user_feature_view
with entities = [user]
and user_transaction_feature_view
with entities = [user, transaction]
. You
can then define a feature service that includes both of these feature views:
fs = FeatureService(name="my_fs", features=[user_feature_view, user_transaction])
Your feature service will need the union of all join keys from the entities in
the feature views it includes. In this case, the feature service will need both
customer_id
and transaction_id
to query.
You can additionally rebind join keys in the feature service definition as shown below:
transaction_fraud_service = FeatureService(
name="transaction_fraud_service",
features=[
user_features.with_name("sender_features").with_join_key_map({"user_id": "sender_id"}),
user_features.with_name("recipient_features").with_join_key_map({"user_id": "recipient_id"}),
],
)
This feature service can look up different entities of the same User Entity
type so that you can query with different join keys: sender_id
and
recipient
. You can now get user features for both the sender and recipient of
a transaction.