Building your first entity

Welcome to this step-by-step guide for creating your first entity in Sightfull. This tutorial will walk you through the basics of creating entities. It focuses on their core components and integrating these components. Let's embark on this journey to build a foundational entity.

What you'll learn in this guide

• Understanding the core components of an entity in Sightfull
• The process of creating an entity in Sightfull
• Integrating entities, dimensions, and relationships in your model

Entity schema structure

Before diving into the creation process, let's understand what a semantic model is. In Sightfull, a semantic model is a structured representation of data that defines how different entities relate to each other and the dimensions that characterize them. It serves as a map or blueprint that simplifies complex data structures into understandable and usable formats.

An entity is defined in a YAML file in a schema with the following structure:

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

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

Property	Description	Example
name	The unique identifier of the entity.	account
meta (optional)	Metadata of 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	Entity columns with unique IDs. They are important for accurate relationships and best performance.	$src__id
relationships	List of mapped links to other entities, used for defining dimensions and calculating metrics.	See Relationships
dimensions	List of mapped and calculated characteristics and features in the entity.	See Dimensions

tip

In Sightfull schemas, all references to dimensions and relationships are preceded by the $ symbol. Field names as they appear in the origin tables are preceded by the src__ prefix. So the original ID or created date fields are called $src__id and $src__created_date in semantic models and metric schemas.

Step-by-step guide

Step 1: Create an entity

Start by identifying the main entity your model will represent. This could be a customer, product, transaction, etc. Think of an entity as the central piece of your model around which everything else revolves. Define the source schema and table to which the entity maps and add any required filters to make sure only the relevant rows are mapped to entities.

For example, this model relies on the account table in the salesforce schema and filters it by account_status to create the customer entity:

entities:
  - name: customer
    meta:
      display_name: Customer
      description: All our accounts with an "Active" status
    data_source:
      schema: salesforce
      table: account
      filters:
        - sql: $src__account_status = 'Active'

Step 2: Establish relationships

Consider the important relationships, links, and associations this entity has (or should have) to other entities. This could be relationships such as a customer to their contracts, a user to their manager, etc. Relationships help to contextualize your entity within your broader data ontology (read more about ontology here).

In this example, customers' contacts and owner relationships are defined:

relationships:
  - name: contacts
    referenced_entity: contact
    type: one_to_many
    on: "$src__id = $contact.src__account_id"
    meta:
      display_name: Contacts
      description: All customer contacts

  - name: owner
    referenced_entity: user
    type: many_to_one
    on: "$src__owner_id = $user.src__id"
    meta:
      display_name: Owner
      description: The owner of this customer

Read more about relationship properties and definitions here.

Step 3: Define dimensions

Next, define the key attributes or characteristics that describe your entity. These are called "dimensions." Define the dimensions that are necessary to accurately select, aggregate, and measure entities. If a dimension is used in metric calculation, it must be defined in the semantic mapping.

For example, we can map the annual_revenue, customer_owner_name, and number_of_contacts dimensions of the account table.

dimensions:
  - name: annual_revenue
    type: number
    source:
      - sql: $src_annual_revenue
    meta:
      display_name: Annual Revenue
      description: The annual revenue of this customer's business

  - name: customer_owner_name
    type: string
    source:
      - sql: $owner.src__name
    meta:
      display_name: Owner Name
      description: The name of the customer account owner

  - name: number_of_contacts
    type: number
    source:
      - sql: count(distinct $contacts.src__id)
    meta:
      display_name: Number of Contacts
      description: The number of contacts associated with this customer account

Read more about mapping and calculating dimensions here.

Step 4: Refine and test

Once you set up an entity in your semantic model, test and iterate to ensure accuracy and consistency. Be sure to test the following to catch common issues:

• The entity is created and includes the "source" table columns
• Dimensions that utilize relationships are accurately created and calculated
• The logic defined in the dimensions' source is behaving as expected.

Step 5: Expand and update

You can freely add semantic models with more entities, relationships, and dimensions to expand and develop your ontology. Semantic models are meant to be flexible, adaptable, and connected to continue supporting your needs as they evolve and your data complexity grows.

Wrapping up

Building your first entity is a key step to unlocking the full potential of semantic mapping for more consistent and accurate analytics. Thoughtful semantic mapping can transform complex and noisy raw data into the meaningful information necessary for metrics that represent the real world and produce actionable insights. Remember, the level of detail in defining entities, dimensions, and relationships, as well as testing and update cadences, are the keys to successful semantic models.

For more detailed information on each component, explore our documentation on entities, dimensions, and relationships.