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

# Core Concepts: Organizations, Metered Entities, and Variables

> Learn how Data Hub organizes data — from organizations and metered entities down to individual variables and visualizations.

Before exploring your data, it helps to understand how Data Hub structures it. This page walks through the core building blocks — what each one is, how it relates to the others, and why it matters for everyday use.

## The Data Flow at a Glance

```text theme={null}
Organization → Metered Entity → Variable → Visualization / Dashboard
```

An **organization** is the account that owns the data — a college, a city, or another institution. Inside an organization, a **metered entity** represents a building or asset. Each metered entity has one or more **variables**, the individual metrics being measured, fed by a **data source** such as a datalogger or public API. Variables are explored through **visualizations** and can be pinned to a metered entity's **default dashboard**.

***

## Organizations

An organization is the top-level container for a set of buildings and their data. Most users belong to a single organization, but some — like researchers working across institutions — have access to more than one, and can switch between them from a dropdown in the top navigation. Switching organizations updates the Home section to show that organization's buildings and variables.

Access to an organization is invite-only: an **Admin** — typically the person or entity responsible for the organization's account — invites other users to view and work with its data.

***

## Metered Entities

A metered entity is a building or asset that Data Hub collects data for — for example, a campus building or a water treatment plant. Each metered entity has its own metadata:

| Field             | Description                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| Total Area        | Size of the building, in square feet                                                                |
| Average Occupancy | Typical number of occupants                                                                         |
| Address           | Physical location                                                                                   |
| Type              | The kind of entity (for example, Building)                                                          |
| Resource Types    | The kinds of resources tracked — water, electricity, and so on                                      |
| Tags              | Labels used to group entities in search and filters                                                 |
| Default Dashboard | The dashboard shown first when viewing this entity                                                  |
| Default Variables | The variables representing total usage per resource, shown in default dashboards and visualizations |

Metered entities can be viewed as a **List** (a detailed table) or as **Tiles** (a simplified card view), toggled from the top of the Metered Entities page.

***

## Variables

A variable is an individual data point tracked for a metered entity — electricity use, water consumption, precipitation, and so on. Each variable has:

* A **type** — Instantaneous, Totalizer, or Average Rate
* A **data source** — the integration or datalogger providing the readings
* A **status** — Enabled (actively recording), Disabled (not recording), or Historical (deprecated, but has past data)
* A **data reception** state — Online (receiving data normally) or Offline (no data for more than 12 hours)

Variables can be viewed in **Table** or **Graph** format, with up to 5 variables selected for simultaneous comparison. Data can be viewed at different resolutions (source, minute, hour, day, week, month, year) and exported as CSV for offline analysis.

<Note>
  Every variable also has a **Details** view showing its formula (if it's a derived/calculated variable), any variables it depends on, and metadata like the last recorded value and units.
</Note>

***

## Data Sources

A data source is the external system feeding data into a variable — a datalogger (Obvius, JACE, BuildingOS), a sensor platform (Motion), a public API (AirNow, OpenWeatherMap, GLOS), or a generic CSV upload. See [Connecting Data Sources](/guides/connecting-sources) for setup details on each.

***

## Visualizations

Visualizations turn variable data into charts for analysis and comparison. They fall into two categories:

**Trend Analysis** — tracks one or more variables over time:

* Single Point Line / Bar Trend Analysis (one variable)
* Multi Point Line / Bar Trend Analysis (multiple variables)
* Heatmap Analysis (data intensity across time or other dimensions)

**Comparison** — compares variables or entities side by side:

* Bar Chart Comparison
* Portfolio Comparison (proportional, hierarchical view)

Visualizations can be filtered by geographic region, organization, building type, specific metered entity, and resource type, and can reference **Typical Usage** or a **Previous Period** for context.

***

## External Data Access

Beyond the Data Visualizer and dashboards, Data Hub provides two additional, complementary ways to access variable data directly:

* **The Data API** — low-latency, read-only, programmatic access for applications and automated workflows, authenticated with a personal access **token**. See the [API Reference](/api-reference/introduction).
* **The Data Downloader** — a UI-driven bulk export tool for larger datasets, submitted as asynchronous jobs rather than generated instantly. It has no public API of its own. See [Share & Export](/guides/sharing-exporting#data-downloader).

Both expose the same **variable** as the primary object — not the underlying sensor or data source — and both require the same registered, authenticated user account used to log into Data Hub. Access to a given organization's variables is governed by the same permissions already granted to that account; neither mechanism introduces a separate permission model.

<Note>
  The Data API's confirmed design (base URL, authentication, endpoints, rate limits) is documented in the API Reference. The Data Downloader's interface hasn't been built yet — see its section on the Share & Export page for what's confirmed versus still in design.
</Note>

***

## Roles

Data Hub uses two roles today:

* **Admin** — associated with the entity responsible for the organization's account. Admins invite and manage users.
* **User** — someone using the system without being the billed party (for example, a student doing coursework). Users are invited by an Admin.

<Note>
  Data Hub's access model is invite-only — there is currently no public self-serve signup for joining an existing organization. More granular, custom permission sets are on the roadmap but not yet available.
</Note>

***

## Logs

Every metered entity and variable has a **Logs** tab — an audit trail of changes and activity, including user-added notes, timestamps, and a description of what changed. Logs can be filtered by date and browsed chronologically using the Newest / Newer / Older / Oldest navigation controls.