> ## Documentation Index
> Fetch the complete documentation index at: https://cubed3-claude-gallant-ramanujan-86st4p.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Views
> Views are curated compositions of cube members that simplify consumption and clarify join paths for downstream tools.
Views sit on top of the data graph of [cubes][ref-ref-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`](#name) and [`cubes`](#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][ref-naming].
```yaml title="YAML" theme={null}
views:
- name: active_users
```
```javascript title="JavaScript" theme={null}
view(`active_users`, {})
```
### `extends`
You can use the `extends` parameter to [extend views][ref-extension] in order to reuse
all declared members of a view.
In the example below, `extended_orders` will extend `orders` with an additional join path:
```yaml title="YAML" theme={null}
views:
- name: orders
cubes:
- join_path: base_orders
includes: "*"
- name: extended_orders
extends: orders
cubes:
- join_path: base_orders.users
includes: "*"
```
```javascript title="JavaScript" theme={null}
view(`orders`, {
cubes: [
{
join_path: `base_orders`,
includes: `*`
}
]
})
view(`extended_orders`, {
extends: orders,
cubes: [
{
join_path: `base_orders.users`,
includes: `*`
}
]
})
```
### `title`
Use the `title` parameter to change the display name of the view.
```yaml title="YAML" theme={null}
cubes:
- name: orders
sql_table: orders
title: Product Orders
```
```javascript title="JavaScript" theme={null}
cube(`orders`, {
sql_table: `orders`,
title: `Product Orders`
})
```
### `description`
This parameter provides a human-readable description of a view.
When applicable, it will be displayed in [Playground][ref-playground] and exposed
to data consumers via [APIs and integrations][ref-apis].
A description can give a hint both to your team and end users, making sure they
interpret the data correctly.
```yaml title="YAML" theme={null}
views:
- name: active_users
description: 14 days rolling count of active users
```
```javascript title="JavaScript" theme={null}
view(`active_users`, {
description: `14 days rolling count of active users`
})
```
### `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`.
```yaml title="YAML" theme={null}
views:
- name: orders
public: false
```
```javascript title="JavaScript" theme={null}
view(`orders`, {
public: false
})
```
You can also use `COMPILE_CONTEXT` for dynamic visibility if necessary, check
out our
[Controlling access to cubes and views ](/docs/data-modeling/access-control)
recipe.
```yaml title="YAML" theme={null}
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
```
```javascript title="JavaScript" theme={null}
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`
}
]
})
```
To learn more about using `public` to control visibility based on security
context, read the [Controlling access to cubes and views
recipe][ref-recipe-control-access-cubes-views].
### `meta`
Custom metadata. Can be used to pass any information to the frontend.
You can also use the `ai_context` key to provide context to the
[AI agent][ref-ai-context] without exposing it in the user interface.
```yaml title="YAML" theme={null}
views:
- name: active_users
meta:
any: value
ai_context: >
This view shows users active in the last 14 days.
Use for engagement analysis questions.
```
```javascript title="JavaScript" theme={null}
view(`active_users`, {
meta: {
any: `value`,
ai_context: `This view shows users active in the last 14 days.
Use for engagement analysis questions.`
}
})
```
#### `auto_run`
In the Cube cloud platform, you can use the `auto_run` key in a view's `meta`
to control whether [workbook][ref-workbook-running] queries against the view
run automatically. By default, a workbook re-runs the query every time a data
consumer changes it — adds a member, edits a filter, and so on. Setting
`auto_run: false` turns this off for the view: the query only runs when the
user clicks **Run query**.
This is useful for views backed by heavy or expensive queries, where running
on every change would be wasteful.
Please note, currently `auto_run` is defined inside the `meta` property; this
may change in the future.
```yaml title="YAML" theme={null}
views:
- name: orders_view
cubes:
- join_path: orders
includes: "*"
meta:
auto_run: false
```
```javascript title="JavaScript" theme={null}
view(`orders_view`, {
cubes: [
{
join_path: orders,
includes: `*`
}
],
meta: {
auto_run: false
}
});
```
The setting only provides the default for the view. Data consumers can toggle
auto-run on or off in each workbook tab, and their choice takes precedence
over the view's default. When `auto_run` is not set, auto-run is on.
#### `default_ui_filters`
In the Cube cloud platform, you can use the `default_ui_filters` key in a
view's `meta` to define default filters for [workbooks][ref-workbook-filtering]
and views embedded via the React Embed SDK. When the view is selected, these
filters are pre-populated as regular, fully editable filters — data consumers
can change their values, switch operators, or remove them entirely.
Each entry has a `member` (a dimension or measure exposed by the view), an
`operator`, and a list of `values` — or a single `value`, which is natural for
single-value operators. Null-check operators take no value.
Please note, currently default UI filters are defined inside the `meta`
property; this may change in the future.
```yaml title="YAML" theme={null}
views:
- name: orders_view
cubes:
- join_path: orders
includes: "*"
meta:
default_ui_filters:
# "is yesterday" → equality at day grain, shows yesterday's data
- member: created_at
operator: is
value: yesterday
# Rolling window → use "between" with two bounds
- member: updated_at
operator: between
values: ["7 days ago", "today"]
- member: status
operator: is
values: ["completed", "shipped"]
```
```javascript title="JavaScript" theme={null}
view(`orders_view`, {
cubes: [
{
join_path: orders,
includes: `*`
}
],
meta: {
default_ui_filters: [
// "is yesterday" → equality at day grain, shows yesterday's data
{
member: `created_at`,
operator: `is`,
value: `yesterday`
},
// Rolling window → use "between" with two bounds
{
member: `updated_at`,
operator: `between`,
values: [`7 days ago`, `today`]
},
{
member: `status`,
operator: `is`,
values: [`completed`, `shipped`]
}
]
}
});
```
##### Operators
Operators use the same labels data consumers see in the workbook filter bar —
what you see in the filter bar is what you type: `is`, `is not`, `after date`,
`after or on date`, `before date`, `before or on date`, `between`, `contains`,
`not contains`, `starts with`, `not starts with`, `ends with`, `not ends with`,
`is null`, `is not null`.
Operators are case-insensitive and whitespace-tolerant. Internal type names and
REST API aliases (e.g. `equals`, `gte`, `inDateRange`) are also accepted.
On a date or time member, `is` with a relative value is an **equality** at that
value's grain, not a range — `is yesterday` matches yesterday only (e.g.
`DATE_TRUNC('day', created_at) = CURRENT_DATE - INTERVAL '1 day'`), and
`is this month` matches the current month. For a rolling window, use `between`
with two bounds.
##### Relative date values
A `between` filter always takes an explicit two-element `[start, end]` pair.
Each bound is one of:
* **A relative value**: `today`, `yesterday`,
`N days|weeks|months|quarters|years ago` (e.g. `7 days ago`),
`N ... from now` (e.g. `2 weeks from now`), or
`this week|month|quarter|year`. `now` is accepted as an alias for `today`.
* **A fixed ISO date**: `"2026-01-15"`, meaning that whole day.
* **A number**, for numeric members.
Relative values also work with `is` and the open-ended comparison operators —
for example, `after date` with `value: 7 days ago`.
Relative bounds resolve when a query runs, not when the filter is seeded:
`["7 days ago", "today"]` produces SQL based on the current date (e.g.
`BETWEEN CURRENT_DATE - INTERVAL '7 days' AND CURRENT_DATE`), so the window
rolls forward day over day. Both bounds are inclusive — `["7 days ago",
"today"]` covers 8 calendar days for daily data. In the workbook, the seeded
filter opens the date editor on the **Relative** tab showing its bounds.
Values are case- and whitespace-insensitive. Entries are validated: an
unrecognized operator or value, or a `between` filter without exactly two
bounds, drops that filter entry with a browser-console warning — the remaining
entries still apply, and view selection never breaks.
Unlike [`default_filters`](#default_filters), which are enforced on every query
against the view, `default_ui_filters` only provide a starting point for the
workbook UI: they don't apply to queries made through APIs or other
visualization tools, and workbook users can freely modify or remove them.
They also only apply to new queries — defining or changing them in the data
model does not add them to existing queries.
### `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.
```yaml title="YAML" theme={null}
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
```
```javascript title="JavaScript" theme={null}
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`
]
}
]
})
```
#### `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, [hierarchies][ref-ref-hierarchies], 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.
A view defines its own surface, so included members don't inherit the
[`public`][ref-dim-public] flag from the underlying cube: a member that is
`public: false` on the cube becomes queryable through the view. Use `excludes`
to keep such members out of the view.
#### `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](#alias) to specify a custom prefix.
#### `alias`
If you'd like to [rename][ref-dim-name] an included member, you can use the `alias`
parameter.
#### `title`
If you'd like to override the [title][ref-dim-title] of a member, you can use the
`title` parameter.
#### `description`
If you'd like to override the [description][ref-dim-description] of a member, you
can use the `description` parameter.
#### `format`
If you'd like to override the [format][ref-dim-format] of a member, you can use the
`format` parameter.
#### `meta`
If you'd like to override the [metadata][ref-dim-meta] 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.
Folders display is subject to support in [visualization tools][ref-viz-tools].
Check [APIs & Integrations][ref-apis-support] for details.
You can also preview folders in [Playground][ref-playground].
Each folder should specify a human-readable name via the `name` parameter and list
included members via the `includes` parameter:
```yaml title="YAML" theme={null}
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
```
```javascript title="JavaScript" theme={null}
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`
]
}
]
})
```
You can also use the `join_path` parameter within `includes` to add all members from a
specific [join path](#join_path) without listing them individually. You can mix
`join_path` with individual member names in the same folder:
```yaml title="YAML" theme={null}
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
```
```javascript title="JavaScript" theme={null}
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`
]
}
]
})
```
#### Nesting
Nested folders are also supported. The `includes` parameter can contain not only
references to view members but also other folders:
```yaml title="YAML" theme={null}
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
```
```javascript title="JavaScript" theme={null}
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`
]
}
]
}
]
})
```
You can still define nested folders in the data model even if some of your [visualization
tools][ref-viz-tools] do not support them. Check [APIs & Integrations][ref-apis-support]
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 [`CUBEJS_NESTED_FOLDERS_DELIMITER`](/reference/configuration/environment-variables#cubejs_nested_folders_delimiter) environment variable to preserve
nested folders and give them path-like names, e.g., `Customer Information / Personal
Details`.
### `default_filters`
The `default_filters` parameter is used to define default filters on a view.
These filters are applied to every query against the view, narrowing down the
result set to a specific subset of data without requiring data consumers to
specify the filter explicitly.
Default filters are useful for governance scenarios where a view should
always be scoped to a particular value (e.g., a tenant, region, or currency).
To provide sensible defaults that data consumers can edit or remove in the UI,
use [`meta.default_ui_filters`](#default_ui_filters) instead.
`default_filters` are enforced on every query against the view, including
filter suggestions.
```yaml title="YAML" theme={null}
views:
- name: orders_us
cubes:
- join_path: orders
includes: "*"
default_filters:
- member: country
operator: equals
values:
- US
```
```javascript title="JavaScript" theme={null}
view(`orders_us`, {
cubes: [
{
join_path: orders,
includes: `*`
}
],
defaultFilters: [
{
member: `country`,
operator: `equals`,
values: [`US`]
}
]
});
```
Each default filter accepts the following parameters:
#### `member`
The name of the dimension to filter on. The member must be exposed by the view.
#### `operator`
The filter operator. Supported operators match the ones available in the
[REST API query format][ref-rest-query-ops]: `equals`, `notEquals`, `contains`,
`notContains`, `startsWith`, `notStartsWith`, `endsWith`, `notEndsWith`, `in`,
`notIn`, `gt`, `gte`, `lt`, `lte`, `set`, `notSet`, `inDateRange`,
`notInDateRange`, `onTheDate`, `beforeDate`, `beforeOrOnDate`, `afterDate`,
`afterOrOnDate`.
#### `values`
A list of values for the filter operator. Required for all operators except
`set` and `notSet`.
#### `unless`
The `unless` parameter optionally lists members that, when referenced in a
query (either in the projection or in an explicit filter), will cause the
default filter to be released. This allows consumers to override the
default filter by querying or filtering by one of the listed members.
If `unless` is not specified, the filter is always applied.
```yaml title="YAML" theme={null}
views:
- name: orders_default_us
cubes:
- join_path: orders
includes: "*"
default_filters:
- member: country
operator: equals
values:
- US
unless:
- country
```
```javascript title="JavaScript" theme={null}
view(`orders_default_us`, {
cubes: [
{
join_path: orders,
includes: `*`
}
],
defaultFilters: [
{
member: `country`,
operator: `equals`,
values: [`US`],
unless: [`country`]
}
]
});
```
In the example above, the `country = US` filter is applied by default. However,
if a query explicitly filters on `country` (e.g., `country = FR`), the default
filter is released and the explicit filter is used instead.
### `access_policy`
The `access_policy` parameter is used to configure [access policies][ref-ref-dap].
[ref-ai-context]: /docs/data-modeling/ai-context
[ref-recipe-control-access-cubes-views]: /docs/data-modeling/access-control
[ref-naming]: /docs/data-modeling/concepts/syntax#naming
[ref-apis]: /reference
[ref-ref-cubes]: /reference/data-modeling/cube
[ref-ref-hierarchies]: /reference/data-modeling/hierarchies
[ref-ref-dap]: /reference/data-modeling/data-access-policies
[ref-rest-query-ops]: /reference/core-data-apis/rest-api/query-format#filters-operators
[ref-apis-support]: /reference#data-modeling
[ref-playground]: /docs/explore-analyze/playground#viewing-the-data-model
[ref-viz-tools]: /admin/connect-to-data/visualization-tools
[ref-workbook-filtering]: /docs/explore-analyze/workbooks/querying-data#filtering
[ref-workbook-running]: /docs/explore-analyze/workbooks/querying-data#running-queries
[ref-extension]: /docs/data-modeling/extending-cubes
[ref-dim-name]: /reference/data-modeling/dimensions#name
[ref-dim-public]: /reference/data-modeling/dimensions#public
[ref-dim-title]: /reference/data-modeling/dimensions#title
[ref-dim-description]: /reference/data-modeling/dimensions#description
[ref-dim-format]: /reference/data-modeling/dimensions#format
[ref-dim-meta]: /reference/data-modeling/dimensions#meta