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

# Data model overview

> Technical guide to Nectar API data structures, processing behavior, and entity relationships.

This guide provides API-facing details for developers building integrations. For a user-friendly introduction, see [How your data works](/platform/methodology/overview) in the Knowledge Base.

***

## Entity relationships

Nectar organizes utility data in a hierarchical structure:

```mermaid theme={null}
erDiagram
    Company ||--o{ Site : contains
    Company ||--o{ Connection : has
    Connection ||--o{ Account : discovers
    Site ||--o{ Meter : contains
    Account ||--o{ Meter : owns
    Meter ||--o{ UsageData : records
    Meter }|--|| Commodity : tracks
    Account ||--o{ Document : receives
    Document ||--o{ LineItem : contains
    Document ||--o{ UsageData : generates
```

### Entity definitions

| Entity         | API resource               | Description                                                     |
| -------------- | -------------------------- | --------------------------------------------------------------- |
| **Company**    | `/company`                 | Top-level entity containing sites and connections               |
| **Site**       | `/company/{id}/site`       | Physical address with meters                                    |
| **Connection** | `/company/{id}/connection` | Configured link to a utility provider                           |
| **Account**    | `/company/{id}/account`    | Billing relationship with a utility; discovered via connections |
| **Meter**      | `/company/{id}/meter`      | Measurement point for a single commodity at a site              |
| **Document**   | `/company/{id}/document`   | Processed utility statement                                     |
| **UsageData**  | `/company/{id}/usage`      | Time-series consumption record                                  |
| **LineItem**   | Nested in document         | Individual charge or credit on a document                       |

***

## Data processing behavior

When a document enters Nectar, it moves through an external lifecycle:

```mermaid theme={null}
flowchart LR
    A[Document Input] --> B[Extraction]
    B --> C[Validation]
    C --> D[Structured API Data]
```

Key behaviors:

* Core bill fields, usage data, and line items are extracted from source documents.
* Meter/account/site associations are applied to organize data in the API model.
* Validation checks run before data is published to improve quality and consistency.
* Electricity demand values are included when present in source documents.

***

## Key data fields

### Document

| Field             | Type    | Description                              |
| ----------------- | ------- | ---------------------------------------- |
| `id`              | UUID    | Unique identifier                        |
| `billDate`        | Date    | End date of billing period               |
| `startDate`       | Date    | Start date of billing period             |
| `totalCharges`    | Decimal | Total amount due                         |
| `currentCharges`  | Decimal | New charges this period                  |
| `chargesUnits`    | String  | Currency code (USD, EUR, etc.)           |
| `revisedDocument` | UUID    | Links to superseding document if revised |

### UsageData

| Field             | Type    | Description                   |
| ----------------- | ------- | ----------------------------- |
| `id`              | UUID    | Unique identifier             |
| `startDate`       | Date    | Start of consumption period   |
| `endDate`         | Date    | End of consumption period     |
| `rawUsage`        | Decimal | Usage as reported on bill     |
| `rawUsageUnits`   | String  | Original unit of measure      |
| `standardUsage`   | Decimal | Normalized usage value        |
| `netMeteringType` | Enum    | IMPORT, EXPORT, or GENERATION |

### Meter

| Field            | Type    | Description                              |
| ---------------- | ------- | ---------------------------------------- |
| `id`             | UUID    | Unique identifier                        |
| `datasourceType` | Enum    | Commodity: ELECTRICITY, GAS, WATER, etc. |
| `isTracked`      | Boolean | Whether included in active analytics     |
| `isDuplicated`   | Boolean | Whether marked as duplicate              |
| `tags`           | Array   | Meter tags assigned to this meter        |

***

## Calendarization algorithm

Nectar converts billing period data to calendar months using daily proration:

```python theme={null}
# Simplified algorithm
daily_usage = total_usage / (end_date - start_date + 1)

for month in overlapping_months:
    overlap_start = max(bill_start, month_start)
    overlap_end = min(bill_end, month_end)
    overlap_days = (overlap_end - overlap_start) + 1
    month_usage = daily_usage * overlap_days
```

Key details:

* **Inclusive date counting**: Both start and end dates are included (closed interval)
* **Computed at query time**: Raw data preserved; calendarization applied dynamically
* **Net metering exports**: Export meters multiply by -1 during aggregation

***

## Cost attribution algorithm

For multi-meter bills, charges are allocated proportionally by usage:

```python theme={null}
# For same-commodity charges
meter_share = meter_usage / total_usage
meter_cost = (total_charges - open_balance) * meter_share

# For account-level charges (customer fees, etc.)
meter_cost = charge_amount / meter_count
```

Key details:

* Uses **new charges** (excludes carried balance) to prevent double-counting
* Demand charges allocated specifically to demand meters
* Currency preserved (no automatic conversion)

***

## Annotations and computed fields

Several fields are computed at query time rather than stored:

| Annotation               | Description                                 | Used for                 |
| ------------------------ | ------------------------------------------- | ------------------------ |
| `isArchived`             | `dataCollectionStopDate` is set and in past | Filtering inactive sites |
| `isVisibleByCurrentUser` | User has site permission                    | Permission filtering     |
| `dailyUsage`             | `standardUsage / span_days`                 | Calendarization          |
| `calendarizedUsage`      | `dailyUsage * overlap_days`                 | Monthly aggregation      |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Document processing details" icon="file-magnifying-glass" href="/developer-guide/data-model/parsing">
    Document-processing behavior and expected outputs
  </Card>

  <Card title="Meter organization" icon="gauge" href="/developer-guide/data-model/meter-organization">
    Meter, account, and site relationships
  </Card>
</CardGroup>