Matriz de validação de runtime
ContractForge separa compatibilidade de conector de validação em runtime.
Compatibilidade significa que o formato do contrato e o caminho de implementação são suportados. Validação significa que o caminho foi exercitado contra uma origem, runtime ou layout de arquivos real. Prontidão para produção ainda depende de rede, identidade, política de nuvem, limites do provedor e volume de dados do usuário.
Níveis de maturidade de conectores
| Status | Significado | Orientação para produção |
|---|---|---|
stable | Caminho central de conector com cobertura automatizada ampla e baixa variação específica de plataforma. | Adequado para uso normal após validação do ambiente. |
validated | Testado contra pelo menos um serviço externo ou caminho de runtime real. | Revise os pré-requisitos documentados e repita a validação no workspace alvo. |
experimental | Comportamento limitado ou específico de adapter que deve ser validado no runtime alvo. | Use em pilotos ou onboarding controlado; adicione validação com origem real antes de produção. |
planned | Conector ou caminho de validação planejado, ainda não suportado. | Acompanhe apenas como roadmap. |
validated é intencionalmente escopado. Ele não certifica todos os modos de autenticação, edições de provedor, topologias de rede, políticas de workspace ou perfis de volume de dados daquele conector. Ele significa que ContractForge tem evidência para pelo menos um caminho representativo em runtime real.
Resumo atual de maturidade
| Família de conectores | Conectores | Maturidade | Resumo de evidência |
|---|---|---|---|
| Catálogo Spark e arquivos | table, sql, csv, json, parquet, orc, delta, text | stable | Cobertos por testes automatizados e padrões reais de validação de pastas/arquivos. |
| Formatos de arquivo/objeto | source.format=avro, xml, jsonl, ndjson | validated | Usados por meio de conectores de object storage quando o runtime fornece os Spark readers necessários. |
| Arquivos HTTP | http_file, http_csv, http_json, http_text | validated | Usados para ingestão de arquivos HTTP públicos quando leituras Spark diretas em https:// não são confiáveis. |
| Object storage | s3, azure_blob, adls, object_storage, blob | validated | Validados por external locations governadas e caminhos selecionados de credenciais diretas quando o runtime permite. |
| Auto Loader | autoloader | validated | Validado com ingestão available-now, checkpoints, child runs e agregação de métricas de stream. |
| JDBC | jdbc, postgres, postgresql, mysql, sqlserver, oracle, redshift | validated | Validado com PostgreSQL/Supabase real e cenários RDS/Aurora IAM; outros engines JDBC usam o mesmo contrato Spark JDBC e exigem validação de driver/runtime. |
| REST bounded | rest_api | validated | Validado com payloads públicos aninhados, preservação de resposta bruta e transform.shape.parse_json. |
| Fontes externalizadas | SaaS, ERP, CRM, drives, SFTP/FTP, Kafka/Event Hubs, Snowflake, BigQuery, MongoDB/search | externalized | Use conectores nativos da plataforma/fornecedor ou pacotes customizados e exponha os dados ao ContractForge por primitivas oficiais. |
Evidência por runtime
| Cenário | Tempo de execução | Status | O que foi validado |
|---|---|---|---|
| CSV público via HTTP | Databricks serverless | validated | Download HTTP no driver, schema/opções CSV explícitos, sobrescrita do destino e metadados em tabelas de controle. |
| JSON REST aninhado | Padrão Databricks serverless/classic | validated | Preservação de payload bruto de API e transform.shape.parse_json para structs/arrays aninhados. |
| Azure Blob via External Location | Azure Databricks serverless | validated | Acesso governado a storage sem injeção direta de credencial SAS/Hadoop no contrato. |
| Azure Blob via SAS/configuração direta | Azure Databricks classic cluster | validated | Comportamento de credencial direta de storage onde a configuração de filesystem do runtime é permitida. |
| AWS S3 via External Location | AWS Databricks serverless | validated | Acesso S3 governado por Unity Catalog e padrões de ingestão de object storage. |
| AWS S3 com credenciais diretas | Classic cluster | validated | Configuração S3A com access key/session token vindos de secrets. |
| Auto Loader available-now | Padrões Databricks classic/serverless | validated | Checkpoints, child runs e métricas agregadas de stream em ctrl_ingestion_streams. |
| JDBC PostgreSQL/Supabase | Databricks | validated | Leituras JDBC, pushdown, particionamento, watermark e padrões SCD/hash-diff. |
| RDS/Aurora IAM JDBC | AWS Databricks serverless e diagnóstico classic | validated | Geração de token IAM, parâmetros SSL, diagnóstico de rede e opções Spark JDBC. |
| Shape público USGS GeoJSON | Azure Databricks classic cluster | validated | GeoJSON REST/raw com schema_ref, explosão de array de structs, extração de coordenadas, SCD hash diff e marts gold. Evidência mais recente: execução 516033488155314, validação 1040635449894221; 1 payload bronze, 1.807 eventos silver, 31 linhas gold diárias e 4 linhas por faixa de magnitude. |
| Dataset conhecido TPCH grande | Azure Databricks classic cluster | validated | Origem samples.tpch.lineitem com 29.999.795 linhas observadas e uma validação processando 250.000 linhas. Validou sql -> table -> sql, hash_diff_upsert, derivação/deduplicação em transform, agregação gold e evidência em control tables. Evidência mais recente: execução 714754107506943, validação 369877249106831. |
| Handoff de conector nativo | Databricks | validated pattern | Sistemas externos podem ser aterrissados ou federados por ferramentas nativas do Databricks e depois ingeridos como table, sql, arquivos ou object storage. |
Regra de adoção em produção
Antes de marcar um novo caminho de conector como pronto para produção em um projeto, registre:
- Tipo de runtime e restrições do workspace Databricks.
- Versão do conector e versão de biblioteca externa quando aplicável.
- Modo de autenticação e comportamento de redação de secrets.
- Caminho de rede e allowlists/políticas do provedor.
- Volume representativo de dados, paginação e limites de contagem de arquivos.
- Evidência em control tables: status da run, contagens de linhas, erros, quality status e métricas de stream quando aplicável.