Model Fields

Introduction

Each data model contains fields (similar to data table and their respective columns). This page describe the fields in details.

As mentioned in Modeling section, Data Model is abstract representation of database table with additional metadata. Similarly, Model's Fields can be thought of an abstract representation of table's columns with additional metadata.

Model Field's Attributes

These are the attributes of a data model's field:

  • Name: True, unique name of the field which analysts will see when managing modeling. Think of this as variable names.
    • Only lowercase alpha-numeric characters (a-z, 0 - 9) and underscores (_) are allowed. If the name starts with a numeric character, the name will be prepended with an underscore (1abcxy_1abcxy)
  • Label: Nice name of the field (what viewers see). You should make the Label as descriptive as possible.
  • Description: This provides more context to understand the field, for example how the field is calculated, or what this field should be used for.
  • Visibility: Whether this field should be visible or hidden to the end business users.
    • It is still visible in Data Modeling interface and accessible in SQL interfaces (when writing SQLs or creating calculated fields)

Types of Model Field

There are 3 types of model fields:

  • Base Dimension
  • Custom Dimension
  • Custom Measure

Base Dimension

Base Dimensions are the "original" dimensions that you got when you first create your model. Think of this as, when you "load" your database table into a model, the table's columns become base dimensions.

Base dimensions can only be hidden, and cannot be removed via the UI.

Custom Dimension

To extend on base dimension, you can create Custom Dimension by supplying a formula. For example, given a birth_date field, you can create custom dimension age to determine how old a user is.

Model users {
type: 'table'
label: 'Users'
table_name: 'public.users'
// .. other basic fields
dimension birth_date {
label: 'Birth Date'
type: 'datetime'
definition: @sql{{ birth_date }};;
}
dimension age {
label: 'Age'
type: 'number'
definition: @sql {{ date_part('year', current_date) -
date_part('year', {{ #THIS.birth_date }}) }};;
}
}

Custom dimensions are created using SQL syntaxes with non-aggregate operations (e.g CASE WHEN, CONCAT(), field_a + field_b, etc)

When creating Custom Dimensions (Calculated Fields), you can reuse other dimensions that you created in the same model:

Notes:

  • When you use Persistence setting, Custom Dimensions will not be persisted to the database.
  • You can use your SQL DB's equivalent of the CAST() operation in a custom dimension to create a new field with the new datatype.

Custom Measure

Measures are similar to Custom Dimension, except that they're created using only aggregate functions/operations. Think of Measure as the aggregate expression of your typical SQL statement.

In Measures' formula, you can refer to any base dimension, custom dimension and measures you created in the same model.