Connection YAML

Arquivos YAML de conexão permitem que vários contratos de ingestão compartilhem padrões de conector sem ocultar a intenção específica do conjunto de dados dentro de um arquivo de configuração global.

Use-os para configurações de origem genuinamente compartilhadas:

• ponto final ou JDBC URL;
• tipo de conector e driver;
• forma de autenticação e referências secretas;
• common read defaults such as fetchsize;
• rótulos do sistema de origem usados ​​em evidências.

Não os use para semântica de conjunto de dados, como nome de tabela, consulta, marca d'água, limites de partição, regras de qualidade, modo de gravação, tabela de destino ou política de acesso. Esses pertencem ao contrato de ingestão.

Inventário do projeto

project.yaml pode listar arquivos de conexão reutilizáveis ​​para que humanos e ferramentas possam ver quais conexões pertencem ao projeto:

connections:
  supabase_postgres: connections/supabase.yaml

Este inventário não aplica uma conexão por si só. O contrato de ingestão escolhe a conexão através do source.type: connection.

Connection file

# connections/supabase.yaml
type: connector
connector: postgres
system: supabase_inventory_demo
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 mesmo arquivo também pode agrupar a carga em source: se um repositório preferir esse estilo:

source:
  type: connector
  connector: postgres
  system: supabase_inventory_demo
  options:
    url: "{{ secret:supabase/jdbc_url }}"
    driver: org.postgresql.Driver

Ingestion override

O contrato de ingestão aponta para o arquivo de conexão e declara o dataset-specific fields:

source:
  type: connection
  connection_path: project://connections/supabase.yaml
  table: public.products
  read:
    fetchsize: 20000
    partition_column: product_id
    lower_bound: 1
    upper_bound: 100000
    num_partitions: 8

target:
  catalog: contractforge
  schema: bronze
  table: b_products

mode: hash_diff_upsert
merge_keys: [product_id]

ContractForge carrega a conexão primeiro e depois mescla profundamente a ingestão source overrides on top.

Merge rule:

Location	Role
Connection YAML	Shared defaults.
Ingestion source	Substituições específicas do conjunto de dados. Esses valores vencem.

Para o exemplo acima, a fonte resolvida recebida pelo adaptador é equivalente to:

type: connector
connector: postgres
system: supabase_inventory_demo
options:
  url: "{{ secret:supabase/jdbc_url }}"
  driver: org.postgresql.Driver
auth:
  type: username_password
  username: "{{ secret:supabase/user }}"
  password: "{{ secret:supabase/password }}"
read:
  fetchsize: 20000
  partition_column: product_id
  lower_bound: 1
  upper_bound: 100000
  num_partitions: 8
table: public.products
connection: project://connections/supabase.yaml

read.fetchsize alterado de 10000 para 20000 porque o contrato de ingestão substituiu o padrão global. Outros campos read foram mesclados. não precisa saber onde morava o YAML; ele recebe esta fonte resolvida.

Regras de caminho

Prefira referências enraizadas no projeto:

source:
  type: connection
  connection_path: project://connections/supabase.yaml

Caminhos relativos do mesmo pacote são permitidos somente quando o arquivo de conexão está dentro o diretório do pacote de ingestão. Caminhos absolutos e travessia .. são rejeitados.

Estas regras evitam que um contrato leia arquivos arbitrários da máquina ou de outro inquilino/projeto.

Comportamento do adaptador

A conexão YAML é uma preocupação central de carregamento, não um recurso de tempo de execução da plataforma.

Databricks, AWS, Snowflake, Fabric, GCP e adaptadores futuros recebem o carga útil de origem resolvida. Eles devem registrar os metadados efetivos do conector em evidências, mas eles não devem reler a conexão YAML ou implementar suas próprias comportamento de mesclagem.

Checklist

• Coloque os padrões de endpoint, autenticação, driver e leitura comum no arquivo de conexão.
• Coloque leituras específicas de tabela, consulta, limites de partição, marca d'água e conjunto de dados o contrato de ingestão.
• Deixe a ingestão substituir a conexão global quando um conjunto de dados precisar de uma conexão diferente value.
• Keep secrets as secret references.
• Use project://connections/... para arquivos de conexão de projeto centralizados.