Entities

In Sightfull, entities play a critical role in the structure and interpretation of data. This document outlines the schema structure of an Entity YAML file, providing insights into how entities are defined and utilized within the semantic model.

What is an entity?

In the context of semantic mapping, an entity represents a key object or interaction within your business domain, such as a customer, product, or touchpoint. It serves as a fundamental building block for constructing the semantic model, allowing you to organize and interpret your data in a meaningful way.

Entity schema structure

The entity YAML file in Sightfull defines the structure and attributes of each entity. Here is the general structure of the entity schema:

entities:
  - name:
    meta:
      display_name:
      description:
    data_source:
      schema:
      table:
      filters:
        - sql:
    primary_keys:
    relationships:
      - name:
        ...
    dimensions:
      - name:
        ...

This table of entity properties details their definitions and example values:

Property	Description	Example
name	The unique identifier of the entity.	account
meta (optional)	Metadata for the entity, including display_name and description.	All our accounts, including potential, target, active and previous customers
data_source	Source of the entity data, including definitions of the data schema, table and any filters to apply (useful for mapping only part of the table to an entity).	- sql: $src__test_account = False
primary_keys	Unique ID columns of the entity, important for accurate relationships and best performance.	$src__id
relationships	List of important entity relationships to other entities.	See Relationships
dimensions	List of mapped and calculated dimensions in the entity.	See Dimensions

The purpose of entities

Entities form the basic buiding blocks of your semantic models. They represent real-world objects or events as captured in the source data tables. Transforming raw data to meaningful entities provides a robust foundation for the metric layer and all other analytics in downstream consumption tools.

When defining entities, mind the following key principles:

• Model reality: entities should reflect real-world objects that matter and should be measured.
• Exclusivity: each entity should represent a unique kind of object, avoid overlapping entities.
• Detailed definition: all relationships and dimensions that are important for downstream analytics should be accurately defined in the entity.

Wrapping up

Entities are the lego pieces that build up semantic models, transforming messy raw data to a structured, robust and meaningful foundation. Create and manage entities to ensure your semantic and metric layers represent your business logic and support your analytics needs.