Desempenho e benchmarks.

ContractForge registra evidências de tempo operacional para cada execução. Use essas evidências para dashboards e use o benchmark harness quando precisar de comparações repetíveis de modos de escrita em um runtime específico.

Modelo de desempenho

ContractForge padroniza o comportamento de ingestão, mas o desempenho do runtime ainda depende do tamanho da fonte, modo de gravação, layout da tabela, runtime do Spark, acesso ao armazenamento e operações de governança.

Custo do modo de gravação

Anexar e substituir geralmente são mais baratos que os modos baseados em mesclagem. SCD2 e exclusão reversível de snapshot executam leituras de destino adicionais e trabalho SQL MERGE.

Evidência de stage

stage_durations registra leitura, preparação, esquema, marca d'água, qualidade, gravação, governança, tempo de estado e linhagem quando o estágio é executado.

Separação de runtime

Não compare Spark local, clusters clássicos e trabalhos serverless como se fossem uma plataforma. Mantenha registros de benchmark por runtime.

O layout é importante

Use Liquid Clustering ou particionamento somente quando os padrões de acesso justificarem. As opções de layout afetam verificações de mesclagem, otimização e latência de consulta.

Práticas recomendadas

Área	Orientação
Cache	Use use_cache=true somente quando estágios caros reutilizarem o mesmo DataFrame. Desative o cache primeiro quando aparecer pressão de memória.
JDBC	Use particionamento, tamanho de busca e predicados do lado da origem para tabelas grandes. Evite consultas ilimitadas em bancos de dados de produção.
API REST	Mantenha explícitos os limites de página, byte, tempo limite e nova tentativa. Coloque extratos muito grandes antes da ingestão.
Layout delta	Prefira cluster_columns para novas tabelas do Databricks quando o Liquid Clustering corresponder aos padrões de consulta. Evite partições de alta cardinalidade.
Portões de qualidade	Use quarentena para verificações de isolamento de linha e anule para verificações de nível de conjunto. Observe o tempo do estágio de qualidade nas tabelas de controle.

harness de benchmark em modo de gravação

O repositório inclui scripts/benchmark_write_modes.py para benchmarking de runtime opcional. Ele cria dados sintéticos determinísticos, executa modos de gravação oficiais selecionados e grava registros JSON Lines com duração, taxa de transferência, contadores de linhas, durações de estágio, tipo de runtime, versão Spark e versão ContractForge.

Não é um teste de IC normal

Os tempos de referência dependem do tamanho do cluster, da versão do runtime, do layout da tabela, do armazenamento e da configuração do catálogo. Trate os resultados como evidências ambientais e não como números universais de produtos.

python scripts/benchmark_write_modes.py --dry-run --rows 100000 --repeats 2

python scripts/benchmark_write_modes.py \
  --catalog main \
  --target-schema contractforge_bench \
  --ctrl-schema contractforge_bench_ops \
  --rows 1000000 \
  --partitions 32 \
  --repeats 3 \
  --reset \
  --output-jsonl benchmark_write_modes.jsonl

Resultado de referência

Campo	Significado
mode	Modo de gravação em teste.
requested_rows	Contagem de linhas de origem sintética solicitada.
rows_read / rows_written	Contadores de execução normalizados do ContractForge.
rows_per_second	rows_written / duration_seconds quando a duração estiver disponível.
stage_durations	Evidência de tempo por estágio do resultado da ingestão.
runtime_type, spark_version, framework_version	Evidência de runtime necessária para comparação.

Consulta do painel

SELECT
  target_table,
  mode,
  count(*) AS runs,
  round(avg(duration_seconds), 2) AS avg_duration_seconds,
  round(percentile_approx(duration_seconds, 0.95), 2) AS p95_duration_seconds,
  round(avg(rows_written / NULLIF(duration_seconds, 0)), 2) AS avg_rows_per_second
FROM main.ops.ctrl_ingestion_runs
WHERE status = 'SUCCESS'
GROUP BY target_table, mode
ORDER BY p95_duration_seconds DESC;