data_drain 0.1.18 → 0.1.19

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09d58bbf9060fa6fb61ddeff5e43f020168280d9487726912c25deda6b1a2a45'
-  data.tar.gz: e8d13997382a5b9c69031406450ff579f01afe9593b1b9edee28546944b9faee
+  metadata.gz: c3b2ce171059217fbb96cf1d1f93e9bce121b31e0afdf73eaa3889d5dca38d5c
+  data.tar.gz: 14600532ba59fd8daf0ec7e1890175211402172d643481539980da8f54799f9b
 SHA512:
-  metadata.gz: de7135c83eb0d5cbdc018cf965d974ccc449ae9c74166868914b4f73e5c775ea9bc39c80bee0ada779b7cafeb313c4cdde7b20b454cfab7b415d9cb7e25ff815
-  data.tar.gz: de65115bbb65cfe1ef4ae035c2c7c644027109fb485e2b0e9e17b079b15595ad2ce015ffd4771432551e314ac7bd42cedb014f907cbd690d669d9a7166a79625
+  metadata.gz: d08d3a7391a2b1ec4ab4b5e9c6f3d894bd5a8d1f46cc1d93f4324559f7a92e9a4150e689f3ca990afecdf33817cbfd3259f9c6bd7162040742ad2fdda3ae3661
+  data.tar.gz: 863f1be6a3e391fe32c63b88a2d944443159d984fbf74f598dba58cbc44ffd8c4a5dc14cafcede6182c620d8b8580f9bec2225d298e75c50215766a87b56cb4a

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.1.19] - 2026-03-30
+
+- Fix: `Record.build_query_path` ahora usa `partition_keys` como fuente de verdad del orden, ignorando el orden de los kwargs del caller. Antes, pasar `where(year: 2026, isp_id: 42)` en distinto orden generaba un path que no coincidía con la estructura Hive en disco.
+- Fix: `GlueRunner` reemplaza `.truncate(200)` de ActiveSupport por `[0, 200]` de Ruby puro, eliminando la dependencia implícita.
+- Convention: orden canónico de `partition_keys` es `[dimension_principal, year, month]` (ej. `isp_id` primero). Documentado en CLAUDE.md y actualizado en README, specs y ejemplos de PySpark.
+- Docs: README actualizado con ejemplos de producción correctos para Glue + Engine + Record.
+
 ## [0.1.18] - 2026-03-23
 
 - Feature: Módulo `Observability` centraliza el logging estructurado en toda la gema.

data/CLAUDE.md

@@ -19,6 +19,24 @@ created_at >= 'START' AND created_at < 'END_BOUNDARY'
 ```
 Donde `END_BOUNDARY` es el inicio del periodo siguiente (ej. `next_day.beginning_of_day`). Nunca usar `<= end_of_day` — los microsegundos en el límite pueden quedar fuera.
 
+### Partition Keys — Orden y Contrato
+
+El array `partition_keys` es **completamente dinámico** — cada tabla/modelo define el suyo. No existe un orden estándar en la librería.
+
+**Regla crítica:** el orden de `partition_keys` al **escribir** (Engine/FileIngestor) debe ser idéntico al declarado en el modelo **Record** que lee esos archivos. Un mismatch genera paths que no coinciden y DuckDB retorna vacío sin error.
+
+```ruby
+# Escritura
+Engine.new(partition_keys: %w[isp_id year month], ...)
+
+# Lectura — debe coincidir
+class ArchivedVersion < DataDrain::Record
+  self.partition_keys = [:isp_id, :year, :month]
+end
+```
+
+**Criterio de diseño del orden:** el primer key debe ser la dimensión de mayor cardinalidad o la que más se usa como filtro (ej. `isp_id` si las consultas son siempre por ISP). Esto determina la jerarquía de carpetas Hive y el rendimiento del prefix scan en S3.
+
 ### Idempotencia
 Las exportaciones usan `OVERWRITE_OR_IGNORE 1` de DuckDB. Los procesos son seguros de reintentar.
 

data/README.md

@@ -84,7 +84,7 @@ ingestor = DataDrain::FileIngestor.new(
   bucket:              'my-bucket-store',
   source_path:         '/tmp/netflow_metrics_1600.csv',
   folder_name:         'netflow',
-  partition_keys:      %w[year month isp_id],
+  partition_keys:      %w[isp_id year month],
   select_sql:          "*, EXTRACT(YEAR FROM timestamp) AS year, EXTRACT(MONTH FROM timestamp) AS month",
   delete_after_upload: true
 )
@@ -148,7 +148,7 @@ DataDrain::GlueRunner.run_and_wait(
     "--db_user"      => config.db_user,
     "--db_password"  => config.db_pass,
     "--db_table"     => table,
-    "--partition_by" => "year,month,isp_id"
+    "--partition_by" => "isp_id,year,month"
   }
 )
 
@@ -159,7 +159,7 @@ DataDrain::Engine.new(
   start_date:     start_date,
   end_date:       end_date,
   table_name:     table,
-  partition_keys: %w[year month isp_id],
+  partition_keys: %w[isp_id year month],
   skip_export:    true
 ).call
 ```
@@ -197,6 +197,9 @@ options = {
 
 df = spark.read.format("jdbc").options(**options).load()
 
+# Agregar columnas derivadas necesarias para las particiones.
+# isp_id ya existe en la tabla fuente — solo agregar las que se calculan.
+# Personalizar esta sección según las partition_keys de cada tabla.
 df_final = df.withColumn("year", year(col("created_at"))) \
              .withColumn("month", month(col("created_at")))
 
@@ -221,7 +224,7 @@ Para consultar los datos archivados sin salir de Ruby, crea un modelo que herede
 class ArchivedVersion < DataDrain::Record
   self.bucket       = 'my-bucket-storage'
   self.folder_name  = 'versions'
-  self.partition_keys = [:year, :month, :isp_id]
+  self.partition_keys = [:isp_id, :year, :month]
 
   attribute :id,             :string
   attribute :item_type,      :string
@@ -238,11 +241,11 @@ Consultas optimizadas mediante Hive Partitioning:
 
 ```ruby
 # Búsqueda puntual aislando la partición exacta
-version = ArchivedVersion.find("un-uuid", year: 2026, month: 3, isp_id: 42)
+version = ArchivedVersion.find("un-uuid", isp_id: 42, year: 2026, month: 3)
 puts version.object_changes # => {"status" => ["active", "suspended"]}
 
 # Colecciones
-history = ArchivedVersion.where(limit: 10, year: 2026, month: 3, isp_id: 42)
+history = ArchivedVersion.where(limit: 10, isp_id: 42, year: 2026, month: 3)
 ```
 
 ### 5. Destrucción de Datos (Retención y Cumplimiento)

data/lib/data_drain/record.rb

@@ -11,7 +11,7 @@ module DataDrain
   # @example
   #   class ArchivedVersion < DataDrain::Record
   #     self.folder_name = 'versions'
-  #     self.partition_keys = [:year, :month, :isp_id]
+  #     self.partition_keys = [:isp_id, :year, :month]
   #     attribute :event, :string
   #   end
   class Record
@@ -110,7 +110,7 @@ module DataDrain
       # @param partitions [Hash]
       # @return [String]
       def build_query_path(partitions)
-        partition_path = partitions.map { |k, v| "#{k}=#{v}" }.join("/")
+        partition_path = partition_keys.map { |k| "#{k}=#{partitions[k.to_sym] || partitions[k.to_s]}" }.join("/")
         DataDrain::Storage.adapter.build_path(bucket, folder_name, partition_path)
       end
 

data/lib/data_drain/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataDrain
-  VERSION = "0.1.18"
+  VERSION = "0.1.19"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.18
+  version: 0.1.19
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-24 00:00:00.000000000 Z
+date: 2026-03-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel