data_drain 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 036367c9d2512c4a9a2785bbef6efeaaf9ee013ee31c013e1527001f91f22d65
-  data.tar.gz: c7dc050b51c3024ad9e2e62ae57e28bb549fee9a0341aea5ee524d4b55a07da5
+  metadata.gz: 918cc35413b6b09496ce15c782b6334dea8d515d9972bcf6a00a1e052140db67
+  data.tar.gz: 62a8278a7d7d4ba064b5bc4c33b63b846745d59c58a2cb77806dc8dc3ba677a5
 SHA512:
-  metadata.gz: 9ed7fb071a8d1f0c103c44c402279b9b575b535944a21db6f260b5d2aa4da2675f56095a9d79d1054c8e4c48ac578a955673befde82a84ca030ee508adf11e8e
-  data.tar.gz: f4c3665f97d5f4c287f70a715bd4fc36264bae977f868bb5f062bade177527cb6bfb10dbaf6c83fb6280ab2fce4787bf8abc1789fa9fb5893ac99f3a0a2b1ee0
+  metadata.gz: c9fecbd5cfdf411b6032ca39bed25e4a12a518d246a3591d84c524e4d2950b5045c0dcb20a1de471600a3b37145d3f6c05b4f5a14c86103a1109fd25f05ba494
+  data.tar.gz: 7c1c6c951e880e2d512599aa90fea56f80fffca0315ab4fba7fc179c4e305c5a27e5ef8af0608459650598c051b945d56790b38e279320ee49db1e1897dd077b

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-16
+
+### Features
+
+- Nueva opción `purge_where_clause` en `Engine#initialize`. Permite especificar una condición SQL independiente para el DELETE, distinta de `where_clause` (que aplica a export/verify). Caso de uso: archivar subset (`isp_id IS NOT NULL`) pero purgar superset (todo el rango). Valores: `nil` = no purge, `""` = purge todo el rango, `"x"` = rango AND x. Backwards compatible vía `fetch(:purge_where_clause, @where_clause)`. Fixes #3.
+
+### Refactor
+
+- Extraído helper `date_range_sql` en Engine para eliminar duplicación entre `base_where_sql` y `purge_where_sql`.
+
+### YARD
+
+- Documentación actualizada en `Engine#initialize` para los tres casos de `purge_where_clause`.
+- `Engine#build_delete_sql` ahora documenta retorno `String|nil`.
+
+### Telemetry
+
+- Nuevo evento `engine.purge_skipped` cuando no hay cláusula de purge (`delete_sql.nil?`).
+
+### Tests
+
+- 5 nuevos tests para `purge_where_clause`: backwards compatible, empty string purge all, integrity usa base_where_sql, independiente de where_clause, y use case primario (archive subset / purge superset).
+
+## [0.5.2] - 2026-04-16
+
+### Correcciones
+
+- `Record#where()` ahora usa wildcards (`key=*`) para partition keys no especificadas, en lugar de valores vacíos (`key=`). Consistente con `destroy_partitions`. Fixes #1.
+
 ## [0.5.1] - 2026-04-15
 
 ### Docs

data/README.md

@@ -1,6 +1,6 @@
 # DataDrain
 
-[![CI](https://github.com/gedera/data_drain/actions/workflows/main.yml/badge.svg)](https://github.com/gedera/data_drain/actions/workflows/main.yml)
+[![CI](https://github.com/sequre/data_drain/actions/workflows/main.yml/badge.svg)](https://github.com/sequre/data_drain/actions/workflows/main.yml)
 
 Micro-framework Ruby para extraer, archivar y purgar datos históricos de PostgreSQL hacia un Data Lake (S3 o disco local) en formato Parquet, usando DuckDB en memoria.
 
@@ -18,7 +18,7 @@ Micro-framework Ruby para extraer, archivar y purgar datos históricos de Postgr
 
 ```ruby
 # Gemfile
-gem 'data_drain', git: 'https://github.com/gedera/data_drain.git', branch: 'main'
+gem 'data_drain', git: 'https://github.com/sequre/data_drain.git', branch: 'main'
 ```
 
 ```bash
@@ -104,6 +104,26 @@ DataDrain::Engine.new(
 ).call
 ```
 
+### Purge subset vs archive superset
+
+Caso común: archivar filas válidas (`isp_id IS NOT NULL`) pero borrar superset (válidas + trash).
+
+```ruby
+# Archiva solo isp_id NOT NULL, verifica integridad solo sobre esos,
+# pero purga TODO el mes (NULL + NOT NULL) con batching/throttling/vacuum
+DataDrain::Engine.new(
+  bucket:             'my-bucket-store',
+  start_date:         6.months.ago.beginning_of_month,
+  end_date:           6.months.ago.end_of_month,
+  table_name:         'versions',
+  partition_keys:     %w[year month],
+  where_clause:       'isp_id IS NOT NULL',  # filtra qué se archiva
+  purge_where_clause: ''                       # purge TODO el mes (vacío = sin filtro adicional)
+).call
+```
+
+**Resultado:** Export/verify cuentan y comparan solo `isp_id NOT NULL`. Purge borra el mes completo con batching, throttling y vacuum del `purge_loop`.
+
 ### Orquestación con AWS Glue (tablas 1TB+)
 
 ```ruby

data/data_drain.gemspec

@@ -11,7 +11,7 @@ Gem::Specification.new do |spec|
   spec.summary = "Micro-framework para drenar datos de PostgreSQL a Parquet vía DuckDB."
   spec.description = "Extrae datos transaccionales, los archiva en un Data Lake (S3/Local) " \
                      "en formato Parquet usando Hive Partitioning, y purga el origen de forma segura."
-  spec.homepage = "https://github.com/gedera/data_drain"
+  spec.homepage = "https://github.com/sequre/data_drain"
   spec.required_ruby_version = ">= 3.2"
 
   spec.files = Dir.chdir(__dir__) do

data/lib/data_drain/engine.rb

@@ -21,7 +21,16 @@ module DataDrain
     # @option options [String] :select_sql (Opcional) Sentencia SELECT personalizada.
     # @option options [Array<String, Symbol>] :partition_keys Columnas para particionar.
     # @option options [String] :primary_key (Opcional) Clave primaria para borrado. Por defecto 'id'.
-    # @option options [String] :where_clause (Opcional) Condición SQL extra.
+    # @option options [String] :where_clause (Opcional) Condición SQL extra
+    #   que filtra export, count e integrity check. Define "qué se archiva".
+    # @option options [String] :purge_where_clause (Opcional) Condición SQL
+    #   para el DELETE. Si se omite, usa :where_clause (backwards compatible).
+    #   Pasar nil explícito para desactivar purga. Pasar '' (vacío) para purgar
+    #   todo el rango de fechas sin filtro adicional (útil para archivar subset
+    #   y borrar superset).
+    #   Puede ser más amplia que :where_clause; filas que matchean
+    #   :purge_where_clause pero no :where_clause se borran sin archivar ni
+    #   verificar. Útil para limpieza de orphans/trash que no debe respaldarse.
     # @option options [Boolean] :skip_export (Opcional) Si true, no exporta
     #   a Parquet — solo valida y purga (para uso con GlueRunner).
     def initialize(options)
@@ -38,6 +47,7 @@ module DataDrain
       @primary_key = options.fetch(:primary_key, "id")
       Validations.validate_identifier!(:primary_key, @primary_key)
       @where_clause = options[:where_clause]
+      @purge_where_clause = options.fetch(:purge_where_clause, @where_clause)
       @bucket = options[:bucket]
       @skip_export = options.fetch(:skip_export, false)
 
@@ -140,11 +150,27 @@ module DataDrain
     # @api private
     # @return [String]
     def base_where_sql
-      sql = "created_at >= '#{@start_date.to_fs(:db)}' AND created_at < '#{@end_date.to_fs(:db)}'"
+      sql = date_range_sql
       sql += " AND #{@where_clause}" if @where_clause && !@where_clause.empty?
       sql
     end
 
+    # @api private
+    # @return [String]
+    def purge_where_sql
+      return nil if @purge_where_clause.nil?
+
+      sql = date_range_sql
+      sql += " AND #{@purge_where_clause}" unless @purge_where_clause.empty?
+      sql
+    end
+
+    # @api private
+    # @return [String]
+    def date_range_sql
+      "created_at >= '#{@start_date.to_fs(:db)}' AND created_at < '#{@end_date.to_fs(:db)}'"
+    end
+
     # @api private
     def setup_duckdb
       @duckdb.query("INSTALL postgres; LOAD postgres;")
@@ -289,13 +315,19 @@ module DataDrain
     # @param conn [PG::Connection]
     # @return [Integer] total de filas borradas
     def purge_loop(conn)
+      delete_sql = build_delete_sql
+      if delete_sql.nil?
+        safe_log(:info, "engine.purge_skipped", { table: @table_name, reason: "no_purge_clause" })
+        return 0
+      end
+
       batches_processed = 0
       total_deleted = 0
       slow_batch_streak = 0
 
       loop do
         batch_start = monotonic
-        result = conn.exec(build_delete_sql)
+        result = conn.exec(delete_sql)
         batch_duration = monotonic - batch_start
         count = result.cmd_tuples
         break if count.zero?
@@ -349,12 +381,16 @@ module DataDrain
     end
 
     # @api private
+    # @return [String, nil] SQL DELETE statement or nil if no purge clause
     def build_delete_sql
+      where = purge_where_sql
+      return nil if where.nil?
+
       <<~SQL
         DELETE FROM #{@table_name}
         WHERE #{@primary_key} IN (
           SELECT #{@primary_key} FROM #{@table_name}
-          WHERE #{base_where_sql}
+          WHERE #{where}
           LIMIT #{@config.batch_size}
         )
       SQL

data/lib/data_drain/record.rb

@@ -131,7 +131,10 @@ module DataDrain
       # @param partitions [Hash]
       # @return [String]
       def build_query_path(partitions)
-        partition_path = partition_keys.map { |k| "#{k}=#{partitions[k.to_sym] || partitions[k.to_s]}" }.join("/")
+        partition_path = partition_keys.map do |k|
+          val = partitions.key?(k.to_sym) ? partitions[k.to_sym] : partitions[k.to_s]
+          val.nil? || val.to_s.empty? ? "#{k}=*" : "#{k}=#{val}"
+        end.join("/")
         DataDrain::Storage.adapter.build_path(bucket, folder_name, partition_path)
       end
 

data/lib/data_drain/version.rb

@@ -2,5 +2,5 @@
 
 module DataDrain
   # @return [String] versión semver de la gema
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/skill/SKILL.md

@@ -14,6 +14,7 @@ Skill de conocimiento completo sobre DataDrain. Consultame para cualquier pregun
 - **Hive Partitioning** — Estructura de carpetas `key1=val1/key2=val2/...` que DuckDB genera y consume nativamente para prefix scans eficientes.
 - **Semi-abierto** — Convención de rangos `[start, end)` con `<` (no `<=`) para evitar pérdida de microsegundos en límites de fecha.
 - **skip_export** — Modo del Engine donde delega export a herramienta externa (Glue/EMR) y solo verifica + purga.
+- **purge_where_clause** — Condición SQL independiente para el DELETE. Permite archivar subset y purgar superset. nil = skip, "" = purge todo el rango, "x" = rango AND x.
 - **ensure_job** — Wrapper idempotente de GlueRunner que crea o actualiza un job según config deseada. Incluye diffing de configuración para evitar API calls innecesarios.
 - **changed_fields** — Helper privado de ensure_job que compara config deseada vs actual de un Glue Job y retorna qué campos difieren.
 - **Heartbeat** — Log de progreso emitido cada 100 lotes en purgas masivas (tablas 1TB).
@@ -70,7 +71,7 @@ DataDrain resuelve el ciclo de vida de datos históricos en bases relacionales c
 
 - Ruby `>= 3.2.0`
 - Runtime: `activemodel >= 6.0`, `duckdb ~> 1.4`, `pg >= 1.2`, `aws-sdk-s3 ~> 1.114`, `aws-sdk-glue ~> 1.0`
-- Versión actual: `0.5.1`
+- Versión actual: `0.6.0`
 
 ## API Pública (resumen)
 
@@ -98,12 +99,22 @@ DataDrain::Engine.new(
   bucket:, start_date:, end_date:, table_name:,
   partition_keys: %w[isp_id year month],
   primary_key: "id",            # opcional
-  where_clause: nil,             # opcional, SQL extra
+  where_clause: nil,             # opcional, SQL extra para export/verify
+  purge_where_clause: nil,       # opcional, SQL para DELETE (nil=skip, ""=full range, "x"=range+x)
   skip_export: false,            # true delega export a Glue
   folder_name: nil,              # default = table_name
   select_sql: "*"                # default
 ).call  # => true (ok) | false (integrity fail)
 
+# Purge subset vs archive superset (v0.6.0+)
+DataDrain::Engine.new(
+  bucket:, start_date:, end_date:, table_name:,
+  partition_keys: %w[year month],
+  where_clause: "isp_id IS NOT NULL",  # filtra qué se archiva
+  purge_where_clause: ""               # purge TODO el rango (vacío = sin filtro adicional)
+).call
+# Resultado: export/verify sobre isp_id NOT NULL, purge sobre todo el rango
+
 # 2. Ingesta de archivos crudos
 DataDrain::FileIngestor.new(
   bucket:, source_path:, folder_name:,
@@ -271,7 +282,7 @@ Catálogo completo en [Antipatrones](references/antipatrones.md). Resumen de los
 ## Referencias
 
 - [API Detallada](references/api-detallada.md) — Firmas completas, parámetros, retornos y comportamientos de cada clase pública.
-- [Glue Jobs Lifecycle](https://github.com/gedera/data_drain/blob/main/docs/glue-jobs-lifecycle.md) — Guía completa de gestión de AWS Glue Jobs: crear, actualizar, eliminar, verificar y ejecutar jobs idempotentemente.
+- [Glue Jobs Lifecycle](https://github.com/sequre/data_drain/blob/main/docs/glue-jobs-lifecycle.md) — Guía completa de gestión de AWS Glue Jobs: crear, actualizar, eliminar, verificar y ejecutar jobs idempotentemente.
 - [Eventos y Telemetría](references/eventos-telemetria.md) — Catálogo completo de eventos KV emitidos por la gema.
 - [Antipatrones](references/antipatrones.md) — Qué NO hacer y alternativas correctas.
 - [Postgres Tuning](references/postgres-tuning.md) — Índices, VACUUM, particionamiento y diagnóstico por tamaño de tabla.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-15 00:00:00.000000000 Z
+date: 2026-04-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -133,7 +133,7 @@ files:
 - skill/references/api-detallada.md
 - skill/references/eventos-telemetria.md
 - skill/references/postgres-tuning.md
-homepage: https://github.com/gedera/data_drain
+homepage: https://github.com/sequre/data_drain
 licenses: []
 metadata: {}
 post_install_message: