---
name: metabase_fix_null_ratio
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def metabase_fix_null_ratio(client: MetabaseClient, *, dry_run: bool = True, card_ids: list[int] | None = None) -> dict"
description: "Detecta y repara el patron vulnerable SUM(a-b)/SUM(b) en cards MBQL de Metabase. Cuando una resta pre-agg tiene operandos con NULL, SUM(A-B)!=SUM(A)-SUM(B). El fix reescribe las referencias post-agg al slot diferencia para usar (SUM(A)-SUM(B)) en su lugar. Soporta dry_run para escanear sin modificar."
tags: [metabase, maintenance, batch, mbql, fix, null, ratio, aggregation, python]
uses_functions: [metabase_list_cards_py_infra]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [copy, time, uuid, httpx]
params:
  - name: client
    desc: "instancia autenticada de MetabaseClient con acceso a GET /api/card y PUT /api/card/:id"
  - name: dry_run
    desc: "si True (default) solo escanea y reporta sin modificar ninguna card; si False aplica el fix via PUT"
  - name: card_ids
    desc: "lista de IDs especificos a procesar; None = todas las cards MBQL activas no archivadas"
output: "dict con scanned (cards MBQL evaluadas), affected (cards con el patron detectado), fixed (cards modificadas, 0 en dry_run), errors (lista de {card_id, error} para fallos en PUT)"
tested: false
tests: []
test_file_path: ""
file_path: "python/functions/metabase/maintenance.py"
---

## Ejemplo

```python
from metabase import MetabaseClient, metabase_fix_null_ratio

c = MetabaseClient("https://metabase.example.com", "mb_apikey")

# Escanear sin modificar
report = metabase_fix_null_ratio(c, dry_run=True)
print(report)
# {'scanned': 312, 'affected': 4, 'fixed': 0, 'errors': []}

# Aplicar solo a cards especificas
report = metabase_fix_null_ratio(c, dry_run=False, card_ids=[101, 205, 307])
print(report)
# {'scanned': 3, 'affected': 2, 'fixed': 2, 'errors': []}
```

## Notas

El patron vulnerable ocurre en cards MBQL con esta estructura:
- expressions: `["-", meta, ["field", m, "campo_a"], ["field", m, "campo_b"]]` con nombre `Diferencia_X`
- aggregation: `["sum", meta, ["expression", m, "Diferencia_X"]]` → slot `sum_N`
- aggregation: `["sum", meta, ["field", m, "campo_a"]]` → slot `sum_A`
- aggregation: `["sum", meta, ["field", m, "campo_b"]]` → slot `sum_B`

El fix reemplaza referencias a `sum_N` en stages posteriores por `(sum_A - sum_B)`.
Las restas pre-agg originales (definiciones en expressions[]) no se tocan.

Solo procesa cards con `dataset_query.type == "query"` y stages MBQL.
Las cards SQL nativas se omiten silenciosamente. Rate-limit: 50ms entre PUTs.