> ## 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.

# Hierarchies

> Hierarchies group dimensions into levels of granularity, allowing users to drill down or roll up for analysis.

You can use the `hierarchies` parameter within [cubes][ref-ref-cubes] to define hierarchies.
You can think about a hierarchy as a means to group [dimensions][ref-ref-dimensions] together and organize
them into levels of granularity, allowing users to drill down or roll up for analysis.

<Info>
  Hierarchies display is subject to support in [visualization tools][ref-viz-tools].
  Check [APIs & Integrations][ref-apis-support] for details.
  You can also preview hierarchies in [Playground][ref-playground].
</Info>

Any hierarchy should have the following parameters: [`name`](#name) and [`levels`](#levels).

<Note>
  Just like other members, hierarchies can be exposed to data consumers through
  [views][ref-ref-views]. List them in the `includes` parameter of a view's
  `cubes` block alongside measures, dimensions, and segments.
</Note>

<iframe width="100%" height="400" src="https://www.youtube.com/embed/Y5E6DmH_Hz4" title="YouTube video" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Parameters

### `name`

The `name` parameter serves as the identifier of a hierarchy. It must be unique
among all members within a cube and follow the [naming conventions][ref-naming].

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

### `title`

You can use the `title` parameter to set the human-readable name of a hierarchy:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

### `levels`

The `levels` parameter is used to define the levels of the hierarchy. You can do so
by listing the dimensions included in the hierarchy, from less granular to more
granular ones:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: users
      sql_table: users

      dimensions:
        - name: state
          sql: state
          type: string

        - name: city
          sql: city
          type: string

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`users`, {
    sql_table: `users`,

    dimensions: {
      state: {
        sql: `state`,
        type: `string`
      },

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

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      }
    }
  })
  ```
</CodeGroup>

You can include the same dimension in multiple hierarchies. It is also possible to
include a dimension from a joined cube into a hierarchy:

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: users
      sql_table: users

      joins:
        - name: orders
          sql: "{CUBE.id} = {orders.user_id}"
          relationship: one_to_many

      dimensions:
        - name: state
          sql: state
          type: string

        - name: city
          sql: city
          type: string

        - name: status
          sql: status
          type: string

      hierarchies:
        - name: details
          title: User Details
          levels:
            - status
            - state
            - city

        - name: statuses
          title: User & Order Statuses
          levels:
            - status
            - orders.status
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`users`, {
    sql_table: `users`,

    joins: {
      orders: {
        sql: `${CUBE.id} = ${orders.user_id}`,
        relationship: `one_to_many`
      }
    },

    dimensions: {
      state: {
        sql: `state`,
        type: `string`
      },

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

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

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ]
      },

      statuses: {
        title: `User & Order Statuses`,
        levels: [
          status,
          orders.status
        ]
      }
    }
  })
  ```
</CodeGroup>

### `public`

The `public` parameter is used to manage the visibility of a hierarchy. Valid
values for `public` are `true` and `false`. When set to `false`, this hierarchy
**cannot** be queried through the API. Defaults to `true`.

<CodeGroup>
  ```yaml title="YAML" theme={null}
  cubes:
    - name: users
      sql_table: users

      # ...

      hierarchies:
        - name: location
          title: User Location
          levels:
            - state
            - city
          public: false
  ```

  ```javascript title="JavaScript" theme={null}
  cube(`users`, {
    sql_table: `users`,

    // ...

    hierarchies: {
      location: {
        title: `User Location`,
        levels: [
          state,
          city
        ],
        public: false
      }
    }
  })
  ```
</CodeGroup>

[ref-ref-cubes]: /reference/data-modeling/cube

[ref-ref-dimensions]: /reference/data-modeling/dimensions

[ref-ref-views]: /reference/data-modeling/view

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

[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