Views

Views are curated compositions of cube members that simplify consumption and clarify join paths for downstream tools.

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.

YAML

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:

YAML

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.

YAML

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.

YAML

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.

YAML

views:
  - name: orders
    public: false

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

YAML

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.

You can also use the ai_context key to provide context to the AI agent without exposing it in the user interface.

YAML

views:
  - name: active_users
    meta:
      any: value
      ai_context: >
        This view shows users active in the last 14 days.
        Use for engagement analysis questions.

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.

YAML

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:

YAML

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:

YAML

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:

YAML

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.

filters

The filters parameter is used to define default value filters on a view. These filters are applied to every query against the view, narrowing down the result set to a specific subset of data without requiring data consumers to specify the filter explicitly.

Default value filters are useful for governance scenarios where a view should always be scoped to a particular value (e.g., a tenant, region, or currency). They can also be used to provide a sensible default that consumers can override by adding their own filter on the same member, by leveraging the unless parameter.

YAML

views:
  - name: orders_us

    cubes:
      - join_path: orders
        includes: "*"

    filters:
      - member: country
        operator: equals
        values:
          - US

Each filter accepts the following parameters:

member

The name of the dimension to filter on. The member must be exposed by the view.

operator

The filter operator. Supported operators match the ones available in the REST API query format: equals, notEquals, contains, notContains, startsWith, notStartsWith, endsWith, notEndsWith, in, notIn, gt, gte, lt, lte, set, notSet, inDateRange, notInDateRange, onTheDate, beforeDate, beforeOrOnDate, afterDate, afterOrOnDate.

values

A list of values for the filter operator. Required for all operators except set and notSet.

unless

The unless parameter optionally lists members that, when referenced in a query (either in the projection or in an explicit filter), will cause the default value filter to be released. This allows consumers to override the default filter by querying or filtering by one of the listed members.

If unless is not specified, the filter is always applied.

YAML

views:
  - name: orders_default_us

    cubes:
      - join_path: orders
        includes: "*"

    filters:
      - member: country
        operator: equals
        values:
          - US
        unless:
          - country

In the example above, the country = US filter is applied by default. However, if a query explicitly filters on country (e.g., country = FR), the default filter is released and the explicit filter is used instead.

access_policy

The access_policy parameter is used to configure access policies.