View groups

View groups organize views into named collections, making it easier for data consumers to navigate and discover related views.

View groups let you organize views into named collections. When a data model contains many views, grouping them by domain or purpose helps downstream consumers — including AI agents, embedded analytics, and visualization tools — discover the right dataset faster.

View groups are returned as a top-level viewGroups array in the /v1/meta response, alongside the cubes array. Each view that belongs to at least one group also carries a viewGroups string array on its own entry.

A view group should have the following parameter: name.

Parameters

name

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

YAML

view_groups:
  - name: sales

title

Use the title parameter to set a human-readable display name for the view group.

YAML

view_groups:
  - name: sales
    title: Sales

description

This parameter provides a human-readable description of the view group.

YAML

view_groups:
  - name: sales
    title: Sales
    description: Revenue, order, and customer views for the sales team

views

A list of view names that belong to this group. Views listed here are merged with any views that reference this group via their own view_group or view_groups parameter.

YAML

view_groups:
  - name: sales
    title: Sales
    views:
      - orders_overview
      - revenue

Assigning views to groups

There are two complementary ways to associate a view with a view group:

1. On the view group — list view names in the views parameter.
2. On the view — set view_group (singular) or view_groups (plural) on the view itself.

Both approaches can be combined. Cube merges the membership from all sources, so a view listed under a group’s views and referencing that group via view_group will appear only once.

Example

The following model defines two view groups. The sales group lists orders_overview in its views parameter; revenue joins the same group via its own view_group property. The customers_view belongs to people through the group-level views list.

YAML

cubes:
  - name: order_items
    sql_table: ECOMMERCE.ORDER_ITEMS

    measures:
      - name: count
        type: count

      - name: total_sale_price
        sql: sale_price
        type: sum

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: status
        sql: status
        type: string

      - name: created_at
        sql: created_at
        type: time

  - name: users
    sql_table: ECOMMERCE.USERS

    measures:
      - name: count
        type: count

    dimensions:
      - name: id
        sql: id
        type: number
        primary_key: true

      - name: city
        sql: city
        type: string

views:
  - name: orders_overview
    cubes:
      - join_path: order_items
        includes:
          - count
          - total_sale_price
          - status
          - created_at

  - name: revenue
    view_group: sales
    cubes:
      - join_path: order_items
        includes:
          - total_sale_price
          - created_at

  - name: customers_view
    cubes:
      - join_path: users
        includes: "*"

view_groups:
  - name: sales
    title: Sales
    description: Revenue and order views for the sales team
    views:
      - orders_overview

  - name: people
    title: People
    description: Customer and user views
    views:
      - customers_view

With this model, the /v1/meta response includes a viewGroups array:

{
  "viewGroups": [
    {
      "name": "sales",
      "title": "Sales",
      "description": "Revenue and order views for the sales team",
      "views": ["orders_overview", "revenue"]
    },
    {
      "name": "people",
      "title": "People",
      "description": "Customer and user views",
      "views": ["customers_view"]
    }
  ]
}

Notice that revenue appears in the sales group even though it was not listed in the group’s views — it was added because the view itself set view_group: sales.