> ## Documentation Index
> Fetch the complete documentation index at: https://docs.explo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Hierarchy

> Facilitate a hierarchical structure with parent-child relationships among your customers.

## Feature Motivation

We at Explo have observed that our clients frequently have a natural parent-child hierarchy among their customer entities that they wish to depict in the Explo Customers tab.
For instance, a client may have customers that are sports leagues, with each league comprising various teams, and each team having multiple players.
This scenario presents a natural three-tier hierarchy: `League`, `Team`, and `Player`. Similarly, many of our clients work with companies that have individual users,
resulting in a natural two-tier hierarchy of `Customer` and `User`. Explo can accommodate up to three layers of any desired hierarchy.

## Configurable Dashboard Sections and Customer Hierarchy

In most scenarios, we anticipate that customers will employ a two-tier `Customer` and `User` hierarchy when activating Configurable Dashboard Sections.
This is primarily because you may want the dashboards to have data populated from the `Customer` level, but have special state saved for each entity at the `User` level.
For instance, if you want Alice and Bob, users within Generic Company, to have their own individually configured dashboards, you must designate Generic Company as the parent customer and
Alice and Bob as the children. Subsequently, in your dashboard queries, you should reference the variables from the Customer level. When embedding, it should be done at
the User level so Alice and Bob can have their own unique views.

## Filtering on the Frontend by Hierarchy Level

On the frontend interface, selecting a customer will filter the customer page accordingly.

<img src="https://mintlify.s3.us-west-1.amazonaws.com/explo/images/hierarchy.gif" alt="" />

You can set the hierarchy level and any parent-child relationships on this customer page as well.

## Feature Functionality

The customer hierarchy feature currently provides two key functionalities:

1. Referencing any ancestor customer entity in a query by utilizing the inherited archetype variables. You can read more about those [here](/creating-dashboards/variables/types-of-variables/customer-object#archetype-variables).
2. Automatically inheriting properties from the parent. For example, in a three-tier hierarchy of sports leagues, if the `conference` property is assigned as `Eastern` at the top level,
   each child and grandchild ('Team' and 'Player') could reference `properties.conference`, which would yield `Eastern` for each level of the hierarchy.

## Example Usage in Queries

The following examples will show how you can control which level in the hierarchy provides the data in your queries.
Understanding customer-specific variables is a prerequesite for writing these types of queries, and you can read more about those [here](/creating-dashboards/variables/types-of-variables/customer-object).

Let's say we have some customer entities with the following setup:

| Name         | Provided Id   | Hierarchy Level | Parent Provided ID | Available Archetype Variables                                                                                                         |
| ------------ | ------------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| NBA          | nba           | League          | None               | `league_id: nba`, `league_name: NBA`                                                                                                  |
| Lakers       | lakers        | Team            | NBA                | `league_id: nba`, `league_name: NBA`, `team_id: lakers` , `team_name: Lakers`                                                         |
| LeBron James | lebron\_james | Player          | lakers             | `league_id: nba`, `league_name: NBA`, `team_id: lakers` , `team_name: Lakers`, `player_id: lebron_james`, `player_name: LeBron James` |
| Rockets      | rockets       | Team            | NBA                | `league_id: nba`, `league_name: NBA`, `team_id: rockets` , `team_name: Rockets`                                                       |
| Jalen Green  | jalen\_green  | Player          | rockets            | `league_id: nba`, `league_name: NBA`, `team_id: rockets` , `team_name: Rockets`, `player_id: jalen_green`, `player_name: Jalen Green` |

If we wanted to show league-level data,

```sql theme={null}
SELECT *
FROM Table_1
WHERE 1=1
[[AND league_column = {{ league_id }}]]
```

For the query above, if you viewed an Explo dashboard as any of the customer entities in the table,
you'd be able to see all of the NBA data since all of the listed customer entities have NBA as an ancestor.

If we wanted to show team-level data,

```sql theme={null}
SELECT *
FROM Table_1
WHERE 1=1
[[AND league_column = {{ league_id }}]]
[[AND team_column = {{ team_id }}]]
```

For the query above, if you viewed an Explo dashboard as `Lakers` you'd be able to see all of the Lakers data. If you
viewed the dashboard as `LeBron James`, you'd also be able to see the all Lakers data because LeBron is a member of the Lakers team.

If we wanted to show player-level data,

```sql theme={null}
SELECT *
FROM Table_1
WHERE 1=1
[[AND league_column = {{ league_id }}]]
[[AND team_column = {{ team_id }}]]
[[AND player_column = {{ player_id }}]]
```

If you viewed the dashboard as `LeBron James`, you'd be able to see all of LeBron's data. If you viewed the
dashboard as `Jalen Green`, you'd only be able to see Jalen's data.

Referencing an inherited property

```sql theme={null}
SELECT *
FROM Table_1
WHERE 1=1
[[AND column = {{properties.inherited_property}}]]
```