Adaptador Databricks

contractforge-databricks é o primeiro adaptador ContractForge completo. Depende do contractforge-core e mantém o código específico do Databricks fora do núcleo semântico.

Instalar

pip install contractforge-core contractforge-databricks

No Databricks, instale ambas as rodas no trabalho, cluster, ambiente de notebook ou caminho do espaço de trabalho. Não instale Spark no núcleo; O tempo de execução Databricks fornece Spark e Delta.

Public entry points

from contractforge_databricks import (
    deploy_databricks_project,
    render_databricks_contract,
    ingest_databricks_bundle,
)

Use render_databricks_contract para produzir artefatos nativos e revisar a saída. Use ingest_databricks_bundle quando o espaço de trabalho Databricks precisar executar o contrato diretamente. Use deploy_databricks_project ou CLI quando um projeto de repositório já contém um pacote de ativos Databricks e deve ser validado, implantado e opcionalmente, execute por meio da implantação nativa Databricks.

Capacidades nativas

ContractForge area	Databricks implementation
Tables	Tabelas Delta em Unity Catalog ou metastore configurado.
Incremental files	Carregador automático / cloudFiles e streaming disponível agora quando configurado.
Writes	Delta modos de anexação, substituição, mesclagem/upsert, hash-diff de estado atual, histórico e exclusão reversível de instantâneo.
Tratamento customizado	Notebook Databricks como pre-task no Asset Bundle, seguido por validacao, escrita e evidencia pelo ContractForge.
Governança	Comentários Unity Catalog, tags, concessões, filtros de linha e máscaras de coluna quando suportados.
Evidência	Tabelas de controle Delta seguindo o modelo de evidência principal.
Rendering	Relatórios de planejamento SQL, Python, Databricks Asset Bundles, Lakeflow e revisão de Markdown.
Tempo de execução	Jobs Databricks, notebooks, clusters serverless ou clássicos dependendo da configuração do ambiente.

Extensões de adaptador

As configurações específicas da plataforma estão sob extensions.databricks ou no contrato de ambiente. Eles não se tornam campos centrais de nível superior.

extensions:
  databricks:
    delta_properties:
      delta.enableChangeDataFeed: "true"
    cluster_columns: [customer_id]
    partition_columns: [ingestion_date]

Use extensões de adaptador apenas para comportamento Databricks. Conceitos portáteis como identidade de destino, modo de gravação, qualidade, política de esquema e intenção de origem permanecem no contrato principal.

Fronteira de transformacao customizada

Para tratamentos complexos que devem ficar em codigo Databricks revisado, use source.type: custom_transform. O contrato declara entradas nomeadas, colunas esperadas de saida, regras de qualidade e destino. A extensao Databricks vincula essa fronteira semantica a uma task de notebook:

extensions:
  databricks:
    custom_transform:
      notebook_path: ./notebooks/prepare_movie_features.py
      task_key: prepare_movie_features
      output_table: workspace.cf_movie_tmp.movie_feature_engineering_output

O adaptador gera artefatos de revisao e conecta o notebook como pre-task no Databricks Asset Bundle. Depois, o runtime ContractForge le a tabela de saida declarada e aplica esquema, qualidade, modo de escrita, evidencia e versionamento de deploy normalmente.

Veja o exemplo movie custom transform para um projeto bronze-to-gold completo baseado no shape de dados movies/ratings ja testado.

Referências de tabela lógica

Quando um contrato Databricks lê uma tabela produzida por outro ContractForge contrato, prefira o ref portátil em vez de codificar o nome Unity Catalog:

source:
  type: table
  ref: bronze.b_products_jdbc

Para SQL:

FROM {{ table_ref:silver.s_product_tags }}

O adaptador Databricks resolve isso para a nomenclatura de catálogo/esquema de destino usada pelo projeto. AWS resolve as mesmas referências para nomes do Catálogo Glue/Iceberg.

Exemplo de tempo de execução

from contractforge_databricks import ingest_databricks_bundle

result = ingest_databricks_bundle(
    "/Workspace/Shared/contracts/silver/s_customers",
    options={
        "catalog": "main",
        "schema": "ops",
        "notebook_name": "jobs/silver/s_customers",
    },
)

O adaptador cria tabelas de controle quando elas não existem, grava a tabela de destino, aplica anotações/operações/comportamento de acesso disponíveis e registra evidências antes de retornar o resultado.

Implantação

A implantação do Databricks pertence ao adaptador e é baseada no DAB. O núcleo não é implantado jobs e não importa SDKs Databricks.

contractforge-databricks deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml \
  --profile dbc-dev \
  --target dev

Adicione --run para executar o trabalho do pacote implementado:

contractforge-databricks deploy-project examples/real-world/supabase-jdbc-medallion/project.yaml \
  --profile dbc-dev \
  --target dev \
  --run

Para projetos sem project.yaml, aponte diretamente para o diretório DAB ou databricks.yml:

contractforge-databricks deploy-bundle ./databricks.yml --profile dbc-dev --target dev --run

O comando do projeto lê validation.databricks.bundle de project.yaml. Se esse campo estiver ausente, o padrão será databricks.yml ao lado do projeto arquivo. O adaptador chama Databricks CLI com argumentos explícitos; isso nunca constrói strings de comando do shell.

Agendamento do projeto

O agendamento pertence ao project.yaml, não ao contrato de ingestão. O o contrato diz o que significa um conjunto de dados; o projeto diz como são os jobs na plataforma connected.

schedule:
  cron: "0 6 * * *"
  timezone: America/Sao_Paulo
  enabled: false
  max_concurrent_runs: 1
  queue: true
  adapters:
    databricks:
      pause_status: PAUSED
      tasks:
        bronze_orders:
          task_key: bronze_orders

execution_order:
  - name: bronze_orders
    contracts:
      databricks: contracts/databricks/bronze_orders.ingestion.yaml
  - name: silver_orders
    depends_on: [bronze_orders]
    contracts:
      databricks: contracts/databricks/silver_orders.ingestion.yaml

Renderize um pacote de ativos Databricks a partir desses metadados:

contractforge-databricks render-project-bundle project.yaml \
  --output databricks.yml \
  --force

Ou renderize e implemente em um fluxo de propriedade do adaptador:

contractforge-databricks deploy-project project.yaml \
  --render-bundle \
  --force-render \
  --target dev

O renderizador mapeia dependências e mapas de tarefas depends_on para Databricks schedule.cron / schedule.timezone de nível superior para a programação de trabalhos Databricks bloquear. AWS mapeia o mesmo cronograma do projeto para o EventBridge Scheduler sem alterar contratos de ingestão.

Exemplos de revisão necessária

Databricks pode suportar muitas semânticas nativamente, mas algumas solicitações ainda precisam de revisão explícita:

Solicitação de contrato	Por que a revisão pode ser necessária
histórico em snapshots de origem não Delta	A completude e a semântica de exclusão devem ser comprovadas.
Row filters/masks	Os privilégios e a disponibilidade do recurso Unity Catalog variam de acordo com o espaço de trabalho.
Available-now streaming	Os locais de pontos de verificação e esquemas devem ser controlados e duráveis.
Conectores nativos Lakeflow	O comportamento específico da fonte é de propriedade do Databricks e pode não ser portátil.

O adaptador deve retornar diagnósticos de revisão em vez de ocultar essas decisões no código gerado.