Compatibilidade de runtime.
ContractForge reconhece o runtime, mas acesso a storage, dependências de connector e recursos do Unity Catalog ainda dependem de onde o código executa.
Matriz de runtime
| Capacidade | Classic cluster | Serverless/Spark Connect | Spark local |
|---|---|---|---|
| Escritas batch Delta | Suportado | Suportado | Compatível com dependências Delta |
| APIs Python DeltaTable | Geralmente suportado | Limitado | Depende de dependências |
| Mesclagem SQL | Suportado | Suportado | Compatível com Delta |
| Auto Loader | Apenas Databricks | Apenas Databricks | Não disponível |
| Unity Catalog annotations | Depende das permissões | Depende das permissões | Não disponível |
| Credenciais diretas de object storage | Padrão comum | Prefira External Location ou Volume | Dependente do ambiente |
| Fontes federadas | Suportado quando existe conexão UC | Recomendado para sistemas externos governados | Não disponível |
| JDBC | Requer driver/rede | Requer suporte de driver/rede | Requer driver/rede |
Modelo de dependência do conector
Formatos Spark integrados
CSV, JSON, Parquet, Delta, ORC e texto geralmente funcionam quando o Spark os suporta.
Pacotes Spark extras
XML, Avro e drivers JDBC devem estar disponíveis no tempo de execução que executa o leitura. Snowflake, BigQuery, MongoDB e sistemas similares são padrões de fonte externalizada; use conectores da plataforma/fornecedor, federation ou pacotes customizados, e passe o resultado landed ao ContractForge.
Cloud object storage
Serverless deve usar External Locations ou Volumes; classic clusters podem usar credenciais Spark/Hadoop quando a política permitir.
HTTP do lado do driver
REST e HTTP file dependem de egress do driver, DNS, regras de proxy e limites de API. Microsoft Graph, SharePoint Server, SFTP e fontes similares são externalizadas, a menos que sejam implementadas por um resolver customizado do projeto.
Extra local do Spark
contractforge[spark] atualmente mira pyspark>=3.4,<4 com delta-spark>=3.0,<4. Spark 4 e Delta 4 não são habilitados pelos metadados do pacote até que testes locais de write mode, schema, qualidade, shape, watermark e control tables sejam validados juntos.
Política de pacotes Spark e Delta
| Ambiente | Status | Proprietário da dependência | Decisão |
|---|---|---|---|
| Databricks classic clusters | Suportado | Tempo de execução Databricks | Use a stack Spark e Delta fornecida pelo runtime. |
| Databricks serverless/Spark Connect | Compatível com limites de runtime | Databricks Runtime | Prefira storage governado, operações SQL-compatible e alternativas documentadas. |
| PySpark 3.x local + Delta 3.x | Suportado para desenvolvimento e testes | contractforge[spark] | Extra local validado atual. |
| PySpark 4.x local + Delta 4.x | Ainda não ativado | Experiência gerenciada pelo usuário | Requer validação explícita antes que os intervalos de dependência sejam ampliados. |
Não instale contractforge[spark] em Databricks jobs, a menos que esteja criando intencionalmente um ambiente de teste isolado. Instale o wheel ContractForge e deixe o Databricks Runtime fornecer Spark e Delta.
Padrões de connector em serverless
Use serverless para ingestão governada e repetível quando o caminho de acesso é configurado pela plataforma. Use classic clusters quando precisar controlar diretamente bibliotecas de baixo nível, opções JVM ou credenciais de filesystem.
| Source | Padrão serverless preferido | Quando usar classic |
|---|---|---|
| S3/Azure Blob/ADLS | Unity Catalog External Location ou Volume; ContractForge lê o path governado. | Credenciais S3A/ABFS/SAS diretas, bibliotecas Hadoop customizadas ou provedores de credenciais não padrão. |
| SaaS/arquivos/streams especializados | Use conectores nativos do Databricks, Lakeflow Connect, Lakehouse Federation, marketplace/vendor tools ou pacotes customizados; ContractForge lê o resultado landed/federado. | Bibliotecas diretas, networking customizado ou dependências específicas de fornecedor que o caminho de plataforma não cobre. |
| JDBC/RDS IAM | Suportado quando driver, rota, SSL e credenciais IAM estão disponíveis para o runtime. | Bancos privados que exigem customização em nível VPC/VNet, instalação de driver ou ajuste de extract de longa duração. |
| REST/HTTP file | HTTP do lado do driver com timeouts explícitos, retries e limites de tamanho/página. | Payloads grandes que devem primeiro ser landed em object storage ou rotas de API que exigem proxies customizados. |
Modelo de falha em serverless
Falhas em serverless geralmente acontecem antes que o provedor externo avalie a credencial. Trate acessibilidade do runtime, autenticação do provedor e sintaxe do contrato como camadas separadas.
| Sintoma | Camada provável | Próxima verificação |
|---|---|---|
| O segredo é resolvido, mas o acesso é negado pelo provedor. | Autenticação ou autorização do provedor. | Valide permissões de aplicativos, política de rede Snowflake, concessões IAM, concessões de banco de dados ou permissões de site Graph. |
| DNS, timeout de conexão, porta bloqueada ou endpoint indisponível. | Política ou roteamento de rede do workspace. | Valide conectividade serverless, PrivateLink/NCC, firewall allowlists, requisitos de proxy ou use uma conexão governada. |
| Spark rejeita configuração de credenciais Hadoop. | Política Spark Connect/runtime. | Use Unity Catalog External Location ou Volume em vez de configuração de filesystem em nível de notebook. |
| A classe do connector ou o driver JDBC está ausente. | Dependência de runtime. | Instale o pacote em classic/job clusters, use um caminho de biblioteca serverless compatível ou use federation. |
HTTP 403 ou resposta malformada é retornada por um conector de driver. | Resposta de origem determinística. | Corrija credenciais, solicite URL, permissões ou análise de resposta. ContractForge não tenta novamente falhas determinísticas. |
Regra de compatibilidade
Se um recurso depender da plataforma, documente isso na página do connector e exponha um erro claro. Não faça fallback silencioso para um comportamento mais fraco que possa ocultar configuração incorreta de runtime.