# nvidia-merlin/nvtabular architecture

> Architecture diagram of the GitHub repository nvidia-merlin/nvtabular, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia-merlin/nvtabular
- Repository: https://github.com/nvidia-merlin/nvtabular

## Overview

##### NVTabular’s Project Type and Purpose
- It’s an open-source, GPU-accelerated feature engineering and preprocessing library for tabular data, designed to scale to terabyte-size datasets.
- It integrates with RAPIDS Dask-cuDF for distributed GPU computation and with downstream deep-learning frameworks (TensorFlow, PyTorch, HugeCTR) as well as Triton Inference Server.

##### File Structure
- Top-level Python package: `nvtabular/` contains core modules:
– `ops/` (feature transformation operators)
– `workflow/` (graph, node, workflow builder)
– `loader/` & `io.py` (data ingestion, backend abstraction)
– `framework_utils/` (TensorFlow & PyTorch integration layers)
– `inference/` (runtime C++ bindings)
– `dispatch.py`, `utils.py`, `worker.py` (runtime orchestration)
- C++ inference library: `cpp/nvtabular/inference`
- Benchmarks and examples to illustrate usage (but not part of core runtime)
- CI, Docker, conda recipe, docs & tests imply production readiness and containerized deployment.

##### README for Additional Insights
- NVTabular rests on a layered architecture:
– High-level API → Workflow graph → Execution engine (Dask + cuDF) → GPU/CPU
– Integrations: Merlin Models, HugeCTR, Triton for inference
– Data sources: Parquet, CSV, TFRecords, cloud storage (S3)
- Emphasis on handling datasets beyond single-GPU/CPU memory via Dask.

##### Main Components
a. User Layer
- Jupyter notebooks / Python scripts (e.g., examples/01-Getting-started.ipynb)
- Calling NVTabular high-level API (nvtabular.workflow and transforms)
b. NVTabular Core
- Workflow Builder
– Graph & Node abstractions (`nvtabular.workflow`)
– Chaining Ops (`nvtabular.ops`)
- Data Loader & IO
– Backend-agnostic loaders (`nvtabular.loader`)
– Parquet / TFRecords readers
- Execution Orchestrator (`worker.py`, Dask scheduler client)
- Framework Utilities
– TensorFlow: feature columns & layers
– PyTorch: embeddings & models
- Inference Module
– C++ library for runtime transforms (`cpp/nvtabular/inference`)
– Triton Server integration
c. Execution Engine
- Dask Scheduler & Worker processes
- RAPIDS cuDF on GPU (or CPU fallback)
- Task graph executed across cluster nodes
d. Data Layer
- External storage systems: S3, HDFS, local disk
- Input formats: Parquet, CSV, TFRecords
e. Downstream Integrations
- Deep Learning frameworks: TensorFlow, PyTorch, HugeCTR
- Triton Inference Server for runtime preprocessing
f. Infrastructure & Deployment
- Docker / Conda environments (see conda/ and Dockerfiles)
- CI/CD pipelines (.github/workflows, .gitlab-ci.yml)

##### Relationships & Data Flow
1. User code constructs a Workflow Graph using NVTabular’s Python API.
2. Graph is submitted to Dask Scheduler via NVTabular’s worker client.
3. Dask Workers fetch input data from storage (S3, HDFS), load via cuDF or CPU, apply Ops in parallel on GPUs.
4. Transformed data is written back to Parquet (or TFRecords) for model training.
5. Downstream training: data fed into TensorFlow/PyTorch/HugeCTR pipelines via framework_utils layers.
6. At inference time, the same Ops graph is serialized and loaded by Triton server using the C++ inference module.

##### Architectural Patterns & Principles
- Layered modular design: API → Graph → Execution → Storage
- Dataflow (DAG) pattern via `nvtabular.workflow`
- Backend abstraction for loaders, execution (CPU vs GPU)
- Integration facade for ML frameworks
- Reusability: same Ops for training and inference

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% User Layer
  subgraph "User Layer" 
    direction TB
    NB1["01-Getting-started.ipynb"]:::user
    NB2["02-Advanced-NVTabular-workflow.ipynb"]:::user
    NB3["03-Running-on-multiple-GPUs-or-on-CPU.ipynb"]:::user
    BENCH["dask-nvtabular-criteo-benchmark.py"]:::user
  end

  %% NVTabular Core
  subgraph "NVTabular Core" 
    direction TB
    subgraph "Workflow Builder" 
      direction TB
      GRAPH["graph.py"]:::core
      NODE["workflow/node.py"]:::core
      WF["workflow/workflow.py"]:::core
      WF_INIT["workflow/__init__.py"]:::core
    end
    subgraph "Feature Transformation Operators" 
      direction TB
      OPS["nvtabular/ops/"]:::core
      OPS_INIT["ops/__init__.py"]:::core
      OP_BASE["operator.py"]:::core
    end
    subgraph "Data Loader & IO" 
      direction TB
      IO["io.py"]:::core
      LOADER_INIT["loader/__init__.py"]:::core
    end
    subgraph "Execution Orchestrator" 
      direction TB
      DISPATCH["dispatch.py"]:::core
      WORKER["worker.py"]:::core
    end
    subgraph "Framework Utilities" 
      direction TB
      FU["framework_utils/"]:::core
    end
    subgraph "Inference Module" 
      direction TB
      INF_PY["inference/__init__.py"]:::core
      INF_CPP["cpp/nvtabular/inference/"]:::core
    end
  end

  %% Execution Engine
  subgraph "Execution Engine" 
    direction TB
    SCHED["Dask Scheduler"]:::exec
    WORKERS["Dask Workers"]:::exec
    CUDF["RAPIDS cuDF (GPU/CPU)"]:::exec
  end

  %% Data Layer
  subgraph "Data Layer" 
    direction TB
    S3["S3 / HDFS / Local"]:::storage
    FORMATS["Parquet / CSV / TFRecords"]:::storage
  end

  %% Downstream Integrations
  subgraph "Integrations" 
    direction TB
    TF["TensorFlow"]:::integ
    PT["PyTorch"]:::integ
    HCTR["HugeCTR"]:::integ
    TRITON["Triton Inference Server"]:::integ
  end

  %% Deployment & CI/CD
  subgraph "Infrastructure & Deployment" 
    direction TB
    CONDA["conda/"]:::deploy
    CI[".github/workflows/ & .gitlab-ci.yml"]:::deploy
    DOCKER["Dockerfiles"]:::deploy
  end

  %% Connections
  NB1 -->|"uses API"| GRAPH
  NB2 -->|"uses API"| GRAPH
  NB3 -->|"uses API"| GRAPH
  BENCH -->|"uses API"| GRAPH

  GRAPH -->|"builds DAG"| OPS
  GRAPH -->|"builds DAG"| IO

  OPS --> DISPATCH
  IO --> DISPATCH
  DISPATCH --> SCHED
  SCHED --> WORKERS
  WORKERS --> CUDF
  WORKERS -->|"read/write"| S3
  WORKERS --> FORMATS

  CUDF -->|"transformed data"| FORMATS
  FORMATS --> TF
  FORMATS --> PT
  FORMATS --> HCTR

  INF_PY --> INF_CPP
  TRITON --> INF_CPP
  WORKERS --> INF_CPP

  CONDA --> DISPATCH
  DOCKER --> DISPATCH
  CI --> DISPATCH

  %% Click Events
  click NB1 "https://github.com/nvidia-merlin/nvtabular/blob/main/examples/01-Getting-started.ipynb"
  click NB2 "https://github.com/nvidia-merlin/nvtabular/blob/main/examples/02-Advanced-NVTabular-workflow.ipynb"
  click NB3 "https://github.com/nvidia-merlin/nvtabular/blob/main/examples/03-Running-on-multiple-GPUs-or-on-CPU.ipynb"
  click BENCH "https://github.com/nvidia-merlin/nvtabular/blob/main/bench/examples/dask-nvtabular-criteo-benchmark.py"
  click GRAPH "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/graph.py"
  click NODE "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/workflow/node.py"
  click WF "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/workflow/workflow.py"
  click WF_INIT "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/workflow/__init__.py"
  click OPS "https://github.com/nvidia-merlin/nvtabular/tree/main/nvtabular/ops/"
  click OPS_INIT "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/ops/__init__.py"
  click OP_BASE "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/ops/operator.py"
  click IO "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/io.py"
  click LOADER_INIT "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/loader/__init__.py"
  click DISPATCH "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/dispatch.py"
  click WORKER "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/worker.py"
  click FU "https://github.com/nvidia-merlin/nvtabular/tree/main/nvtabular/framework_utils/"
  click INF_PY "https://github.com/nvidia-merlin/nvtabular/blob/main/nvtabular/inference/__init__.py"
  click INF_CPP "https://github.com/nvidia-merlin/nvtabular/tree/main/cpp/nvtabular/inference/"
  click CONDA "https://github.com/nvidia-merlin/nvtabular/tree/main/conda/"
  click CI "https://github.com/nvidia-merlin/nvtabular/tree/main/.github/workflows/"
  click DOCKER "https://github.com/nvidia-merlin/nvtabular/blob/main/.dockerignore"

  %% Styles
  classDef user fill:#e0f7fa,stroke:#0288d1,color:#000
  classDef core fill:#e8f5e9,stroke:#2e7d32,color:#000
  classDef exec fill:#fff3e0,stroke:#ef6c00,color:#000
  classDef storage fill:#eceff1,stroke:#90a4ae,color:#000
  classDef integ fill:#f3e5f5,stroke:#8e24aa,color:#000
  classDef deploy fill:#fbe9e7,stroke:#d84315,color:#000
```
