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

includes

A list of views that belong to this group. It can also contain nested view groups (see Nesting below).

YAML

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

Nesting

View groups can be nested, similar to nested folders. The includes parameter can contain not only references to views but also other view groups, each with its own title, description, and includes.

YAML

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

      - name: enterprise_sales
        title: Enterprise Sales
        description: Views for the enterprise sales team
        includes:
          - enterprise_deals

Assigning views to groups

To associate a view with a view group, list its name in the includes parameter on the view group.

Example

The following model defines two view groups. The sales group lists orders_overview and revenue in its includes parameter, while the people group lists customers_view.

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
    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
    includes:
      - orders_overview
      - revenue

  - name: people
    title: People
    description: Customer and user views
    includes:
      - 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",
      "includes": ["orders_overview", "revenue"]
    },
    {
      "name": "people",
      "title": "People",
      "description": "Customer and user views",
      "includes": ["customers_view"]
    }
  ]
}

Each view group carries an includes array that preserves the authoring order and contains the group’s views as well as any nested view groups.