---
name: diff_entities
kind: function
lang: py
domain: datascience
version: "1.0.0"
purity: pure
signature: "def diff_entities(before: list[dict], after: list[dict], key: str = 'id', ignore_fields: list[str] | None = None, compare_fields: list[str] | None = None) -> dict"
description: "Compara dos snapshots de entities y devuelve diferencias campo a campo. Detecta añadidas, eliminadas, modificadas e inalteradas. Ignora created_at y updated_at por defecto."
tags: [diff, entities, snapshot, operations, comparison, datascience, pendiente-usar]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: ""
imports: []
params:
  - name: before
    desc: "lista de dicts con entities antes de cambios (ej: [{'id': '1', 'name': 'Alice', 'status': 'active'}, ...])"
  - name: after
    desc: "lista de dicts con entities despues de cambios, misma estructura que before"
  - name: key
    desc: "nombre del campo que identifica cada entity (tipico: 'id'). Debe existir en todas las entities."
  - name: ignore_fields
    desc: "lista opcional de campos a ignorar en la comparacion (ej: ['created_at', 'updated_at'])"
  - name: compare_fields
    desc: "lista opcional de campos SOLO a comparar (si se da, tiene prioridad sobre ignore_fields)"
output: "dict con {added, removed, modified, unchanged, summary} describiendo los cambios campo a campo"
tested: true
tests:
  - "entity añadida"
  - "entity eliminada"
  - "entity modificada con detalle de campos"
  - "entities identicas → unchanged"
  - "ignore_fields funciona"
  - "compare_fields filtra correctamente"
  - "lista vacia vs lista con datos"
test_file_path: "python/functions/datascience/diff_entities_test.py"
file_path: "python/functions/datascience/diff_entities.py"
---

## Ejemplo

```python
before = [
    {"id": "1", "name": "Alice", "status": "active", "updated_at": "2024-01-01"},
    {"id": "2", "name": "Bob", "status": "active", "updated_at": "2024-01-01"},
]
after = [
    {"id": "1", "name": "Alice", "status": "inactive", "updated_at": "2024-01-02"},
    {"id": "3", "name": "Carol", "status": "active", "updated_at": "2024-01-02"},
]

result = diff_entities(before, after)
# result["added"]    -> [{"id": "3", "name": "Carol", ...}]
# result["removed"]  -> [{"id": "2", "name": "Bob", ...}]
# result["modified"] -> [{"key": "1", "changes": {"status": {"old": "active", "new": "inactive"}}}]
# result["unchanged"] -> 0
# result["summary"]  -> "1 added, 1 removed, 1 modified, 0 unchanged"
```

## Notas

Funcion pura. No hace I/O — toma listas de dicts ya cargadas en memoria.

El campo `key` debe existir en todas las entities; las que no lo tengan se ignoran silenciosamente.

Si `compare_fields` se da, tiene prioridad sobre `ignore_fields`. Esto permite comparar solo un subconjunto especifico de campos sin preocuparse por los campos temporales.

El orden de `added` y `removed` no esta garantizado (depende del orden de iteracion de sets).