Visão geral do conector

ContractForge modela a intenção de origem no núcleo e permite que os adaptadores escolham a implementação nativa. Isso mantém os conceitos de origem comuns portáveis, sem fingir que todas as plataformas têm o mesmo tempo de execução do conector.

Classes de portabilidade de origem

Class	Exemplos	Comportamento ContractForge
Intenção de origem portátil	table, view, sql, csv, json, parquet, orc, text, avro, jdbc, http_file, object_storage, incremental_files	O núcleo pode validar a intenção e os adaptadores mapeiam-na para leitores nativos.
Bounded streaming	kafka_bounded, eventhubs_bounded	Semântica de atualização ou repetição limitada, não uma promessa implícita de streaming contínuo.
Engine-specific	Databricks autoloader, AWS glue_bookmark, Fabric dataflow_gen2_*	Válido apenas para o adaptador correspondente. Outros adaptadores retornam diagnósticos.
Passagem nativa	Salesforce, Workday, SAP, SharePoint, conectores SaaS gerenciados	O contrato registra a intenção, enquanto o adaptador delega para sistemas de plataforma/fornecedor nativos.
Tratamento customizado	custom_transform	O contrato declara entradas nomeadas e saida esperada; o adaptador vincula codigo nativo de tratamento, como um notebook Databricks, antes da validacao e escrita pelo ContractForge.

Reusable connection YAML

Muitos contratos de ingestão partilham os mesmos detalhes de ligação. Use source.type: connection para herdar um arquivo de conexão centralizado e manter cada contrato de conjunto de dados focado na intenção específica da tabela.

Contrato de conjunto de dados:

source:
  type: connection
  connection_path: /Workspace/Shared/connections/supabase_postgres.connection.yaml
  table: public.products

target:
  catalog: main
  schema: bronze
  table: b_products

mode: hash_diff_upsert
hash_keys: [product_id]

Connection file:

source:
  type: postgres
  system: supabase_postgres
  options:
    url: "{{ secret:supabase/jdbc_url }}"
    driver: org.postgresql.Driver
  auth:
    type: username_password
    username: "{{ secret:supabase/user }}"
    password: "{{ secret:supabase/password }}"
  read:
    fetchsize: 10000

O carregador mescla o arquivo de conexão com substituições no nível do conjunto de dados. Os campos do conjunto de dados vencem. O adaptador recebe uma especificação de origem resolvida e registra os metadados de origem efetivos em evidência.

Campos de origem padrão

Field	Propósito
type	Tipo de fonte ou classe de portabilidade.
connection_path	Caminho para uma conexão reutilizável YAML quando type: connection.
connector	Identificador de conector opcional para compatibilidade com type: connector.
system	Rótulo do sistema de origem registrado em evidência.
ref, table_ref	Referência lógica layer.table a uma tabela produzida por outro contrato ContractForge.
table, query, path, format	Identidade de origem.
options	Opções do leitor ou configurações do conector não secreto.
auth	Configurações de autenticação apoiadas por segredo. Os valores são ocultados nas evidências.
read	Controles de leitura com reconhecimento de estrutura, como particionamento, tamanho de busca, esquema, ponto de verificação ou marcadores de integridade.
request, pagination, response, limits	Controles de origem HTTP/REST.

Exemplos de mapeamento de adaptador

Fonte do contrato	Adaptador Databricks	Destino do adaptador AWS	Destino do adaptador Fabric
incremental_files	Auto Loader / cloudFiles	Marcadores Glue ou trabalho de streaming	Dataflow/Pipeline incremental pattern
jdbc / postgres	Spark JDBC com driver configurado e token RDS IAM opcional	Glue JDBC / EMR Spark JDBC	Dataflow Gen2 ou Spark JDBC quando disponível
table / sql	Tabela Spark SQL / Unity Catalog	Catálogo Glue, Athena/Iceberg ou EMR SQL	Tabela Lakehouse ou endpoint SQL
native_passthrough Salesforce	Lakeflow Connect Salesforce	AppFlow Salesforce	Conector Dataflow Gen2

Esses mapeamentos são responsabilidades do adaptador. O núcleo apenas preserva a intenção da fonte e valida os limites da portabilidade.

Fronteira de tratamento customizado

Use custom_transform quando uma transformacao declarativa nao expressa bem o tratamento necessario, mas o resultado ainda deve ficar sob validacao, modo de escrita e evidencias do ContractForge.

O exemplo completo de movies no Databricks esta documentado em Transformacao customizada no Databricks.

Logical downstream refs

Para projetos medalhões, prefira referências lógicas quando um contrato lê o output of another:

source:
  type: table
  ref: bronze.b_products_jdbc

As fontes SQL podem usar espaços reservados:

FROM {{ table_ref:silver.s_product_tags }}

Databricks resolve a referência ao seu nome de catálogo/esquema/tabela. AWS resolve para Catálogo Glue/Iceberg. O núcleo não conhece o qualificador de nenhuma das plataformas.

Production checklist

• Mantenha os segredos em referências secretas, não em valores literais YAML.
• Use conexão reutilizável YAML para terminais compartilhados.
• Marque a integridade da fonte ao usar os modos de substituição, instantâneo ou reconhecimento de exclusão.
• Declare explicitamente o streaming limitado; não implicam streaming contínuo, a menos que o adaptador suporte isso.
• Use tipos de origem específicos do adaptador somente quando a portabilidade não for necessária.
• Verifique as tabelas de controle/evidência após a primeira execução para confirmar metadados de origem, conector, contagens de linhas e redação.