Skip to main content

Why We Document Data Models

At Carbon Arc, data is only as useful as it is understandable. Our Data Model pages serve as blueprints — showing how each dataset is structured, how entities relate, and how metrics are derived. These documents clarify the system behind the signal.

Every panel, feed, and insight in Carbon Arc is built on a defined data model. These models include:

  • Field-level definitions
  • Metric transformations
  • Entity relationships
  • Temporal and spatial logic

Without clear documentation, users are left guessing how the data was shaped — leading to misinterpretation, model errors, or duplicated logic across teams.

We treat our data model pages as part of our product surface. They support:

  • Transparency: Users should understand exactly what each field means and how it’s calculated
  • Reproducibility: Analysts can recreate metrics and logic independently
  • Alignment: Data scientists, engineers, and business users operate off a shared source of truth
  • Governance: Field and table definitions stay consistent over time and versions

What You’ll Find in Each Page​

A well-structured data model page includes:

  • Schema diagrams or tables with field names, types, and descriptions
  • Derived metric logic for fields that aren’t raw
  • Entity links to brands, companies, products, locations
  • Temporal logic to explain how data is windowed, rolled up, or time-shifted
  • Version notes for breaking changes or structural shifts

When to Use It​

  • Before joining two tables and needing to understand key relationships
  • When defining KPIs and ensuring consistent metric logic
  • While debugging a data discrepancy
  • During onboarding or cross-team collaboration

Why It Matters​

Documentation is not overhead — it’s leverage.

Carbon Arc users rely on these pages to build scalable analysis, compare across datasets, and maintain interpretability as logic evolves. A well-documented data model accelerates decision-making and reduces risk.

Summary​

Data Model pages are more than reference material — they are operational blueprints. By treating models as user-facing components, we equip teams to explore, analyze, and act on Carbon Arc data with confidence and clarity.