Execute um contrato em cinco minutos.
Este início rápido mostra a forma ContractForge: instale o núcleo, adicione o adaptador para o tempo de execução de destino, valide o contrato e, em seguida, renderize ou execute por meio do adaptador.
1. Instale os pacotes
Instale o core neutro de plataforma e o pacote do adaptador do runtime de destino:
pip install contractforge-core contractforge-databricks
Use o pacote correspondente para outros runtimes:
pip install contractforge-core contractforge-aws
pip install contractforge-core contractforge-snowflake
pip install contractforge-core contractforge-fabric
pip install contractforge-core contractforge-gcp
A entrega em runtime muda por plataforma. Databricks e Fabric normalmente podem instalar pelo PyPI no ambiente de job/notebook; AWS Glue deve receber wheels no S3; procedures Snowflake hospedadas usam imports ZIP preparados em stage; GCP BigQuery/Workflows executam artefatos nativos enquanto o adaptador roda na CLI ou no CI.
Veja Instalação para a matriz completa de pacotes e entrega em runtime.
2. Crie um contrato mínimo de ingestão
source:
type: table
table: main.raw.orders
system: crm
target:
catalog: main
schema: bronze
table: b_orders
layer: bronze
mode: append
schema_policy: additive_only
quality_rules:
not_null: [order_id]
expressions:
- name: positive_amount
expression: amount >= 0
severity: abort
O destino canônico está sempre aninhado em target. Os metadados de propriedade de origem pertencem ao source.system, não como um campo de nível superior.
3. Valide com a CLI do core
contractforge validate contracts/bronze/b_orders.ingestion.yaml
A etapa principal de validação verifica o formato do contrato, a semântica portátil e os campos que não devem vazar detalhes de implementação da plataforma no modelo semântico.
4. Planeje ou renderize com um adaptador
Use o adaptador Databricks quando o destino de execução for Databricks:
from contractforge_databricks import render_databricks_contract
artifacts = render_databricks_contract("contracts/bronze/b_orders.ingestion.yaml")
print(artifacts.status)
print(sorted(artifacts.artifacts))
A renderização produz artefatos Databricks nativos, como SQL, Python, fragmentos de Asset Bundle e relatórios de revisão, quando aplicável.
Para AWS:
contractforge-aws render contracts/bronze/b_orders.ingestion.yaml --environment environments/prod.aws.yaml
A renderização produz scripts Glue Spark, definições de trabalho Glue, artefatos de revisão, evidências DDL e andaimes de infraestrutura.
5. Execute um pacote de contrato dividido em Databricks
from contractforge_databricks import ingest_databricks_bundle
result = ingest_databricks_bundle(
"/Workspace/Shared/contracts/bronze/b_orders",
options={
"catalog": "main",
"schema": "ops",
},
)
display(result)
O caminho do pacote pode resolver:
b_orders.ingestion.yaml
b_orders.annotations.yaml
b_orders.operations.yaml
b_orders.access.yaml
b_orders.environment.yaml
Apenas a ingestão é necessária para mover dados. Os outros contratos tornam explícitos os metadados do catálogo, as operações, o acesso e as escolhas de ambiente.
6. Inspecione evidências
No Databricks, o adaptador persiste o modelo de evidência principal nas tabelas de controle Delta:
SELECT
status,
target_table,
mode,
source_system,
source_connector,
rows_read,
rows_written,
rows_quarantined,
quality_status,
framework_version,
error_message
FROM main.ops.ctrl_ingestion_runs
ORDER BY started_at_utc DESC
LIMIT 20;
Outros adaptadores devem preservar os mesmos conceitos de evidência, mesmo quando sua implementação de persistência não for Delta.
7. Faça deploy no AWS Glue
AWS usa um contrato de ambiente para selecionar a publicação do artefato S3, tarefa Glue configurações e o armazém Iceberg:
name: prod
adapter: aws
artifacts:
uri: s3://contractforge-artifacts/prod/orders/
include_contract_bundle: true
include_normalized_contract: true
parameters:
aws:
iceberg:
warehouse: s3://contractforge-warehouse/prod/
glue_job:
role_arn: arn:aws:iam::123456789012:role/ContractForgeGlueRole
contractforge-aws deploy contracts/bronze/b_orders.ingestion.yaml --environment environments/prod.aws.yaml
O adaptador renderiza artefatos, publica-os no S3 e cria ou atualiza o Trabalho Glue. Glue executa código nativo Spark/Iceberg; não analisa contrato YAML em tempo de execução.
8. Use referências lógicas de tabela
Quando um contrato downstream lê uma tabela produzida por outro ContractForge contrato, use uma referência neutra:
source:
type: table
ref: bronze.b_products_jdbc
SQL embutido pode usar:
FROM {{ table_ref:silver.s_product_tags }}
Databricks, AWS, Snowflake, Fabric e GCP resolvem essas referências para seus modelos nativos de catálogo/tabela, mas a intenção do contrato permanece a mesma.