Entities

Entities are real-world concepts like customers, orders, payments etc. These are first-class citizens in Lynk, meaning everything we build and consume is around entities.

The main concept of Lynk Data Modeling Framework is to create a central source of truth for each of the entities in the business, in a trusted and accessible way. In other words, from a business perspective, for each business entity it should be clear what we know of it, how was it defined, and where we can find it. We call these pieces of information on an entity level - features.

---

Defining Entities

Entities can be defined either via code or via Lynk Studio UI. The below example shows how we define a customer entity as a YAML file:

# customer.yml

name: customer

description: a customer is a user who logged in at least once

key_table: db_prod.core.customer_dim

aliases:
- user

features:
- type: metric
  name: orders_count
  asset: db_prod.core.orders
  measure: orders_count
  filters: null

measures:
- name: average_orders
  description: average of orders count per customer
  sql: avg({orders_count})
  
related_assets:
  db_prod.core.orders:
    relationship: one_to_many
    joins:
    - name: all_orders
      default: true
      type: sql
      sql: "{source}.{customer_id} = {destination}.{customer_id}"

For a quick onboarding, use the discovery process to automatically extract business entities from your Data Warehouse schemas and SQL code.

description

Free text to describe the entity

key_table

An entities is defined by it's key data asset. An entity key data asset is a table or a view in the data warehouse, that has all the entity instances, and each entity instance exists only once on this asset.

For example, if our entity is customer, it's key data asset should have all the customers, and each customer appears only once in that data asset.

The entity DIM table is a good fit here, if exists in the DWH. However, any data asset which answers the the above requirement can fit. Once loaded as an entity in Lynk, you will be able to add as many enrichment features as needed.

aliases

Sometimes different people might call the same entity by different names. e.g a customer can also be referred to as a user. This is relevant especially when interacting with AI apps to ask questions. Lynk supports aliases to entity names.

features

Features are attributes that represent all we know about our Entities. It can be simple fields, aggregated metrics, first - last features, period-over-period formulas, custom formulas and more. See Features page for in depth information on this.

measures

Measures are reusable aggregate definitions that can be defined on an entity level. Entity level measures are being used once the entity is aggregated (rolled-up) and they define centrally how entity aggregations should be performed. See Measures page for in depth information on this.

related_assets

Define which Data Assets are related to the entity. Related assets will be shown and used when creating new features for an entity. For example, if the data asset db_prod.core.orders is related to the entity customer, we will be able to extract features from db_prod.core.orders to the customer level. See Related assets for in depth information on this.

---

Entity relationships

To see how to define and use relationships between entities, please see Entity-to-Enitity Relations page.

---

Consuming Entities

Entities and their Features and Measures can be consumed via SQL API or SQL REST API.

-- Example for a simple SQL API query
SELECT  customer_id,
        total_order_amount,
        first_order_date,
        last_order_status
FROM    entity('customer') 
WHERE   country = 'US'
LIMIT   100

---

Governance

Lynk Governance makes sure Entities are unique:

• Entities have unique names

• Entities have unique Key data asset

• Entity key asset validation (no duplications, no missing instances)

• Entities do not share the same aliases

---

Discovery

Lynk Discovery makes it easy to bootstrap your project and define entities automatically. Read more on this on the Discovery page.