Dimensions

The dimensions property contains a set of dimensions. You can think about a dimension as an attribute related to a measure, e.g. the measure userCount can have dimensions like country, age, occupation, etc.

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

You can name a dimension by following the same rules as for measure, so each name should:

  • Be unique within a cube
  • Start with a lowercase letter
  • Consist of numbers, letters and _
JS
YAML
cube(`Products`, {
  dimensions: {
    price: {
      sql: `price`,
      type: `number`,
    },

    brand_name: {
      sql: `brand_name`,
      type: `string`,
    },
  },
});

The case statement is used to define if/then/else conditions to display data. It contains two parameters: when and then. The first when statement declares a condition and result if the rule returns a true value. The second else statement declares results for options when rules return a false value.

The following static label example will create a size dimension with values xl and xxl:

JS
YAML
cube('Products', {
  dimensions: {
    size: {
      type: `string`,
      case: {
        when: [
          { sql: `${CUBE}.meta_value = 'xl-en'`, label: `xl` },
          { sql: `${CUBE}.meta_value = 'xl'`, label: `xl` },
          { sql: `${CUBE}.meta_value = 'xxl-en'`, label: `xxl` },
          { sql: `${CUBE}.meta_value = 'xxl'`, label: `xxl` },
        ],
        else: { label: `Unknown` },
      },
    },
  },
});

The label property can be defined dynamically as an object with a sql property in JavaScript models:

cube('Products', {
  dimensions: {
    size: {
      type: `string`,
      case: {
        when: [
          {
            sql: `${CUBE}.meta_value = 'xl-en'`,
            label: { sql: `${CUBE}.english_size` },
          },
          {
            sql: `${CUBE}.meta_value = 'xl'`,
            label: { sql: `${CUBE}.euro_size` },
          },
          {
            sql: `${CUBE}.meta_value = 'xxl-en'`,
            label: { sql: `${CUBE}.english_size` },
          },
          {
            sql: `${CUBE}.meta_value = 'xxl'`,
            label: { sql: `${CUBE}.euro_size` },
          },
        ],
        else: { label: `Unknown` },
      },
    },
  },
});

You can add details to a dimension's definition via the description property:

JS
YAML
cube('Products', {
  dimensions: {
    comment: {
      type: `string`,
      sql: `comments`,
      description: `Comments for orders`,
    },
  },
});

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

JS
YAML
cube('Products', {
  dimensions: {
    users_count: {
      sql: `${Users.count}`,
      type: `number`,
      meta: {
        any: 'value',
      },
    },
  },
});

Specify which dimension is a primary key for a cube. The default value is false.

A primary key is used to make joins work properly.

Setting primaryKey to true will change the default value of shown parameter to false. If you still want shown to be true, set it manually.

JS
YAML
cube('Products', {
  dimensions: {
    id: {
      sql: `id`,
      type: `number`,
      primaryKey: true,
    },
  },
});

When this statement is set to true, the filters applied to the query will be passed to the subquery.

JS
YAML
cube('Products', {
  dimensions: {
    users_count: {
      sql: `${Users.count}`,
      type: `number`,
      subQuery: true,
      propagateFiltersToSubQuery: true,
    },
  },
});

You can manage the visibility of the dimension using the shown property. The default value of shown is true.

JS
YAML
cube('Products', {
  dimensions: {
    comment: {
      type: `string`,
      sql: `comments`,
      shown: false,
    },
  },
});

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

cube(`Orders`, {
  dimensions: {
    created_at: {
      sql: `created_at`,
      type: `time`,
    },
  },
});

The subQuery statement allows you to reference a measure in a dimension. It's an advanced concept and you can learn more about it here.

JS
YAML
cube('Products', {
  dimensions: {
    users_count: {
      sql: `${Users.count}`,
      type: `number`,
      subQuery: true,
    },
  },
});

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

JS
YAML
cube('Products', {
  dimensions: {
    meta_value: {
      type: `string`,
      sql: `meta_value`,
      title: `Size`,
    },
  },
});

Did you find this page useful?