Tabela e SQL

estável

Use fontes nativas do catálogo quando os dados já estiverem registrados em Spark ou Unity Catalog.

Quando usar

Escolha table, delta_table ou view para objetos registrados. Escolha sql quando a origem precisar ser uma consulta de extração revisada em vez de um objeto de catálogo reutilizável.

Registered tables

Fontes nativas do catálogo

Use isso para Unity Catalog, metastore Hive ou objetos de catálogo Spark já disponíveis para o tempo de execução.

Views

Lógica de origem compartilhada

Prefira visualizações quando a filtragem ou junções do lado da origem forem reutilizadas por mais de um contrato de ingestão.

SQL extracts

Reviewed predicates

Use SQL para lógica de extração limitada. Promova transformações comerciais complexas para visualizações, notebooks ou contratos Silver/Gold.

Internal lakehouse

Fastest path

Este conector não possui driver externo ou camada de credenciais além das permissões de catálogo.

Requisitos de tempo de execução

Requirement	Details
Acesso ao catálogo	O principal do trabalho deve ser capaz de ler a tabela de origem, a visualização ou as dependências SQL.
Fully qualified names	Use nomes de catálogo/esquema/tabela para tabelas externas. Use referências lógicas para tabelas produzidas por outros contratos ContractForge.
SQL review	Mantenha o SQL inline pequeno o suficiente para revisão. A lógica grande deve residir em visualizações ou transformações versionadas.
Watermark columns	Se estiver usando leituras incrementais, a tabela/consulta selecionada deverá expor as colunas de marca d'água.

Exemplo básico

source:
  type: connector
  connector: table
  table: main.raw.orders

source:
  type: connector
  connector: sql
  query: |
    SELECT id, updated_at, amount
    FROM main.raw.orders
    WHERE status = 'closed'

Referências de tabela lógica

Use referências lógicas quando a origem for outra tabela gerenciada por ContractForge. Esse mantém contratos medalhão portáteis em Databricks, AWS e adaptadores futuros.

source:
  type: table
  ref: bronze.b_products_jdbc

O SQL inline pode usar a mesma referência neutra:

source:
  type: sql
  query: |
    SELECT *
    FROM {{ table_ref:silver.s_product_tags }}

O núcleo valida a referência layer.table. Databricks resolve isso para um Unity Catalog-style name; AWS resolves it to Glue Catalog/Iceberg.

Tipos de origem compatíveis

Conector	Usar
table	Tabela de tempo de execução registrada ou source.ref lógico para uma tabela produzida por outro contrato ContractForge.
delta_table	Tabela Delta registrada quando se deseja explicitar o tipo de armazenamento.
view	Visualização registrada usada como objeto de origem.
sql	Consulta inline SQL declarada no contrato; pode incluir espaços reservados {{ table_ref:layer.table }}.

Advanced patterns

Use fontes SQL para predicados de extração pequenos e revisados. Se o SQL se tornar uma transformação de negócios, promova-o para uma visualização, etapa de notebook ou contrato Silver/Gold.

source:
  type: connector
  connector: sql
  query: |
    SELECT order_id, updated_at, amount
    FROM main.raw.orders
    WHERE updated_at >= timestamp '2026-01-01'
watermark_columns: [updated_at]

Validação operacional

SELECT run_id, status, source_connector, source_table, source_query, rows_read, rows_written
FROM main.ops.ctrl_ingestion_runs
WHERE source_connector IN ('table', 'delta_table', 'view', 'sql')
ORDER BY started_at_utc DESC;

Common issues

Symptom	Likely cause	Action
Tabela não encontrada	Nome não qualificado, contexto de catálogo/esquema incorreto ou nomenclatura de referência lógica que não pode ser inferida.	Use nomes totalmente qualificados para fontes externas; use source.ref ou table_ref explícito para tabelas gerenciadas por ContractForge.
Permission denied	O principal do trabalho não possui concessões de catálogo/tabela.	Conceda permissões de leitura de origem fora do ContractForge.
Inline SQL is hard to review	A transformação dos negócios está oculta na extração da fonte.	Mova a lógica para uma visualização ou contrato downstream.

Como este conector se encaixa no contrato

Mantenha as preocupações de extração em source, normalização estrutural em transform, validação em quality_rules e semântica de destino em mode. Essa separação mantém os exemplos portáteis e evita que soluções alternativas específicas do conector se tornem uma lógica de negócios oculta.