You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Cuando la CLI no es suficiente — porque necesitas integrar Teckel en una aplicación existente, controlar el ciclo de vida del SparkSession, o componer pipelines con otra lógica — usas el módulo `teckel-api` directamente desde Scala.
4
-
5
-
El API está construido sobre Cats Effect y ofrece tres entry points con distintos niveles de abstracción. Elige el que mejor encaje con tu estilo de código.
6
-
7
3
## Entry Points
8
4
9
-
### `etl[F, O]` — Fully polymorphic
5
+
Three entry points are available, differing in effect abstraction and execution model.
6
+
7
+
### `etl[F, O]`
10
8
11
-
El entry point más genérico. Parametrizado sobre el efecto `F[_]`y el tipo de resultado `O`. Útil si ya tienes un stack de efectos definido y quieres integrar Teckel sin fijar `IO`.
9
+
Generic, parameterized over effect type `F[_]`and result type `O`.
12
10
13
11
```scala
14
12
importcom.eff3ct.teckel.api._
15
13
importcats.effect.IO
16
14
17
-
valyaml:String=
18
-
"""
19
-
|input:
20
-
| - name: source
21
-
| format: csv
22
-
| path: 'data/input.csv'
23
-
| options:
24
-
| header: true
25
-
|output:
26
-
| - name: source
27
-
| format: parquet
28
-
| mode: overwrite
29
-
| path: 'data/output'
30
-
""".stripMargin
31
-
32
-
// F = IO, O = Unit → ejecuta el pipeline y escribe el output
33
-
// Requiere SparkSession implícito y EvalContext[Unit] en scope
15
+
// F = IO, O = Unit → execute mode (writes output files)
16
+
// Requires implicit SparkSession and EvalContext[Unit] in scope
34
17
valprogram:IO[Unit] = etl[IO, Unit](yaml)
35
18
```
36
19
37
-
### `etlIO[O]` — Fija F = IO
20
+
### `etlIO[O]`
38
21
39
-
El más habitual cuando trabajas con Cats Effect. Fija `F = IO` para no tener que especificarlo:
22
+
Fixes `F = IO`.
40
23
41
24
```scala
42
25
importcom.eff3ct.teckel.api._
43
-
importcats.effect.IO
44
-
45
-
valyaml:String="..."// contenido YAML
46
26
47
27
valprogram:IO[Unit] = etlIO[Unit](yaml)
48
28
```
49
29
50
-
### `unsafeETL[O]` — Síncrono y bloqueante
30
+
### `unsafeETL[O]`
51
31
52
-
Ejecuta el pipeline de forma síncrona. Sin efectos, sin IO. Conveniente para scripts, jobs batch simples, o tests donde no quieres gestionar runtime de Cats Effect:
32
+
Synchronous, blocking. Convenient for scripts and tests.
53
33
54
34
```scala
55
35
importcom.eff3ct.teckel.api._
56
36
57
-
valyaml:String="..."// contenido YAML
58
-
59
-
unsafeETL[Unit](yaml) // bloquea hasta completar
37
+
unsafeETL[Unit](yaml) // blocks until completion
60
38
```
61
39
62
-
## Modos de evaluación
40
+
## Evaluation Modes
63
41
64
-
El tipo `O`que pasas a cualquiera de los entry points determina qué hace Teckel con el pipeline. Hay dos contextos de evaluación disponibles.
42
+
The type parameter `O`determines what Teckel does with the pipeline.
65
43
66
44
### Execute (`O = Unit`)
67
45
68
-
El modo por defecto. Ejecuta el DAG completo y escribe los outputs a sus destinos. Es el comportamiento que esperarías de un job ETL normal.
46
+
Runs the full DAG and writes outputs.
69
47
70
48
```scala
71
-
importcom.eff3ct.teckel.api._
72
-
73
-
unsafeETL[Unit](yaml) // ejecuta y escribe
49
+
unsafeETL[Unit](yaml)
74
50
```
75
51
76
52
### Debug (`O = Context[DataFrame]`)
77
53
78
-
En lugar de escribir los outputs, devuelve todos los DataFrames intermedios como un `Map[String, DataFrame]`. Extremadamente útil para testing y depuración — puedes inspeccionar el estado del pipeline en cada paso sin tocar el almacenamiento.
54
+
Returns all intermediate DataFrames without writing to storage. Useful for testing.
// Todos los assets del pipeline están disponibles por nombre
88
-
assets.foreach { case (name, df) =>
89
-
println(s"\n=== $name ===")
90
-
df.show(10)
91
-
df.printSchema()
92
-
}
93
-
94
-
// O accede a uno específico
95
-
valactiveUsers:DataFrame= assets("active_users")
63
+
assets("active_users").show()
96
64
```
97
65
98
-
Este modo es especialmente valioso en tests de integración: puedes verificar el resultado de transformaciones intermedias sin necesitar un sistema de ficheros real.
99
-
100
-
## Inspección sin Spark
66
+
## Inspect Without Spark
101
67
102
-
Estas utilidades analizan el YAML y generan información sobre el pipeline sin necesitar un SparkSession — son puramente funcionales y muy rápidas.
68
+
These utilities parse and analyze the pipeline without a `SparkSession`.
103
69
104
70
### Dry Run
105
71
106
-
Genera el plan de ejecución en texto: qué pasos se van a ejecutar, en qué orden y con qué configuración. También valida las referencias entre assets.
Convierte el pipeline en documentación Markdown. Describe todas las fuentes, transformaciones y destinos con sus parámetros. Útil para mantener la documentación sincronizada con el pipeline real.
83
+
### Doc Generation
122
84
123
85
```scala mdoc:compile-only
124
86
importcom.eff3ct.teckel.api.DocGen
125
87
126
-
valyaml:String="..."//contenido YAML
88
+
valyaml:String="..."// YAML content
127
89
128
-
DocGen.generate(yaml).foreach(println)
90
+
DocGen.generate(yaml).foreach(s =>println(s))
129
91
```
130
92
131
-
### GraphViz
132
-
133
-
Genera una representación gráfica del DAG. Soporta tres formatos: `mermaid` (el más habitual para GitHub/Notion), `dot` (para Graphviz) y `ascii` (para terminales).
93
+
### DAG Visualization
134
94
135
95
```scala mdoc:compile-only
136
96
importcom.eff3ct.teckel.api.GraphViz
137
97
138
-
valyaml:String="..."// contenido YAML
139
-
140
-
// Mermaid — se puede pegar directamente en GitHub o Notion
La CLI de Teckel es la forma más directa de usar el framework: construyes el uber JAR, apuntas a tu pipeline YAML y listo. No hace falta escribir ni una línea de Scala.
4
-
5
-
## Construir el JAR
6
-
7
-
El artefacto CLI incluye Spark empaquetado, así que no necesitas tener Spark instalado por separado:
Teckel tiene varias herramientas para entender lo que va a pasar antes de lanzar el job de Spark. Son especialmente útiles en CI, en revisiones de código, o simplemente cuando estás depurando un pipeline nuevo.
20
+
## Dry Run
39
21
40
-
### Dry-run
41
-
42
-
Analiza el pipeline, valida las referencias cruzadas entre assets y muestra el plan de ejecución paso a paso. No instancia ningún SparkSession — es completamente ligero:
22
+
Validates references and prints the execution plan. Does not start Spark.
La salida por defecto es un diagrama Mermaid, que puedes pegar directamente en GitHub, Notion o cualquier herramienta que lo soporte.
44
+
## Environment Variables
69
45
70
-
## Variables de entorno
71
-
72
-
Los valores en el YAML pueden referenciar variables de entorno usando la sintaxis `${VARIABLE}`. Esto permite tener un pipeline genérico y parametrizarlo en tiempo de ejecución:
46
+
Reference environment variables in YAML using `${VAR}` syntax:
73
47
74
48
```yaml
75
49
input:
@@ -78,38 +52,22 @@ input:
78
52
path: '${INPUT_PATH}'
79
53
options:
80
54
header: true
81
-
82
-
output:
83
-
- name: source
84
-
format: parquet
85
-
mode: overwrite
86
-
path: '${OUTPUT_PATH}'
87
55
```
88
56
89
-
Pasa las variables como variables de entorno al lanzar el JAR:
Para casos donde quieres exponer tus pipelines como un servicio HTTP — integración con orquestadores, plataformas de datos, o simplemente para invocarlo desde otras herramientas — Teckel incluye un servidor embebido sin dependencias adicionales:
0 commit comments