# Marquez CLI Utilities

Utilidades en Go para gestionar **datasets**, **jobs** y **runs** con lineage tracking completo en Marquez (OpenLineage).

---

## 📦 ¿Qué se Creó?

### 1. **Binario `marquez-cli`** (Go)

Herramienta CLI completa para interactuar con Marquez:

- ✅ Registrar y consultar **datasets**
- ✅ Registrar y consultar **jobs**
- ✅ Enviar eventos de **runs** (START, RUNNING, COMPLETE, FAIL)
- ✅ Consultar **lineage** de datasets
- ✅ Listar recursos (namespaces, jobs, datasets)
- ✅ Sin dependencias externas (solo Go stdlib)
- ✅ Binario estático de ~5MB

**Ubicación**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/`

**Instalación**:
```bash
cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
make install
```

**Uso**:
```bash
marquez-cli help
marquez-cli version
```

---

### 2. **Scripts de Ejemplo**

#### a) `simple_pipeline_with_lineage.sh`

Pipeline simple que demuestra:
- Generación de Run ID
- Eventos START, RUNNING, COMPLETE
- Tracking de transformaciones
- Manejo de errores

**Ubicación**: `~/dagu/scripts/examples/simple_pipeline_with_lineage.sh`

**Uso**:
```bash
~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
```

#### b) `etl_to_postgres_with_lineage.sh`

ETL completo con carga a PostgreSQL:
- Extract desde API
- Transform con jq
- Load a PostgreSQL
- Lineage completo del flujo

**Ubicación**: `~/dagu/scripts/examples/etl_to_postgres_with_lineage.sh`

**Uso**:
```bash
~/dagu/scripts/examples/etl_to_postgres_with_lineage.sh
```

---

### 3. **DAG de Ejemplo para Dagu**

DAG completo con lineage tracking integrado:
- Generación de Run ID único
- Eventos en cada paso del pipeline
- Handler de errores (FAIL event)
- Handler de éxito
- Cleanup de archivos temporales

**Ubicación**: `~/dagu/dags/example_lineage_tracking.yaml`

**Uso**:
```bash
# Ejecutar manualmente desde Dagu UI
http://localhost:8090

# O desde CLI
dagu start example_lineage_tracking
```

---

## 🎯 Conceptos Clave de Marquez

### Datasets

Representan **fuentes de datos** (tablas, archivos, APIs, streams).

**Naming Convention**:
```
postgres://host:port/db/schema/table
clickhouse://host:port/database/table
nats://host:port/subject
file:///absolute/path
api://domain/endpoint
```

**Comandos**:
```bash
# Registrar dataset
marquez-cli dataset register -name "postgres://localhost:5434/postgres/public/events"

# Listar datasets
marquez-cli list datasets
```

---

### Jobs

Representan **procesos/pipelines** que leen/escriben datasets.

**Naming Convention**:
- Usa nombres descriptivos: `fetch_api_data`, `transform_sales`
- Evita guiones, usa guiones bajos
- Mismo nombre que el DAG en Dagu

**Comandos**:
```bash
# Registrar job
marquez-cli job register -name my_pipeline

# Listar jobs
marquez-cli list jobs

# Ver runs de un job
marquez-cli job runs -name my_pipeline
```

---

### Runs

Representan **ejecuciones** de un job con inputs/outputs específicos.

**Lifecycle**:
1. **START** - Inicio de ejecución
2. **RUNNING** - Progreso (opcional, múltiples)
3. **COMPLETE** o **FAIL** - Finalización

**Comandos**:
```bash
RUN_ID=$(uuidgen)

# START
marquez-cli run start -job my_job -run-id $RUN_ID

# RUNNING (progreso intermedio)
marquez-cli run running -job my_job -run-id $RUN_ID \
  -inputs "file:///tmp/raw.json" \
  -outputs "file:///tmp/clean.json"

# COMPLETE
marquez-cli run complete -job my_job -run-id $RUN_ID \
  -outputs "postgres://table"

# FAIL (en caso de error)
marquez-cli run fail -job my_job -run-id $RUN_ID
```

---

## 📋 Reglas de Lineage

### ✅ SIEMPRE debes:

1. **Enviar evento START** al inicio del pipeline
2. **Usar el mismo Run ID** en todos los eventos del mismo run
3. **Declarar TODOS los inputs** (APIs, archivos, tablas que lees)
4. **Declarar TODOS los outputs** (archivos, streams, tablas que escribes)
5. **Enviar evento COMPLETE** al finalizar exitosamente
6. **Enviar evento FAIL** si hay errores (usar trap/handler)
7. **Usar URIs bien formados** para datasets
8. **Usar namespace consistente** (`automatic-process`)

### ❌ NUNCA debes:

1. Omitir el evento START
2. Olvidar el evento COMPLETE/FAIL
3. Cambiar el Run ID en medio del pipeline
4. Usar nombres ambiguos para datasets
5. Saltarte el lineage en pipelines críticos

---

## 🔍 Recuperar Lineage

### Método 1: CLI

```bash
# Ver lineage de un dataset
marquez-cli lineage -name "postgres://localhost:5434/postgres/public/events"

# Formato JSON (para scripts)
marquez-cli lineage -name "postgres://table" -format json

# Con más profundidad
marquez-cli lineage -name "postgres://table" -depth 20
```

### Método 2: Web UI

```bash
# Abrir Marquez Web UI
xdg-open http://localhost:3001

# Buscar por job o dataset
# Ver grafo visual de lineage
```

### Método 3: API REST

```bash
# Ver lineage directo desde API
curl "http://localhost:5000/api/v1/lineage?nodeId=dataset:automatic-process:postgres://table&depth=10" | jq .

# Listar jobs
curl http://localhost:5000/api/v1/namespaces/automatic-process/jobs | jq .

# Ver runs de un job
curl http://localhost:5000/api/v1/namespaces/automatic-process/jobs/my_job/runs | jq .
```

---

## 🚀 Quick Start

### 1. Instalar marquez-cli

```bash
cd ~/AutomaticProyects/automatic_process/tools/marquez-cli
make install
marquez-cli version
```

### 2. Probar con Ejemplo

```bash
# Ejecutar pipeline de ejemplo
~/dagu/scripts/examples/simple_pipeline_with_lineage.sh

# Ver lineage generado
marquez-cli lineage -name "file:///tmp/users_clean.json"
```

### 3. Crear tu Primer Pipeline

```bash
#!/bin/bash
set -euo pipefail

JOB_NAME="my_first_pipeline"
RUN_ID=$(uuidgen)

# Manejo de errores
cleanup() {
  marquez-cli run fail -job $JOB_NAME -run-id $RUN_ID
}
trap cleanup ERR

# START
marquez-cli run start -job $JOB_NAME -run-id $RUN_ID

# Tu trabajo aquí
echo "Doing work..."
curl https://api.example.com/data > /tmp/data.json

# COMPLETE
marquez-cli run complete \
  -job $JOB_NAME \
  -run-id $RUN_ID \
  -inputs "api://example.com/data" \
  -outputs "file:///tmp/data.json"

echo "✓ Pipeline completed!"
```

---

## 📊 Estructura de Archivos

```
~/AutomaticProyects/automatic_process/
├── tools/
│   └── marquez-cli/           # Código fuente del CLI
│       ├── main.go            # CLI principal
│       ├── openlineage.go     # Cliente API
│       ├── go.mod             # Módulo Go
│       ├── Makefile           # Build automation
│       ├── README.md          # Documentación completa
│       ├── QUICKSTART.md      # Guía rápida
│       └── marquez-cli        # Binario compilado
│
├── MARQUEZ_UTILITIES.md       # Este archivo
│
~/dagu/
├── scripts/
│   └── examples/
│       ├── simple_pipeline_with_lineage.sh
│       └── etl_to_postgres_with_lineage.sh
│
└── dags/
    └── example_lineage_tracking.yaml
```

---

## 🔧 Comandos Útiles

### Gestión de Runs

```bash
# Iniciar run con inputs/outputs
marquez-cli run start -job my_job -inputs "api://source" -outputs "file:///tmp/data"

# Marcar progreso
marquez-cli run running -job my_job -run-id <uuid> -inputs "file:///a" -outputs "file:///b"

# Completar exitosamente
marquez-cli run complete -job my_job -run-id <uuid> -outputs "postgres://table"

# Marcar como fallido
marquez-cli run fail -job my_job -run-id <uuid>
```

### Consultas

```bash
# Ver todos los jobs
marquez-cli list jobs

# Ver runs de un job
marquez-cli job runs -name my_job

# Ver lineage completo
marquez-cli lineage -name "postgres://localhost:5434/postgres/public/events"

# Ver datasets
marquez-cli list datasets
```

---

## 📚 Documentación Adicional

- **README Completo**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/README.md`
- **Quick Start**: `~/AutomaticProyects/automatic_process/tools/marquez-cli/QUICKSTART.md`
- **CLAUDE.md**: Guía de servicios manipulables
- **OpenLineage Spec**: https://openlineage.io/
- **Marquez Docs**: https://marquezproject.ai/

---

## 🎯 Próximos Pasos

1. **Ejecuta el ejemplo**:
   ```bash
   ~/dagu/scripts/examples/simple_pipeline_with_lineage.sh
   ```

2. **Verifica el lineage**:
   ```bash
   marquez-cli lineage -name "file:///tmp/users_clean.json"
   ```

3. **Adapta el patrón** a tus propios pipelines

4. **Siempre sigue las reglas** de lineage tracking

---

## 💡 Tips

- **Usa variables de entorno** para configuración:
  ```bash
  export MARQUEZ_URL="http://localhost:5000"
  export MARQUEZ_NAMESPACE="automatic-process"
  ```

- **Genera Run ID una sola vez** y reutilízalo en todo el pipeline:
  ```bash
  RUN_ID=$(uuidgen)
  ```

- **Usa trap para manejar errores** automáticamente:
  ```bash
  trap 'marquez-cli run fail -job $JOB_NAME -run-id $RUN_ID' ERR
  ```

- **Verifica lineage después** de cada ejecución:
  ```bash
  marquez-cli lineage -name "postgres://table"
  ```

---

**Última actualización**: 2026-03-23
**Versión**: 1.0.0
**Autor**: Lucas (@egutierrez)