Skip to Content
DocumentationData modelingReferenceViews

Views

Views sit on top of the data graph of cubes and create a facade of your whole data model with which data consumers can interact. They are useful for defining metrics, managing governance and data access, and controlling ambiguous join paths.

Any view should have the following parameters: name and cubes.

Parameters

name

The name parameter serves as the identifier of a view. It must be unique among all cubes and views within a deployment and follow the naming conventions.

view(`active_users`, {})
 
views:
  - name: active_users

extends

You can use the extends parameter to extend views in order to reuse all declared members of a view.

In the example below, extended_orders will extend orders with an additional join path:

view(`orders`, {
  cubes: [
    {
      join_path: `base_orders`,
      includes: `*`
    }
  ]
})
 
view(`extended_orders`, {
  extends: orders,
  cubes: [
    {
      join_path: `base_orders.users`,
      includes: `*`
    }
  ]
})
views:
  - name: orders
    cubes:
      - join_path: base_orders
        includes: "*"
 
  - name: extended_orders
    extends: orders
    cubes:
      - join_path: base_orders.users
        includes: "*"

title

Use the title parameter to change the display name of the view.

cube(`orders`, {
  sql_table: `orders`,
  title: `Product Orders`
})
cubes:
  - name: orders
    sql_table: orders
    title: Product Orders

description

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

A description can give a hint both to your team and end users, making sure they interpret the data correctly.

view(`active_users`, {
  description: `14 days rolling count of active users`
})
views:
  - name: active_users
    description: 14 days rolling count of active users

public

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

views:
  - name: orders
    public: false
view(`orders`, {
  public: false
})

You can also use COMPILE_CONTEXT for dynamic visibility if necessary, check out our Controlling access to cubes and views recipe.

view(`arr`, {
  description: `Annual Recurring Revenue`,
  public: COMPILE_CONTEXT.security_context.is_finance,
 
  cubes: [
    {
      join_path: revenue,
      includes: [
        `arr`,
        `date`
      ]
    },
    {
      join_path: revenue.customers,
      includes: `plan`
    }
  ]
})
views:
  - name: arr
    description: Annual Recurring Revenue
    public: COMPILE_CONTEXT.security_context.is_finance
 
    cubes:
      - join_path: revenue
        includes:
          - arr
          - date
 
      - join_path: revenue.customers
        includes:
          - plan

To learn more about using public to control visibility based on security context, read the Controlling access to cubes and views recipe.

meta

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

view(`active_users`, {
  meta: {
    any: `value`
  }
})
views:
  - name: active_users
    meta:
      any: value

cubes

Use cubes parameter in view to include exposed cubes in bulk. You can build your view by combining multiple joined cubes together and specifying the path by which they should be joined for that particular view.

view(`orders`, {
  cubes: [
    {
      join_path: base_orders,
      includes: [
        `status`,
        `created_date`,
        `total_amount`,
        `total_amount_shipped`,
        `count`,
        `average_order_value`
      ]
    },
    {
      join_path: base_orders.line_items.products,
      includes: [
        {
          name: `name`,
          alias: `product`,
          title: `My custom product`,
          description: `My custom product description`,
          format: `number`,
          meta: {
            some: `custom`,
            meta: `data`
          }
        }
      ]
    },
    {
      join_path: base_orders.users,
      prefix: true
      includes: `*`,
      excludes: [
        `company`
      ]
    }
  ]
})
views:
  - name: orders
 
    cubes:
      - join_path: base_orders
        includes:
          - status
          - created_date
          - total_amount
          - total_amount_shipped
          - count
          - average_order_value
 
      - join_path: base_orders.line_items.products
        includes:
          - name: name
            alias: product
            title: My custom product
            description: My custom product description
            format: number
            meta:
              some: custom
              meta: data
 
      - join_path: base_orders.users
        prefix: true
        includes: "*"
        excludes:
          - company

join_path

When listing cubes to expose, you need to provide a join_path parameter. It uses the “dot notation” to describe the join path: cube_1.cube_2.cube_3.

For the root cube of the view, just use the cube name as in the example above for base_orders.

includes and excludes

The other required parameter inside the cubes block is includes. Use it to list measures, dimensions, or segments you’d like to include into the view.

To include all members from a cube, use the includes all shorthand: includes: "*". In that case, you can also use the excludes parameter to list members that you’d like to exclude.

prefix

If you’d like to prefix exposed members with the cube name, you can do so by setting the prefix parameter to true. It will prefix members with the cube name, e.g. users_city. You can use the alias parameter to specify a custom prefix.

alias

If you’d like to rename an included member, you can use the alias parameter.

title

If you’d like to override the title of a member, you can use the title parameter.

description

If you’d like to override the description of a member, you can use the description parameter.

format

If you’d like to override the format of a member, you can use the format parameter.

meta

If you’d like to override the metadata of a member, you can use the meta parameter. Note that the meta is overridded as a whole.

folders

The folders parameter is used to organize members of a view (e.g., dimensions, hierarchies, measures, etc.) into logical groups. Folders can contain non-overlapping subsets of members from a view.

Folders display is subject to support in visualization tools. Check APIs & Integrations for details. You can also preview folders in Playground.

Each folder should specify a human-readable name via the name parameter and list included members via the includes parameter:

view(`customers`, {
  cubes: [
    {
      join_path: `users`,
      includes: `*`
    },
    {
      join_path: `users.orders`,
      prefix: true,
      includes: [
        `status`,
        `price`,
        `count`
      ]
    }
  ],
 
  folders: [
    {
      name: `Basic Details`,
      includes: [
        `created_at`,
        `location`,
        `orders_status`,
        `orders_count`
      ]
    },
 
    {
      name: `Sensitive Details`,
      includes: [
        `name`,
        `gender`
      ]
    }
  ]
})
views:
  - name: customers
 
    cubes:
      - join_path: users
        includes: "*"
 
      - join_path: users.orders
        prefix: true
        includes:
          - status
          - price
          - count
 
    folders:
      - name: Basic Details
        includes:
          - created_at
          - location
          - orders_status
          - orders_count
 
      - name: Sensitive Details
        includes:
          - name
          - gender

You can also use the join_path parameter within includes to add all members from a specific join path without listing them individually. You can mix join_path with individual member names in the same folder:

view(`orders`, {
  cubes: [
    {
      join_path: base_orders,
      includes: `*`
    },
    {
      join_path: base_orders.line_items,
      includes: `*`
    },
    {
      join_path: base_orders.users,
      includes: [
        `count`,
        {
          name: `count_distinct`,
          alias: `users_distinct_count`
        }
      ]
    }
  ],
 
  folders: [
    {
      name: `Order Details`,
      includes: [
        { join_path: base_orders }
      ]
    },
    {
      name: `Line Items & Users`,
      includes: [
        { join_path: base_orders.line_items },
        `count`,
        `users_distinct_count`
      ]
    }
  ]
})
views:
  - name: orders
 
    cubes:
      - join_path: base_orders
        includes: "*"
 
      - join_path: base_orders.line_items
        includes: "*"
 
      - join_path: base_orders.users
        includes:
          - count
          - name: count_distinct
            alias: users_distinct_count
 
    folders:
      - name: Order Details
        includes:
          - join_path: base_orders
 
      - name: Line Items & Users
        includes:
          - join_path: base_orders.line_items
          - count
          - users_distinct_count

Nesting

Nested folders are also supported. The includes parameter can contain not only references to view members but also other folders:

view(`customers`, {
  cubes: [
    {
      join_path: `users`,
      includes: `*`
    },
    {
      join_path: `users.orders`,
      prefix: true,
      includes: [
        `status`,
        `price`,
        `count`
      ]
    }
  ],
 
  folders: [
    {
      name: `Customer Information`,
      includes: [
        {
          name: `Personal Details`,
          includes: [
            `name`,
            `gender`
          ]
        },
        {
          name: `Location`,
          includes: [
            `address`,
            `postal_code`,
            `city`
          ]
        }
      ]
    },
    {
      name: `Order Analytics`,
      includes: [
        `orders_status`,
        `orders_price`,
        {
          name: `Metrics`,
          includes: [
            `orders_count`,
            `orders_average_value`
          ]
        }
      ]
    }
  ]
})
views:
  - name: customers
 
    cubes:
      - join_path: users
        includes: "*"
 
      - join_path: users.orders
        prefix: true
        includes:
          - status
          - price
          - count
 
    folders:
      - name: Customer Information
        includes:
          - name: Personal Details
            includes:
              - name
              - gender
 
          - name: Location
            includes:
              - address
              - postal_code
              - city
 
      - name: Order Analytics
        includes:
          - orders_status
          - orders_price
          
          - name: Metrics
            includes:
              - orders_count
              - orders_average_value

You can still define nested folders in the data model even if some of your visualization tools do not support them. Check APIs & Integrations for details on the nested folders support.

For tools that do not support nested folders, the nested structure will be flattened: by default, the members of nested folders are merged into folders at the root level. You can also set the CUBEJS_NESTED_FOLDERS_DELIMITER environment variable to preserve nested folders and give them path-like names, e.g., Customer Information / Personal Details.

access_policy

The access_policy parameter is used to configure access policies.

Was this page useful?

CubesMeasures