ContextQMD
Back to Cube

Views

docs/content/product/data-modeling/reference/view.mdx

1.6.4313.3 KB
Original Source

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.

<CodeTabs>
javascript
view(`active_users`, {})
yaml
views:
  - name: active_users
</CodeTabs>

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:

<CodeTabs>
javascript
view(`orders`, {
  cubes: [
    {
      join_path: `base_orders`,
      includes: `*`
    }
  ]
})

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

  - name: extended_orders
    extends: orders
    cubes:
      - join_path: base_orders.users
        includes: "*"
</CodeTabs>

title

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

<CodeTabs>
javascript
cube(`orders`, {
  sql_table: `orders`,
  title: `Product Orders`
})
yaml
cubes:
  - name: orders
    sql_table: orders
    title: Product Orders
</CodeTabs>

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.

<CodeTabs>
javascript
view(`active_users`, {
  description: `14 days rolling count of active users`
})
yaml
views:
  - name: active_users
    description: 14 days rolling count of active users
</CodeTabs>

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.

<CodeTabs>
yaml
views:
  - name: orders
    public: false
javascript
view(`orders`, {
  public: false
})
</CodeTabs>

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

<CodeTabs>
javascript
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`
    }
  ]
})
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
</CodeTabs>

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.

<CodeTabs>
javascript
view(`active_users`, {
  meta: {
    any: `value`
  }
})
yaml
views:
  - name: active_users
    meta:
      any: value
</CodeTabs>

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.

<CodeTabs>
javascript
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`
      ]
    }
  ]
})
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
</CodeTabs>

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.

<InfoBox>

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

</InfoBox>

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

<CodeTabs>
javascript
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`
      ]
    }
  ]
})
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
</CodeTabs>

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:

<CodeTabs>
javascript
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`
      ]
    }
  ]
})
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
</CodeTabs>

Nesting

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

<CodeTabs>
javascript
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`
          ]
        }
      ]
    }
  ]
})
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
</CodeTabs>

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 <EnvVar>CUBEJS_NESTED_FOLDERS_DELIMITER</EnvVar> 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.