Dimensions

Dimensions define the characteristics and features of the entities in your semantic models. They play a critical role in making your data more meaningful. In this document we will cover everything you need to know to use dimensions to build effective semantic models; what they are, why they're important, and how to use them effectively.

What are dimensions?

Dimensions represent the real-world features or aspects of entities. Defining your entities' dimensions gives meaning to the columns and fields in your raw data tables. They can be either direct "mappings" specific source fields or more custom equations. Entity dimensions can be incredibly useful for more accurately and efficiently slicing and dicing your metrics data.

Why are dimensions important?

Dimensions serve as fundamental elements in data analytics, providing structure and clarity to entities used in metric calculations and downstream analytics tools. Creating and maintaining rich and precise dimension definitions offers the following benefits:

• More accessible data: Clear and consistent dimensions empower non-technical users to engage with data, promoting a data-driven culture across the organization.
• Flexible and adaptable analytics: Dimensions can be tailored to fit specific analytical needs and modified to adapt to changes in business logic and processes as the organization grows in complexity.
• Improved alignement on data: Consistent dimensions that are defined once with clear governance give teams clarity and decrease conflicts and contradictions in their reporting.
• More efficient analytics: Well-structured dimensions reduce the need for manual data manipulation and replication of the same logic, saving time and resources and allowing teams to focus on more strategic analyses.

How to use dimensions

To use dimensions effectively and build robust semantic models, you'll need a solid understanding of the dimension schema as well as how to map and calculate dimensions.

Dimension schema

Dimensions are created and modified for each entity in its respective semantic model. Entities' have a dimensions property in which all of the entities' defined dimensions are listed with the following schema structure:

      - name:
        type:
        sources:
          - sql:
          ...
        meta:
          display_name:
          description:

This table outlines the purpose of each dimension property:

Properties	Description	Example
name	Field identifier	contract_length
type	Data type of the field; including string, number, bool and timestampz	number
sources	List of possible source dimensions or calculations	- sql: $src__contract_length, - sql: (12)
meta (optional)	Metadata for the field, including display_name and description	-

How are dimensions defined?

Dimensions are defined by assigning their source and any fallbacks where necessary. The source property of each dimension contains a list of queries, where the first item determines primary source and all subsequent items are fallbacks to use when preceding items are not available (null value).

The following example of the contract_length dimension helps clarify how sources work:

- name: contract_length
type: number
sources:
    - sql: $src__contract_length
    - sql: (12) # default contract length
meta:
    display_name: Contract length
    description: The opportunity's contract length, in months. Defaults to 12 months.

In this example, the source of the contract_length dimension is the $src_contract_length field (contract_length in the raw table). If that source is not available - because the original column value is null - then the dimension will fallback to the 12 constant.

Source types

Any valid query can be used as a source for a dimension, these generally fall into one of 5 main types:

Direct refernce

Directly reference the value of another source field or defined dimension on the same entity. This approach allows you to directly reference and utilize values that are already defined within the same entity. It's commonly used for straightforward cases where no complex computation or reference to related entities is required.

- sql: $src__close_date # source dimension
- sql: $contract_length # defined dimension

Lookup

Lookup involves using the value of a source field or defined dimension from a related entity. This is achieved through a many-to-one relationship. It's a powerful way to enrich data by including relevant information from an associated entity, usually a parent or owner of some kind.

- sql: $account.src__industry # source industry field on account
- sql: $owner.tenure # tenure defined dimension on owner

Rollup

Rollup aggregates dimension values from several related entities through a one-to-many relationship. This method is essential for aggregating or extracting data from multiple related entities, such as all opportunity line items or all account leads.

- sql: sum($line_items.src__amount) # sum all line item amounts
- sql: min($leads.converted_date) # get first lead converted date

Constant

A constant value is used, often as a fallback or default value, in scenarios where dynamic data is not required or available. This method ensures that there is always a value present, even in cases where the data might be missing or not applicable.

- sql: (12) # set value to (12)
- sql: "Other" # set value to 'Other'

Equation

For more complex logic and calculations, combining various dimensions, operations, and aggregations to calculate the dimension value. Equations can leverage query syntax freely, including arithmetic and logical operations, aggregations as well as direct references to other fields and dimensions. Equation dimensions are ideal for scenarios where you need to creating complicated custom dimensions that require complex operations.

- sql: $amount * $src__probability # create weighted_amount value
- sql: (CASE WHEN $is_won = true THEN $amount ELSE 0 END) # create won_amount value
- sql: (sum($orders.amount) / count($orders.src__id)) # create average order amount per customer entity

Wrapping up

In Wrapping up, dimensions are key to leveraging semantic mapping to create a solid and consistent foundation for analytics. They provide the much-needed context and depth to raw data, transforming it into meaningful information and consistent defintions that capture the business logic and main features of the real-world. By thoughtfully defining and maintaing dimensions, teams ensure consistent and adaptable analytics and reporting.