View groups - Cube — ContextQMD

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

javascript

view_group(`sales`, {})

</CodeGroup>

`title`

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

yaml

view_groups:
  - name: sales
    title: Sales

javascript

view_group(`sales`, {
  title: `Sales`
})

</CodeGroup>

`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

javascript

view_group(`sales`, {
  title: `Sales`,
  description: `Revenue, order, and customer views for the sales team`
})

</CodeGroup>

`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

javascript

view_group(`sales`, {
  title: `Sales`,
  includes: [`orders_overview`, `revenue`]
})

</CodeGroup>

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

javascript

view_group(`sales`, {
  title: `Sales`,
  includes: [
    `orders_overview`,
    `revenue`,
    {
      name: `enterprise_sales`,
      title: `Enterprise Sales`,
      description: `Views for the enterprise sales team`,
      includes: [`enterprise_deals`]
    }
  ]
})

</CodeGroup>

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

javascript

cube(`order_items`, {
  sql_table: `ECOMMERCE.ORDER_ITEMS`,

  measures: {
    count: {
      type: `count`
    },

    total_sale_price: {
      sql: `sale_price`,
      type: `sum`
    }
  },

  dimensions: {
    id: {
      sql: `id`,
      type: `number`,
      primary_key: true
    },

    status: {
      sql: `status`,
      type: `string`
    },

    created_at: {
      sql: `created_at`,
      type: `time`
    }
  }
})

cube(`users`, {
  sql_table: `ECOMMERCE.USERS`,

  measures: {
    count: {
      type: `count`
    }
  },

  dimensions: {
    id: {
      sql: `id`,
      type: `number`,
      primary_key: true
    },

    city: {
      sql: `city`,
      type: `string`
    }
  }
})

view(`orders_overview`, {
  cubes: [
    {
      join_path: order_items,
      includes: [
        `count`,
        `total_sale_price`,
        `status`,
        `created_at`
      ]
    }
  ]
})

view(`revenue`, {
  cubes: [
    {
      join_path: order_items,
      includes: [
        `total_sale_price`,
        `created_at`
      ]
    }
  ]
})

view(`customers_view`, {
  cubes: [
    {
      join_path: users,
      includes: `*`
    }
  ]
})

view_group(`sales`, {
  title: `Sales`,
  description: `Revenue and order views for the sales team`,
  includes: [`orders_overview`, `revenue`]
})

view_group(`people`, {
  title: `People`,
  description: `Customer and user views`,
  includes: [`customers_view`]
})

</CodeGroup>

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

json

{
  "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.