nini-datacomp

Compara duas tabelas grandes linha a linha, dentro de um orçamento de memória. Diz quais linhas existem só de um lado, quais divergem, em que colunas e com exemplos, num relatório em texto, Markdown, HTML ou JSON.

É a reescrita do datacompolars: o mesmo resultado (os testes conferem os casos de borda contra ele, amostra por amostra), com a comparação em kernels C++ que leem as colunas do Polars sem cópia.

• Memória sob controle: a comparação anda em janelas pela chave, do tamanho que cabe no memory_limit ("auto" = 1/4 da RAM livre, até 2 GB). Tabelas maiores que a memória são comparadas sem problema.
• Rápida: 10 milhões de linhas x 300 colunas em 32 s com 1 GB, onde o datacompolars levava 50 s e usava quase 2 GB (números).
• Sem surpresas: igualdade exata pelo hash de linha (com verify_hash=True para conferir célula a célula), tolerâncias absolutas e relativas com a aritmética do Polars, texto sem caixa e sem espaços, nulos e NaN como no datacompolars.
• Lê o que você tem: Parquet, CSV, JSON, Arrow, Avro, Excel e os arquivos do SAS (.sas7bdat, .xpt), do Stata (.dta) e do SPSS (.sav, .zsav, .por), estes pelo ReadStat compilado na própria biblioteca: nenhum pacote a mais.
• Leve: só polars, numpy e pydantic; wheels prontos para Linux, Windows e macOS (x86-64 e ARM), sem compilador.

Instalação

pip install nini-datacomp

Python 3.10 ou mais novo e Polars 1.30 ou mais novo.

Uso

import nini_datacomp as dc  # importe antes do Polars (veja Memória)

result = dc.compare(
    "sas/tops_adm.parquet",  # arquivo, pasta, glob, pl.DataFrame ou pl.LazyFrame
    "lake/tops_adm/",
    on=["id", "competencia"],  # a chave: uma coluna ou várias
    abs_tol={"valor": 0.005},  # tolerância numa coluna (ou um número para todas)
    memory_limit="2GB",
)

result.is_match  # False
result.rows.mismatched  # linhas em comum com algum valor diferente
result.columns["valor"].mismatches  # divergências nessa coluna
result.columns["valor"].samples  # pl.DataFrame: id, competencia, valor (left), valor (right)

print(result.report())  # o relatório em texto
result.report(path="relatorio.html")  # ou em HTML (o formato sai da extensão)

As opções vão como argumentos nomeados, como acima, ou num dc.CompareOptions(...) passado em options=.

Formatos

O formato sai da extensão; uma pasta vira uma fonte só (com as subpastas; arquivos que começam com . ou _ ficam de fora). Tudo o que não é Parquet é convertido uma vez para Parquet numa pasta temporária, aos pedaços (cada um com ~1/16 do memory_limit), e a pasta some no fim da comparação.

read=dc.ReadOptions(...) muda a leitura, para os dois lados ou um par (esquerda, direita):

dc.compare(
    "sas/tops_adm.sas7bdat",
    "lake/tops_adm/",
    on="id",
    cast="right",  # no SAS todo número é real (Float64); no lake o id costuma ser inteiro
    read=(dc.ReadOptions(encoding="wlatin1"), dc.ReadOptions()),
)

Para ler fora da comparação: dc.read_sas, dc.read_stata e dc.read_spss devolvem um pl.DataFrame; dc.scan_sas, dc.scan_stata e dc.scan_spss, um pl.LazyFrame lido aos pedaços quando a consulta roda (cada collect lê o arquivo de novo).

O resultado

O relatório

result.report(format=None, path=None, *, width=100, style="auto", max_columns=20, max_sample_columns=10, print_output=False), nos formatos "text", "markdown", "html" e "json". Sem format, o formato sai da extensão de path (.md, .html, .json, .txt); com path, o relatório também é salvo. Texto e Markdown mostram até max_columns colunas com divergência; HTML e JSON trazem tudo.

┌──────────────────────────────────────────────────────────────────────────────┐
│ ✘ DIFFERENCES FOUND                                                          │
│ 2 of 3 common rows differ (66.67%); 1 rows only in sas; 1 rows only in lake. │
└──────────────────────────────────────────────────────────────────────────────┘

DIFFERENCES BY COLUMN
─────────────────────

  ┌────────┬─────────┬─────────────┬─────────────┬──────────────┐
  │ Column │ Type    │ Differences │ % of common │              │
  ├────────┼─────────┼─────────────┼─────────────┼──────────────┤
  │ valor  │ Float64 │           2 │      66.67% │ ████████░░░░ │
  └────────┴─────────┴─────────────┴─────────────┴──────────────┘

SAMPLE DIFFERING ROWS
─────────────────────

  valor: 2 differing rows, showing 2
  ┌────┬─────────────┬─────────────┬──────────────┐
  │ id │ competencia │ valor (sas) │ valor (lake) │
  ├────┼─────────────┼─────────────┼──────────────┤
  │ 2  │ 2026-01     │ 10          │ 10.5         │
  │ 3  │ 2026-01     │ 7.25        │ null         │
  └────┴─────────────┴─────────────┴──────────────┘

Opções

Uma opção com nome errado é erro (extra="forbid"), em vez de ser ignorada.

Comparadores próprios

comparators={"coluna": ...} troca a comparação de uma coluna (a chave não pode). A regra de nulos é a de sempre: nulo com nulo é igual, nulo de um lado só é diferente, e o comparador só decide os pares sem nulo. Tolerâncias e as opções de texto não se aplicam à coluna: quem decide é o comparador.

O caminho rápido é o dc.expr, uma mini-linguagem que roda nos kernels C++:

from nini_datacomp.expr import left, right

dc.compare(
    a,
    b,
    on="id",
    comparators={
        "nome": left.strip().lower() == right.strip().lower(),
        "valor": (left - right).abs() <= 0.01 * right.abs(),
        "codigo": left.remove_whitespace() == right.remove_whitespace(),
    },
)

Tem + - * /, abs(), == != < <= > >=, & | ~ e, no texto, lower(), upper(), strip(), remove_whitespace() e len(), com a semântica do Polars (inclusive o Unicode: "ß".upper() == "SS"). Lê inteiros (menos UInt64), reais, booleanos e texto; reais fazem conta em 64 bits.

Para o resto, uma função f(esquerda, direita) -> pl.Expr (ou um comparador do datacompolars, com compare), que roda no Polars só nos pares daquela coluna e avisa com PerformanceWarning:

comparators = {"itens": lambda l, r: l.list.sort() == r.list.sort()}

Tipos

Inteiros, reais, booleano, texto (String, e Categorical e Enum comparados como texto), Date, Datetime, Duration, Time e Decimal, e os aninhados (List, Array e Struct), comparados pelo valor inteiro: [1, 2] e [2, 1] são diferentes, a não ser que a coluna esteja em unordered_lists; tolerâncias e as opções de texto não entram nos campos de dentro. Os aninhados vão pelo hash do valor (o Expr.hash do Polars, 64 bits), como as outras colunas exatas.

Desempenho

O caminho exato (hash de linha) contra o datacompolars 0.4.4, com memory_limit="1GB" (954 MiB), num Windows 11 com 16 threads e 15,7 GB. Média de 5 execuções, cada uma num processo novo; a razão vem com o IC de 95%, e um caso é ok se o intervalo inteiro fica em até 1,10. As contagens (linhas e divergências por coluna) conferem em todos.

O nini-datacomp fica dentro do memory_limit em todos os casos; o datacompolars não tem orçamento e usa até o dobro. Os detalhes, com o caminho coluna a coluna (com tolerância), estão em docs/benchmarks/.

Memória

Importe o nini_datacomp antes do Polars. No import, ele configura o alocador do Polars (MIMALLOC_PURGE_DELAY=10 e MIMALLOC_RESET_DELAY=10) para devolver em 10 ms a memória que libera: sem isso, numa comparação grande no Windows o pico chega a ~1,9x; devolvendo na hora, cada janela pede de novo ao sistema a memória da anterior (até ~30% mais lento). Se o Polars já tiver sido importado, não dá mais para configurar e o pacote avisa com AllocatorWarning; dá para definir as variáveis antes de iniciar o Python, ou silenciar com NINI_DATACOMP_ALLOCATOR=0.

Vindo do datacompolars

Mesma semântica; mudam os nomes, e o que era ajuste interno do motor vira um orçamento de memória.

Desenvolvimento

Precisa de Python ≥ 3.10, uv, CMake ≥ 3.20 e um compilador C++17 (no Windows, o Visual Studio com as ferramentas de C++; os wheels publicados usam o clang-cl).

uv sync                                    # compila o C++ e instala o pacote no ambiente
uv run python tools/check.py               # formata, lint, tipos e testes, parando no primeiro que falhar
uv run python tools/check.py --then bench_hash   # ... e, se tudo passar, um benchmark
uv run python tools/gen_bindings.py        # depois de mudar a assinatura de uma função C++

Ferramentas (tools/):

No Windows, para compilar como os wheels: $env:DC_CLANGCL = "1" antes do uv sync (precisa dos componentes "C++ Clang Compiler for Windows" e "MSBuild support for LLVM (clang-cl) toolset" no Visual Studio Installer).

Licença

Apache-2.0 (veja LICENSE e NOTICE).