> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-feat-druid-driver-streaming.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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][ref-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`][ref-meta-endpoint] 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`](#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][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={null}
  view_groups:
    - name: sales
  ```

  ```javascript title="JavaScript" theme={null}
  view_group(`sales`, {})
  ```
</CodeGroup>

### `title`

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

<CodeGroup>
  ```yaml title="YAML" theme={null}
  view_groups:
    - name: sales
      title: Sales
  ```

  ```javascript title="JavaScript" theme={null}
  view_group(`sales`, {
    title: `Sales`
  })
  ```
</CodeGroup>

### `description`

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

<CodeGroup>
  ```yaml title="YAML" theme={null}
  view_groups:
    - name: sales
      title: Sales
      description: Revenue, order, and customer views for the sales team
  ```

  ```javascript title="JavaScript" theme={null}
  view_group(`sales`, {
    title: `Sales`,
    description: `Revenue, order, and customer views for the sales team`
  })
  ```
</CodeGroup>

### `includes`

A list of [views][ref-views] that belong to this group. It can also contain
nested view groups (see [Nesting](#nesting) below).

<CodeGroup>
  ```yaml title="YAML" theme={null}
  view_groups:
    - name: sales
      title: Sales
      includes:
        - orders_overview
        - revenue
  ```

  ```javascript title="JavaScript" theme={null}
  view_group(`sales`, {
    title: `Sales`,
    includes: [`orders_overview`, `revenue`]
  })
  ```
</CodeGroup>

#### Nesting

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

<CodeGroup>
  ```yaml title="YAML" theme={null}
  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 title="JavaScript" theme={null}
  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`](#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`.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  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 title="JavaScript" theme={null}
  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 theme={null}
{
  "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.

[ref-views]: /docs/data-modeling/views

[ref-view-nesting]: /reference/data-modeling/view#nesting

[ref-naming]: /docs/data-modeling/concepts/syntax#naming

[ref-meta-endpoint]: /reference/core-data-apis/rest-api/reference