Padrões práticos de ingestão para fontes de dados comuns.
Os exemplos devem demonstrar os recursos do ContractForge sem ocultar o comportamento recorrente por trás das soluções alternativas do notebook. Se um padrão for amplamente útil, prefira um contrato declarativo ou um modelo reutilizável.
Public CSV over HTTP
Usa http_file, opções explícitas de CSV, integridade da fonte e modo de substituição.
NASA EONET REST API
Usa o modo de resposta bruto rest_api e transform.shape.parse_json para modelar matrizes aninhadas.
Azure Blob / ADLS files
Usa caminhos de armazenamento de objetos, esquemas, pastas particionadas, pesquisa recursiva e vários formatos de arquivo.
RDS/Aurora JDBC
Usa particionamento JDBC, pushdown, geração de token RDS IAM e gravações de hash diff.
Transferência de conector nativo
Usa conectores nativos do Databricks, Federação Lakehouse, replicação de fornecedor ou ferramentas de mercado para obter fontes especializadas primeiro e, em seguida, entregar a tabela ou os arquivos direcionados ao ContractForge.
Gerar um projeto inicial
contractforge init --bundle --layer bronze --target-schema raw --table b_orders --mode append
contractforge validate-project contracts/
Exemplos do mundo real no repositório
O repositório inclui exemplos determinísticos derivados do trabalho de validação do conector. O objetivo deles é parecer ativos de transferência de produção, em vez de fragmentos mínimos.
| Exemplo | O que demonstra |
|---|---|
examples/real-world/rest-nested-json-shape | Ingestão de carga útil bruta REST, transform.shape.parse_json, manipulação de array, comparação de hash SCD e avisos de qualidade. |
examples/real-world/usgs-earthquake-geojson-shape | Ingestão pública de USGS GeoJSON com schema_ref, explosão de matriz de estrutura, extração de coordenadas, métricas derivadas, hash-diff SCD, mercados de ouro e divisão de governança. |
examples/real-world/large-known-dataset-tpch | Fonte de amostra Databricks TPCH conhecida com 29,9 milhões de linhas observadas, uma execução validada de 250 mil linhas, conectores SQL/tabela, comparação de hash SCD1, agregação de ouro e evidência de tabela de controle. |
examples/real-world/autoloader-available-now | Ingestão do Auto Loader disponível agora, pontos de verificação, localização do esquema e evidências da tabela de controle de fluxo. |
examples/real-world/jdbc-postgres-scd1 | Leituras JDBC, particionamento, marca d'água, upsert SCD1 e regras de qualidade com capacidade de quarentena. |
examples/real-world/object-storage-multiformat | Armazenamento de objetos neutro em relação ao provedor, pastas de destino CSV/JSON/Parquet/Avro, esquemas explícitos e separação de governança. |
examples/real-world/supabase-jdbc-medallion | Projeto real de paridade de medalhão Databricks/AWS com conexão compartilhada YAML, referências de tabela lógica, particionamento JDBC, quarentena de qualidade, execução DAB, artefatos AWS S3 e implantação de trabalho Glue. |
Valide todos os exemplos do mundo real:
PYTHONPATH=src python examples/real-world/scripts/validate_real_world.py
Scenario catalog
Estes cenários destinam-se a mostrar padrões de ingestão em forma de produção, e não fragmentos de sintaxe isolados. Cada cenário deve tornar visíveis o acesso à fonte, a manipulação de esquemas, o comportamento de transformação, as evidências de qualidade e as suposições de tempo de execução.
| Scenario | Tempo de execução típico | O que demonstra |
|---|---|---|
| Public CSV over HTTP | Databricks serverless | http_file, opções explícitas de CSV, substituição, metadados de origem e um caminho de download seguro sem servidor. |
| Multi-format object storage | Databricks sem servidor ou clássico | object_storage neutro em termos de provedor, caminhos governados, pastas CSV/JSON/Parquet/Avro, pesquisa recursiva e metadados de formato de origem. |
| Nested REST JSON | Databricks sem servidor ou clássico | rest_api, preservação de carga útil bruta, transform.shape.parse_json, explosão de array e separação de esquema entre origem e transformação. |
| Small-file folder stress | Sem servidor ou clássico | Muitos arquivos, esquema explícito, pesquisa recursiva, seleção glob/regex, contagens de linhas e observabilidade da tabela de controle. |
| Azure Blob SAS files | Azure Databricks classic cluster | Credenciais diretas de armazenamento de objetos, pastas recursivas, esquemas, vários formatos de arquivo e configuração de armazenamento em nível de cluster. |
| Azure External Location | Databricks serverless | Acesso de armazenamento controlado sem SAS direto no contrato, leituras de caminho por meio de Unity Catalog e metadados de origem. |
| AWS S3 External Location | AWS Databricks serverless | Governança de armazenamento Unity Catalog, caminhos S3 através de locais externos e acesso compatível sem servidor. |
| AWS S3 direct credentials | Classic cluster | Configuração de credenciais S3A, comportamento de chave de acesso/token de sessão e restrições de armazenamento de objetos entre nuvens. |
| Auto Loader on Blob/ADLS | Databricks | cloudFiles, pontos de verificação, available_now, métricas de execução infantil e agregação de fluxo. |
| Supabase/Postgres JDBC | Databricks e AWS Glue/Iceberg | Driver JDBC, pushdown, leituras particionadas, marca d'água, padrões de comparação SCD1/hash e paridade de plataforma por meio de referências lógicas. |
| RDS/Aurora IAM | Classic cluster | JDBC auth.type=rds_iam, cadeia de credenciais botocore/default e diagnóstico de pré-requisitos de rede. |
| Large known dataset TPCH | Azure Databricks classic cluster | Fonte de amostra pública conhecida, processamento de 250 mil linhas, conectores SQL/tabela, comparação de hash SCD1, agregação de ouro e evidência de tempo de execução adequada para capturas de tela do painel. |
| Transferência de plataforma nativa | Sem servidor ou clássico | Fontes especializadas são enviadas ou federadas por Databricks/ferramentas nativas e depois processadas por ContractForge como table, sql, arquivos ou armazenamento de objetos. |
| SFTP partner drops | Conexão nativa clássica ou sem servidor | Estratégia de conexão SFTP nativa de download de driver versus Databricks, caminhos de teste, limites de arquivo e política de chave de host. |
Evidências esperadas de exemplos
Um exemplo é considerado útil quando produz evidências que um usuário pode inspecionar após a execução:
| Evidência | Onde inspecionar | Por que isso importa |
|---|---|---|
| Executar status e contagens de linhas | ctrl_ingestion_runs | Confirma se a movimentação de dados e a gravação da contabilidade correspondem às expectativas. |
| Metadados de origem | source payload in run records | Mostra qual conector, caminho/consulta e opções redigidas foram usados. |
| Quality status | ctrl_ingestion_quality e resumo da execução | Prova que os portões de qualidade foram executados e não ocultos no código do notebook. |
| Quarantine details | ctrl_ingestion_quarantine | Mostra linhas inválidas isoladas quando as regras estão no nível da linha e podem ser colocadas em quarentena. |
| Stream aggregation | ctrl_ingestion_streams | Confirma as métricas de execução pai/filho do fluxo disponível agora e os totais de microlotes. |
| Mudanças de esquema | ctrl_ingestion_schema_changes | Mostra alterações aditivas, desvios rejeitados e decisões de ampliação de tipo. |
O mesmo modelo de evidência deve ser utilizado na adaptação de exemplos a fontes privadas.
Template families
Os modelos fornecem pontos de partida opinativos para combinações comuns de conector, transformação e modo de gravação.
contractforge templates list
contractforge templates wizard --layer silver --source jdbc --mode hash_diff_upsert
contractforge templates write jdbc_hash_diff --output contracts/silver/s_orders
Arquivos pequenos e armazenamento de objetos particionados
Use esquemas explícitos, pesquisa recursiva e filtros regex opcionais para seleção avançada de arquivos.
REST raw payloads
Mantenha a recuperação do API no conector e modele cargas úteis aninhadas por meio do transform.shape.
JDBC incremental
Combine marca d’água, pushdown, leituras particionadas, portas de qualidade e semântica de mesclagem determinística.
Auto Loader available-now
Use tabelas de controle de fluxo para verificar contagens de microlotes e totais de linhas.
Exemplo de regra de design
Os exemplos não são permitidos para ocultar lacunas da estrutura com código Spark ad-hoc. Se uma fonte real exigir um comportamento comum, prefira melhorar a biblioteca ou documentar um padrão reutilizável.
Design principle
O comportamento de origem reutilizável pertence aos conectores, a modelagem reutilizável pertence ao transform.shape e a lógica de negócios específica da origem pertence ao código do projeto ou às transformações downstream.