Dataset properties

note

Metriql will ignore the dbt resources that doesn't have meta.metriql property.

models/schema.yml

models: # can be seeds, sources, and metrics as well.
  - name: customers
    description: List of customers
    meta:
     metriql:
      label: Customers
      hidden: false
      measures:
        total_rows:
          aggregation count
          dimension | column | sql <reference>
          filters <filters>
             // filtered measure
      dimensions
        full_location:
          column | sql <reference>
          type: string
      category User Segments
      mappings
        user_id: id
        event_timestamp: occurred_at
      relations
        events:
          to: ref('user_id')
      aggregates
        total_customers:
           measures: ['total_rows']
           dimensions: ['full_location']
      always_filters
        - {dimension: 'is_active', value: true}
    columns:
       country:
         description: The country the user signed up from
         meta:
           metriql.dimension:
              type string
              label User Country
              category Location
              hidden false
              primary false
              name location_country
       created_at:
         meta:
           metriql.dimension:
              type: timestamp
              timeframes [day, week, month, year] # only available for timestamp columns
       total_sales:
         meta:
           metriql.measure:
              aggregation sum

label:

The value will be shown in the user interface. If the label is not set, the default label is the name of the model.

label: Facebook Ads

hidden:

If the value is true, the model will not show up in the user interface.

hidden: false

category:

If you set the category field in your models, the system requires the end user to select one of the categories before selecting the actual model. Otherwise, all the models under the same page will be listed in a single select box. It's good practice to set the category field for accessibility if you have more than 20 models. If you have set the category in at least one of the models, the models that don't belong to a category will be grouped as Uncategorized in the user interface.

measures:

There are two ways to define a measure; under <model l seed | source>.columns.meta.measure:

created_at:
    meta:
        metriql.measure:
            aggregation: count_unique
            column: user_id

or <model l seed | source>.meta.metriql.measures for measures that will be written as SQL:

models:
  - name: facebook_ads
    meta:
      metriql:
        measures:
          custom_measure:
            aggregation: sum
            sql: "{TABLE}.column1 * 2"

For more information, see Measure properties

dimensions:

There are two ways to define a dimension; under <model l seed | source>.columns.meta.dimension:

created_at:
         meta:
           metriql.dimension:
          type: timestamp
          timeframes: [day, week, month, year] # only available for timestamp columns

or <model l seed | source>.meta.metriql.dimension for measures that will be written as SQL:

models:
       - name: facebook_ads
         meta:
              metriql:
                   dimensions:
                        custom_dimension:
                         sql: "{{TABLE}}.column1 * 2"

relations:

The relations between the models can be defined under <model l seed | source>.meta.metriql.relations as follows:

models:
  - name: events
    meta:
      metriql:
        relations:
          user_attributes:
            model: users
            sql: "{TABLE}.user_id = {TARGET}.id"
            relationship: many_to_one
            type: left_join

aggregates:

Aggregates should be defined under <model | seed | source>.meta.metriql.aggregates. You can see the Aggregate properties or learn more about the concept on Aggregates.

always_filters:

If you define always_filters for a view, the system pushes the relevant filter for all the queries that are executed in metriql.

models:
  - name: pageview_events
    always_filters: 
      - {dimension: event_type, operator: equals, value: 'pageview'}

extends

If you want to re-use the dimensions, measures, relations, and mappings of another model or source in a dbt project, you can extend from it. When you extend from another dbt model, Metriql automatically re-use the fields in the current model. If you have additional fields, it tries to merge all the fields that are defined in the current model.

models:
  - name: pageview_events
    extends: ref('all_events')

name

danger

If you use the name property in dbt resource files, you won't be able to reference your models with ref or sources with source syntax.

The unique identifier of the dataset. The name lets you reference the dataset from other dataset. The names must be lowercase and does not have any special character except _. Metriql will complain if the dataset names that has whitespace, non-ascii, or any upppercase character.