Measures

The measures parameter contains a set of measures and each measure is an aggregation over a certain column in your database table.

Any measure should have the following properties: name, sql and type.

Parameters

name

The name parameter serves as the identifier of a measure. It must be unique among all measures, dimensions, and segments within a cube and follow the naming conventions.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: count
        sql: id
        type: count
 
      - name: total_amount
        sql: amount
        type: sum

description

This parameter provides a human-readable description of a measure. When applicable, it will be displayed in Playground and exposed to data consumers via APIs and integrations.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: orders_count
        description: Count of all orders
        sql: id
        type: count

drill_members

Using the drill_members parameter, you can define a set of drill down fields for the measure. drill_members is defined as an array of dimensions. Cube automatically injects dimensions’ names and other cubes’ names with dimensions in the context, so you can reference these variables in the drill_members array. Learn more about how to define and use drill downs.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: revenue
        type: sum
        sql: price
        drill_members:
          - id
          - price
          - status
          - products.name
          - products.id

filters

If you want to add some conditions for a metric's calculation, you should use the filters parameter. The syntax looks like the following:

cubes:
  - name: orders
    # ...
 
    measures:
      - name: orders_completed_count
        sql: id
        type: count
        filters:
          - sql: "{CUBE}.status = 'completed'"

format

format is an optional parameter. It is used to format the output of measures in different ways, for example, as currency for revenue. Please refer to the Measure Formats for the full list of supported formats.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: total
        sql: amount
        type: sum
        format: currency

meta

Custom metadata. Can be used to pass any information to the frontend.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: revenue
        type: sum
        sql: price
        meta:
          any: value

rolling_window

If you want to calculate some metric within a window, for example a week or a month, you should use a rolling_window parameter. The trailing and leading parameters define window size.

These parameters have a format defined as (-?\d+) (minute|hour|day|week|month|year). The trailing and leading parameters can also be set to an unbounded value, which means infinite size for the corresponding window part. You can define trailing and leading parameters using negative integers.

The trailing parameter is a window part size before the offset point and the leading parameter is after it. You can set the window offset parameter to either start or end, which will match the start or end of the selected date range. By default, the leading and trailing parameters are set to zero and offset is set to end.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: rolling_count_month
        sql: id
        type: count
        rolling_window:
          trailing: 1 month

Here's an example of an unbounded window that's used for cumulative counts:

cubes:
  - name: orders
    # ...
 
    measures:
      - name: cumulative_count
        type: count
        rolling_window:
          trailing: unbounded

public

The public property is used to manage the visibility of a measure. Valid values for public are true and false. When set to false, this measure cannot be queried through the API. Defaults to true.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: orders_count
        sql: id
        type: count
        public: false

sql

sql is a required parameter. It can take any valid SQL expression depending on the type of the measure. Please refer to the Measure Types Guide for detailed information on the corresponding sql parameter.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: users_count
        sql: "COUNT(*)"
        type: number

Depending on the measure type, the sql parameter would either:

• Be skipped (in case of the count type).
• Contain an aggregate function, e.g., STRING_AGG(string_dimension, ',') (in case of string, time, boolean, and number types).
• Contain a non-aggregated expression that Cube would wrap into an aggregate function according to the measure type (in case of the avg, count_distinct, count_distinct_approx, min, max, and sum types).

title

You can use the title parameter to change a measure’s displayed name. By default, Cube will humanize your measure key to create a display name. In order to override default behavior, please use the title parameter.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: orders_count
        title: Number of Orders Placed
        sql: id
        type: count

type

type is a required parameter. There are various types that can be assigned to a measure. Please refer to the Measure Types for the full list of measure types.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: orders_count
        sql: id
        type: count

Calculated measures

In the case where you need to specify a formula for measure calculating with other measures, you can compose a formula in sql. For example, to calculate the conversion of buyers of all users.

cubes:
  - name: orders
    # ...
 
    measures:
      - name: purchases_to_created_account_ratio
        sql: "{purchases} / {users.count} * 100.0"
        type: number
        format: percent

You can create calculated measures from several joined cubes. In this case, a join will be created automatically.