Adaptador Snowflake

O adaptador Snowflake é o terceiro adaptador ContractForge. Tem como alvo o Snowflake SQL warehouse como superfície de tempo de execução, mapeando a intenção do contrato em SQL nativo do Snowflake, tabelas de evidências, operações de governança e implantação artefatos.

O adaptador não é uma abstração Snowflake genérica. É um conjunto de explícitos Sub-alvos Snowflake, cada um com capacidades declaradas e limites de revisão.

Status atual: superfície estável com suporte para fontes de tabela, fontes SQL, fontes REST API limitadas, arquivos preparados, modos de gravação, qualidade, política de esquema, governança, estado/idempotência, evidência, reconciliação de custos, linhagem, projeto artefatos de implantação e o executor da biblioteca de procedimentos Snowpark hospedado em snowflake_sql_warehouse. O benchmark hash-diff de referência e a execução ao vivo do gráfico de tarefas são validados. historical/snapshot soft delete, continuous ingestion surfaces such as Snowpipe, Streams, Snowpipe Streaming e ingestão de conector Kafka e o acesso à linha dependente do recurso da conta ou a aplicação da política de mascaramento são excluídos de stable-final onde a conta Snowflake conectada não fornece esses recursos de política nativa.

A porta de liberação para esta superfície apoiada é rastreada em Critérios de superfície estável Snowflake, o Registro de isenção Snowflake e o Snowflake stabilization matrix.

O modelo de execução padrão é o padrão executor de biblioteca. Contratos e ambientes são publicados como artefatos JSON de tempo de execução em um Snowflake interno estágio. O executor carrega esses artefatos por meio do conector Snowflake, renderiza o corpo Snowflake SQL revisado com o mesmo renderizador do adaptador e o executa na sessão Snowflake ativa.

Alvo Inicial

Area	Decision
Subtarget	snowflake_sql_warehouse
Tempo de execução	Snowflake SQL warehouse
Formato de tabela	Tabelas nativas Snowflake
Storage	Snowflake managed storage
Catalog	Banco de dados/esquema Snowflake
Governança	Tags Snowflake, comentários, políticas de acesso a linhas, políticas de mascaramento
Evidência	ContractForge control tables in Snowflake
Implantação	Tarefas que chamam o procedimento do executor estável

Pontos de entrada de tempo de execução

O adaptador fornece um único caminho de execução de tempo de execução estável através do library runner.

contractforge-snowflake run \
  --contract-uri @CONTRACTFORGE_ARTIFACTS/dev/runtime/ANALYTICS.BRONZE_ORDERS.contract.json \
  --environment-uri @CONTRACTFORGE_ARTIFACTS/dev/runtime/ANALYTICS.BRONZE_ORDERS.environment.json \
  --connect-options connection.yaml

contractforge-snowflake run \
  --contract-uri contracts/bronze/orders/orders.contract.yaml \
  --dry-run

O runner:

1. carrega os artefatos do contrato e do ambiente do estágio ou do sistema de arquivos local;
2. renderiza fonte SQL, preparação, qualidade, política de esquema, gravação SQL e evidência DDL para o dialeto Snowflake;
3. executa as operações renderizadas em ordem por meio de uma sessão do conector Snowflake;
4. execução de registros, erro, qualidade, quarentena, alteração de esquema, estado, anotação, acesso, operações, linhagem e explicar evidências.

Sources

O registro de origem Snowflake suporta tabela, visualização, expressão SQL, expressão limitada REST API e fontes de arquivos temporários. A detecção do formato do arquivo é conservadora: o o adaptador requer um objeto de formato de arquivo nomeado Snowflake; formato de arquivo embutido definições não são permitidas porque dificultam a validação da sintaxe.

Fonte	Planner	Tempo de execução
table e view	SUPPORTED	SELECT * FROM <qualified>
sql / query	SUPPORTED	Executa o SQL fornecido após remover os pontos e vírgulas finais
rest_api	SUPPORTED	Usa o cliente REST principal compartilhado e materializa registros limitados em uma tabela de origem Snowflake temporária
staged_files com CSV, JSON, Parquet	SUPPORTED para formatos de arquivo nomeados	SELECT... FROM @stage com projeções posicionais ou tipadas
staged_files com formatos não suportados	REVIEW_REQUIRED	Blocked
autoloader	UNSUPPORTED	Blocked
kafka	UNSUPPORTED	Blocked

A execução do procedimento hospedado Snowflake para rest_api requer acesso externo integração que permite o host HTTPS de destino. Para o exemplo USGS isto é CF_USGS_REST_ACCESS allowing earthquake.usgs.gov:443.

Configuração mínima de conta para o exemplo USGS REST não autenticado:

USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE NETWORK RULE CONTRACTFORGE_TEST_DB.PUBLIC.CF_USGS_REST_RULE
  TYPE = HOST_PORT
  MODE = EGRESS
  VALUE_LIST = ('earthquake.usgs.gov:443');

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION CF_USGS_REST_ACCESS
  ALLOWED_NETWORK_RULES = (CONTRACTFORGE_TEST_DB.PUBLIC.CF_USGS_REST_RULE)
  ALLOWED_AUTHENTICATION_SECRETS = none
  ENABLED = TRUE;

GRANT USAGE ON INTEGRATION CF_USGS_REST_ACCESS
TO ROLE CONTRACTFORGE_INGEST_ROLE;

Se a função de serviço criar a integração em vez de ACCOUNTADMIN, ela também precisa de USAGE em CONTRACTFORGE_TEST_DB.PUBLIC.CF_USGS_REST_RULE e CREATE EXTERNAL ACCESS INTEGRATION on the account. Use ALLOWED_AUTHENTICATION_SECRETS = none for unauthenticated REST; (none) is parsed as a secret identifier in some Snowflake accounts.

As fontes de arquivos preparadas aceitam columns como uma lista (CSV posicional) ou um mapeamento (JSON/Parquet $1:field::TYPE projections). Unsafe stage paths containing .. ou caracteres fora do conjunto de identificadores de estágio serão rejeitados.

Modos de gravação

Modo	Planner	Tempo de execução
append	SUPPORTED	INSERT INTO <target> SELECT * FROM (<source>)
overwrite	SUPPORTED	CREATE OR REPLACE TABLE <target> AS SELECT * FROM (<source>)
upsert	SUPPORTED	MERGE INTO <target> USING (<source>) ON <merge_keys> WHEN MATCHED THEN UPDATE WHEN NOT MATCHED THEN INSERT
hash_diff_upsert	SUPPORTED_WITH_WARNINGS	Calcule HASH em colunas não mescladas e não excluídas e, em seguida, MERGE somente em linhas alteradas

A validação de simulação de chave de mesclagem é executada para upsert e hash_diff_upsert: chaves de mesclagem nulas e chaves de mesclagem duplicadas na visualização de origem rejeitam a execução antes de qualquer tentativa de gravação.

Política de esquema

A política de esquema é aplicada por meio de INFORMATION_SCHEMA.COLUMNS quando conectado, recorrendo aos metadados do conector. As políticas padrão são suportadas:

• additive_only: novas colunas são adicionadas com ADD COLUMN IF NOT EXISTS.
• strict: qualquer diferença de coluna entre origem e destino rejeita a execução.
• permissive: ignores column mismatches.

Alterações de tipo incompatíveis (por exemplo, VARCHAR para NUMBER) rejeitam a execução independentemente da política.

A evidência de alteração de esquema é registrada em ctrl_ingestion_schema_changes.

Qualidade

Rule	Planner	Tempo de execução
not_null	SUPPORTED	SELECT COUNT(*) WHERE <column> IS NULL
required_columns	SUPPORTED	Column existence check
accepted_values	SUPPORTED	SELECT COUNT(*) WHERE <column> NOT IN (...)
min_rows	SUPPORTED	Row count check
unique_key	SUPPORTED	SELECT COUNT(*) ... GROUP BY <key> HAVING COUNT(*) > 1
max_null_ratio	SUPPORTED	Null ratio calculation
Row-level expression	SUPPORTED_WITH_WARNINGS	Expression evaluated in a Snowflake SQL WHERE clause

A quarentena agregada sem um predicado de linha é rejeitada. As linhas em quarentena são gravado em uma tabela de quarentena com o ID de execução. A evidência de qualidade é registrada em ctrl_ingestion_quality e ctrl_ingestion_quarantine.

Preparation

As transformações de preparação compatíveis com SQL são suportadas:

• Seleção e projeção de colunas.
• cast: renderiza CAST(<column> AS <type>) com SELECT * REPLACE.
• derive: renderiza a expressão compatível com Snowflake.
• standardize: TRIM, LOWER, NULLIF(..., '').
• Filters: rendered as a WHERE clause.
• Deterministic deduplicate: QUALIFY ROW_NUMBER() OVER (PARTITION BY <keys> ORDER BY <order>) = 1.

Complex nested shapes (parse_json, array explosions) remain REVIEW_REQUIRED until live-tested.

Governança

Anotações

• Os comentários de tabelas e colunas são aplicados diretamente.
• As tags Snowflake são renderizadas quando existem objetos de tag. Nomes de tags totalmente qualificados such as GOVERNANCE.PUBLIC.DOMAIN produce deterministic live apply.
• annotation_tag_mode: validate_only valida a intenção da tag e registra evidências sem executar DDL.
• A evidência de anotação é registrada em ctrl_ingestion_annotations.

A política de erros de anotação controla se tags ou comentários inválidos interrompem a execução:

extensions:
  snowflake:
    annotation_failure: warn
    annotation_tag_mode: validate_only

Acesso

• O planejamento de subsídios validate_only registra os subsídios pretendidos em ctrl_ingestion_access sem executar DDL.
• A política de acesso de linha SQL e a política de mascaramento SQL são renderizadas a partir do contrato declarations.
• Destructive revokes are gated as REVIEW_REQUIRED.

Estado, idempotência e marcas d'água

• O último estado de sucesso é persistido para cada execução com metadados de origem e watermark values.
• Os candidatos à marca d’água são calculados a partir de MAX(order_column) na página visualização da fonte.
• A filtragem anterior de marca d'água ignora linhas já processadas em execuções anteriores usando evidências do estado.
• A pesquisa de idempotência verifica ctrl_ingestion_runs para replays bem-sucedidos e skips already-completed runs.
• A aquisição e liberação de bloqueio opt-in protegem contra execução simultânea.

Despejo e recall

O adaptador registra a superfície de evidência ContractForge padrão no Snowflake tabelas de controle no esquema de evidência configurado:

Tabela de controle	Content
ctrl_ingestion_runs	Execute identidade, status, métricas, metadados de origem/destino
ctrl_ingestion_errors	Error message, redacted stack trace, run reference
ctrl_ingestion_quality	Resultados e status da avaliação de qualidade por regra
ctrl_ingestion_quarantine	Linhas em quarentena com ID de execução e referência de regra
ctrl_ingestion_schema_changes	Colunas adicionadas/removidas/alteradas com tipos
ctrl_ingestion_annotations	Comentários, tags, status aplicado/somente validação
ctrl_ingestion_access	Concessões, políticas, status somente validado ou aplicado
ctrl_ingestion_state	Last success watermark, idempotency key, run reference
ctrl_ingestion_operations	Intenção de operações e status aplicado
ctrl_ingestion_lineage	Eventos de linhagem de origem para destino com metadados OpenLineage
ctrl_ingestion_explain	Saída EXPLAIN USING TEXT para operações de gravação
ctrl_ingestion_cost	Histórico de consultas e sinais de atribuição do uso da conta

Todos os identificadores da tabela de controle são citados para proteger palavras reservadas. Banco de dados e bootstrap do esquema é aditivo: CREATE DATABASE IF NOT EXISTS e CREATE SCHEMA IF NOT EXISTS são ignorados quando o banco de dados ou esquema já existe, então service-role deployments avoid unnecessary failures.

Cost Reconciliation

A reconciliação de custos usa o comando canônico cost-report documentado em Adaptador CLI. As opções específicas do Snowflake incluem o ID de execução, destino tabela, opções de conexão e pesquisa limitada para latência de uso da conta.

A reconciliação:

1. investiga QUERY_HISTORY por QUERY_TAG estruturado contendo o ID de execução;
2. registra sinais de histórico de consultas e sinais opcionais de atribuição de consultas;
3. retorna PENDING quando a latência de uso da conta atrasa a disponibilidade da linha;
4. exclui sinais de custo anteriores de propriedade do adaptador antes de inserir novos.

O sinalizador --wait pesquisa até que as linhas apareçam ou um tempo limite seja atingido.

Lineage

Two lineage paths are available:

1. Linhagem imediata (ctrl_ingestion_lineage): escrita durante o tempo de execução execução com origem, destino, id de execução e metadados compatíveis com OpenLineage.
2. Reconciliação atrasada (ctrl_ingestion_lineage de ACCESS_HISTORY): reconciliável posteriormente por meio do CLI quando a latência de uso da conta permitir.

contractforge-snowflake reconcile-lineage \
  --run-id "ANALYTICS.BRONZE_CUSTOMERS:abc123" \
  --wait --max-wait-seconds 3600

A saída EXPLAIN USING TEXT para instruções de gravação é gravada em ctrl_ingestion_explain.

Implantações de projetos

O adaptador pode implementar e executar gráficos de tarefas a partir de arquivos de projeto usando o comandos canônicos deploy-project e run-project documentados em Adaptador CLI. cleanup-plan continua sendo específico do Snowflake non-destructive helper.

Os artefatos de implantação incluem:

• Procedimento de runner estável CREATE OR REPLACE PROCEDURE.
• Gráfico de tarefas CREATE TASK para execução agendada ou orientada por dependência.
• Pesquisa de histórico de tarefas para run-project --wait.

O procedimento live smoke foi aprovado com o executor da biblioteca Snowpark hospedado. Tarefa A smoke ao vivo do gráfico também passou com a execução e limpeza de tarefas raiz/dependentes.

Smoke Tests

O comando canônico smoke valida o adaptador em relação a um Snowflake real account. Additional Snowflake-specific smoke variants cover failure paths, publicação de estágio, execução de procedimento hospedado e gráficos de tarefas.

Cada comando smoke tem como padrão objetos não destrutivos com prefixo CF_SMOKE_*. O sinalizador --execute-cleanup é necessário antes da execução de qualquer instrução DROP.

Validação ao vivo

Validação recente ao vivo do Snowflake coberta:

Scenario	Status	Notes
smoke-procedure	PASS	O procedimento Snowpark hospedado importou bibliotecas de núcleo/adaptador empacotadas com ZIP e gravou 2 linhas; ID de consulta de procedimento 01c4ea61-0001-6b57-0001-084600149952.
smoke-task-graph	PASS	O gráfico de tarefas ao vivo implantou duas tarefas, executou a tarefa raiz, esperou pelos estados SUCCEEDED de bronze/prata, verificou contagens de bronze/prata de 2 linhas e limpou artefatos de smoke.
USGS GeoJSON REST medallion	LOCAL PASS	O projeto de exemplo agora declara contratos Snowflake bronze-ouro ao lado dos contratos Databricks e AWS, com Snowflake bronze usando o mesmo contrato source.type: rest_api URL/method/raw response. Os testes de tempo de execução local executam os contratos Snowflake declarados na ordem do projeto. A execução do procedimento hospedado ao vivo requer CF_USGS_REST_ACCESS na conta Snowflake.

Instalação e dependências

pip install contractforge-core contractforge-snowflake

Conexão de tempo de execução:

pip install contractforge-snowflake[runtime]

Snowpark procedure support (optional):

pip install contractforge-snowflake[snowpark]

O adaptador não importa o conector Snowflake ou Snowpark SDK por padrão importar. As dependências de tempo de execução são ativadas preguiçosamente por meio do [runtime] e [snowpark] extras.

Comparação com outros adaptadores

Área	Databricks	AWS	Snowflake
Tempo de execução	Spark direto no workspace	Glue Spark	Procedimento armazenado Snowpark e SQL
Formato de tabela	Delta	Apache Iceberg	Snowflake nativo
Implantação	Asset Bundles	Jobs Glue implantados via boto3	Pacote preparado importado pelo procedimento de runner estável
Governança	Unity Catalog	Lake Formation	Tags, comentários, políticas de acesso a linhas, políticas de mascaramento
Evidência	Tabelas Delta por padrão	Tabelas Iceberg	Tabelas de controle Snowflake
Paridade de origem	Autoloader, arquivos, JDBC, REST, passagem nativa	S3 files, JDBC, REST, HTTP file, incremental files	Tabelas/visualizações, SQL, REST limitado, arquivos preparados, revisão necessária para superfícies contínuas

Para obter orientação sobre paridade de ingestão lado a lado em Databricks, AWS e Snowflake, consulte Testar contratos entre adaptadores.

Roteiro e paridade

O status de paridade do adaptador é rastreado em:

• Especificação de paridade de capacidade Snowflake
• Plano de execução de paridade do adaptador Snowflake
• Snowflake stabilization matrix
• Critérios de superfície estável Snowflake
• Registro de isenção de superfície estável Snowflake

Continuous ingestion surfaces (copy_into, Snowpipe, Streams, Snowpipe Ingestão de conector de streaming e Kafka), funções de métrica de dados e a validação da política de acesso dependente de recursos da conta permanece fora do reivindicação final estável até um mapeamento de tempo de execução/evidência separado ou disponível o conjunto de recursos da conta é implementado e a validação ao vivo é concluída.