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 user_count
can have dimensions like country
, age
, occupation
, etc.
Any dimension should have the following properties: name
, sql
and type
.
Parameters
name
The name
parameter serves as the identifier of a dimension. It must be unique
among all dimensions, measures, and segments within a cube and follow the
naming conventions.
cubes:
- name: products
dimensions:
- name: price
sql: price
type: number
- name: brand_name
sql: brand_name
type: string
case
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
:
cubes:
- name: products
# ...
dimensions:
- name: 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` },
},
},
},
});
description
You can add details to a dimension's definition via the description
property:
cubes:
- name: products
# ...
dimensions:
- name: comment
description: Comments for orders
sql: comments
type: string
format
format
is an optional parameter. It is used to format the output of dimensions
in different ways, for example, a link for external_url
. Please refer to the
Dimension Formats for the full list of supported
formats.
cubes:
- name: orders
# ...
dimensions:
- name: total
sql: amount
type: number
format: currency
meta
Custom metadata. Can be used to pass any information to the frontend.
cubes:
- name: products
# ...
dimensions:
- name: users_count
sql: "{users.count}"
type: number
meta:
any: value
primary_key
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 primary_key
to true
will change the default value of public
parameter to false
. If you still want public
to be true
, set it manually.
cubes:
- name: products
# ...
dimensions:
- name: id
sql: id
type: number
primary_key: true
propagate_filters_to_sub_query
When this statement is set to true
, the filters applied to the query will be
passed to the subquery.
cubes:
- name: products
# ...
dimensions:
- name: users_count
sql: "{users.count}"
type: number
sub_query: true
propagate_filters_to_sub_query: true
public
Prior to v0.33, this property was called shown
.
The public
property is used to manage the visibility of a dimension. Valid
values for public
are true
and false
. When set to false
, this dimension
cannot be queried through the API. Defaults to true
.
cubes:
- name: products
# ...
dimensions:
- name: comment
sql: comments
public: false
shown: false
sql
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 to understand what the sql
parameter should
be for a given dimension type.
cubes:
- name: orders
# ...
dimensions:
- name: created_at
sql: created_at
type: time
sub_query
The sub_query
statement allows you to reference a measure in a dimension. It's
an advanced concept and you can learn more about it here.
cubes:
- name: products
# ...
dimensions:
- name: users_count
sql: "{users.count}"
type: number
sub_query: true
title
You can use the title
parameter to change a dimension's displayed name. By
default, Cube will humanize your dimension key to create a display name. In
order to override default behavior, please use the title
property:
cubes:
- name: products
# ...
dimensions:
- name: meta_value
title: Size
sql: meta_value
type: string
type
type
is a required parameter. There are various types that can be assigned to
a dimension. Please refer to the Dimension Types
for the full list of dimension types.
cubes:
- name: orders
# ...
dimensions:
- name: rating
sql: rating
type: number