API e carga útil de resultado.

As APIs ContractForge retornam evidências operacionais estruturadas. As execuções com falha são geradas por padrão, depois que os registros da tabela de controle são persistidos.

Pontos de entrada públicos

API	Usar quando
ingest(**kwargs)	Você chama a estrutura de notebooks ou código Python.
ingest_plan(plan)	Você já normalizou um IngestionPlan.
ingest_stream_plan(plan)	Você executa a ingestão do Auto Loader disponível agora.
ingest_bundle(bundle)	Você carrega contratos divididos e deseja ingestão e metadados de governança.
validate_plan_shape(contract)	Você valida a estrutura YAML/JSON sem iniciar o Spark.
yaml_schema()	Você gera o esquema de contrato YAML mais amplo para validação do editor.
contract_model_schemas()	Você gera fragmentos do esquema JSON a partir dos modelos de limite do Pydantic para contratos de origem, governança, forma e transformação.

Comportamento de falha

Por padrão, ingest, ingest_plan, ingest_stream_plan e ingest_bundle aumentam ContractForgeExecutionError para o status final de FAILED ou ABORTED. A carga útil do resultado ainda é gravada primeiro nas tabelas de controle.

from contractforge import ContractForgeExecutionError, ingest

try:
    result = ingest(**contract)
except ContractForgeExecutionError as exc:
    print(exc.run_id)
    print(exc.target_table)
    print(exc.result["error_message"])

Campos de resultados importantes

Campo	Significado
status	SUCCESS, FAILED, SKIPPED, DRY_RUN ou outro status final.
run_id	Identificador de execução primário usado em tabelas de controle.
source	Metadados do conector e métricas de origem editados.
rows_read, rows_written	Métricas de linha lógica calculadas pela estrutura.
rows_inserted, rows_updated, rows_deleted	Métricas de gravação específicas do modo, quando disponíveis.
rows_quarantined	Linhas isoladas por regras de qualidade com capacidade de quarentena.
stage_durations	Segundos gastos nos estágios de leitura, esquema, qualidade, gravação, estado, linhagem e governança.
watermark_previous, watermark_current	Transição de estado usada para processamento incremental.
framework_version, ctrl_schema_version	Evidência de versão para suporte e migrações.