dbt-nexus Documentation

A comprehensive dbt package for entity resolution, event tracking, and entity management with advanced state management capabilities.

Welcome to the dbt-nexus package documentation! This package provides a standardized, source-agnostic solution for building unified customer data platforms with powerful entity resolution and state management capabilities.

What is dbt-nexus?

dbt-nexus is a way of structuring all company data in your data warehouse so it's operationally useful, not just good for dashboards. It's designed to help you actually close sales, speed up customer support, and reduce churn.

Specifically, it's a dbt package that lets data engineers quickly merge and organize any data source into a combined view of people, companies, and events - creating a complete timeline of everything you know about your customers.

dbt-nexus helps you:

  • 🔗 Resolve identities across multiple data sources and systems
  • 📊 Track events with standardized event logging that creates actionable timelines
  • 👥 Manage entities including persons, groups, subscriptions, contracts, and their relationships
  • 🏷️ Track state over time with SCD2 state management for dimensions (lifecycle status) and measurements (MRR, contract value)
  • 📈 Efficient time-series queries via precomputed deltas on entity states — no date-spine joins needed
  • ⚡ Scale efficiently with incremental processing and optimized queries
  • 🎯 Drive operations - support teams, sales teams, and AI tools get complete customer context

Quick Start

Get up and running with dbt-nexus in minutes:

# packages.yml
packages:
  - local: path/to/dbt-nexus

dbt deps

→ Follow the complete installation guide

Architecture Overview

Image

Database Schema Diagram

Mermaid

Final Tables

erDiagram
    nexus_events {
        string event_id PK
        timestamp occurred_at
        string event_type
        string event_name
        string source
    }

    nexus_entities {
        string entity_id PK
        string entity_type
        string email "dynamic trait"
        string name "dynamic trait"
        string domain "dynamic trait"
    }

    nexus_relationships {
        string relationship_id PK
        string entity_a_id FK
        string entity_b_id FK
        string relationship_type
        boolean is_active
    }

    nexus_entity_participants {
        string entity_participant_id PK
        string entity_id FK
        string event_id FK
        string entity_type
        string role
    }

    nexus_entity_states {
        string entity_state_id PK
        string entity_id FK
        timestamp valid_from
        timestamp valid_to
        boolean is_current
        string ___ "dynamic dimensions"
        numeric ___ "dynamic measurements"
        numeric ___ "dynamic deltas"
    }

    nexus_event_measurements {
        string event_measurement_id PK
        string event_id FK
        string measurement_name
        numeric value
        string value_unit
    }

    %% Relationships
    nexus_entities ||--o{ nexus_relationships : "entity_a"
    nexus_entities ||--o{ nexus_relationships : "entity_b"
    nexus_entities ||--o{ nexus_entity_participants : "participates in"
    nexus_entities ||--o{ nexus_entity_states : "state timeline"
    nexus_events ||--o{ nexus_entity_participants : "has participants"
    nexus_events ||--o{ nexus_event_measurements : "has measurements"

Full

graph TD
    %% Raw Data Layer
    subgraph RawData["Raw Data"]
        RSD[raw_source_data<br/>• id: string PK<br/>• ...: string]
    end

    %% Source Event Log Layer
    subgraph SourceLog["Source Event Log"]
        SET[source_entity_traits<br/>• id: string PK<br/>• event_id: string FK<br/>• trait_name: string<br/>• trait_value: string]
        SEI[source_entity_identifiers<br/>• id: string PK<br/>• event_id: string FK<br/>• identifier_type: string<br/>• identifier_value: string]
        SE[source_events<br/>• event_id: string PK<br/>• event_name: string<br/>• ...: string]
        SEM[source_event_measurements<br/>• event_id: string FK<br/>• measurement_name: string<br/>• value: numeric]
        SRD[source_relationship_declarations<br/>• event_id: string FK<br/>• entity_a_identifier: string<br/>• entity_b_identifier: string<br/>• relationship_type: string]
    end

    %% Core Event Log Layer
    subgraph CoreLog["Core Event Log"]
        E[nexus_events<br/>• event_id: string PK<br/>• occurred_at: timestamp<br/>• event_type: string<br/>• event_name: string<br/>• source: string]
        EID[nexus_entity_identifiers<br/>• entity_type: string<br/>• identifier_type: string<br/>• identifier_value: string<br/>• event_id: string FK]
        ET[nexus_entity_traits<br/>• entity_type: string<br/>• trait_name: string<br/>• trait_value: string<br/>• event_id: string FK]
        EM[nexus_event_measurements<br/>• event_measurement_id: string PK<br/>• event_id: string FK<br/>• measurement_name: string<br/>• value: numeric]
        RD[nexus_relationship_declarations<br/>• relationship_declaration_id: string PK<br/>• entity_a_identifier: string<br/>• entity_b_identifier: string<br/>• relationship_type: string]
    end

    %% Entity Resolution Layer
    subgraph Identity["Entity Resolution"]
        RPI[resolved_person_identifiers<br/>• person_id: string<br/>• identifier_type: string<br/>• identifier_value: string]
        RGI[resolved_group_identifiers<br/>• group_id: string<br/>• identifier_type: string<br/>• identifier_value: string]
        RET[resolved_entity_traits<br/>• entity_id: string<br/>• trait_name: string<br/>• trait_value: string]
        RRD[resolved_relationship_declarations<br/>• entity_a_id: string<br/>• entity_b_id: string<br/>• relationship_type: string]
    end

    %% Final Tables Layer
    subgraph Final["Final Tables"]
        ENT[nexus_entities<br/>• entity_id: string PK<br/>• entity_type: string<br/>• email: string<br/>• name: string<br/>• domain: string]
        REL[nexus_relationships<br/>• relationship_id: string PK<br/>• entity_a_id: string FK<br/>• entity_b_id: string FK<br/>• relationship_type: string]
        EP[nexus_entity_participants<br/>• entity_participant_id: string PK<br/>• entity_id: string FK<br/>• event_id: string FK<br/>• role: string]
    end

    %% Data Flow Connections
    RSD -->|derives| SET
    RSD -->|derives| SEI
    RSD -->|derives| SE
    RSD -->|derives| SEM
    RSD -->|derives| SRD

    SET -->|unions all sources| ET
    SEI -->|unions all sources| EID
    SE -->|unions all sources| E
    SEM -->|unions all sources| EM
    SRD -->|unions all sources| RD

    E -->|has many| EID
    E -->|has many| ET
    E -->|has many| EM
    E -->|has many| RD

    EID -->|resolves| RPI
    EID -->|resolves| RGI
    ET -->|resolves| RET
    RD -->|resolves| RRD

    RPI -->|materializes| ENT
    RGI -->|materializes| ENT
    RET -->|enriches| ENT
    RRD -->|materializes| REL

    ENT -->|entity_a| REL
    ENT -->|entity_b| REL
    ENT -->|references| EP
    E -->|references| EP

Interactive database schema diagram showing the dbt-nexus data model structure with the five-layer architecture: Raw Data, Source Event Log, Core Event Log, Entity Resolution, and Final Tables.

Note: To view the original diagram, open docs/assets/images/database-diagram.xml in diagrams.net.

Quick Start Guides