Pular para o conteúdo principal

AWS Capability Parity

Este documento registra os recursos nativos do AWS pesquisados ​​que devem informar o roteiro do adaptador contractforge-aws. Ele existe para evitar a subconstrução do adaptador AWS simplesmente porque um recurso não fazia parte de uma passagem de implementação anterior.

O adaptador deve buscar a semântica máxima de ContractForge que AWS pode preservar nativamente, enquanto ainda retorna REVIEW_REQUIRED ou UNSUPPORTED quando a equivalência semântica não for comprovada.

Tese Primária de Tempo de Execução​

O tempo de execução principal do AWS permanece:

AWS Glue Spark
Apache Iceberg
AWS Glue Data Catalog
Amazon S3
AWS Lake Formation
Iceberg evidence tables

Este alvo é capaz de mais do que revisar artefatos:

  • Glue oferece suporte a tabelas Apache Iceberg e gravações de DataFrame por meio do catálogo de dados Glue.
  • As tabelas Iceberg suportam padrões de adição, criação/substituição e mesclagem SQL/DataFrame por meio de Spark.
  • O Glue Data Quality fornece DQDL e uma transformação PySpark EvaluateDataQuality.
  • Os filtros de dados Lake Formation suportam controles de acesso em nível de coluna, nível de linha e nível de célula para operações de leitura.
  • Os marcadores de trabalho Glue fornecem rastreamento de origem incremental para JDBC e formatos S3 selecionados.
  • Os conectores nativos e personalizados do Glue fornecem um destino de passagem nativo melhor do que escrever o código do conector SaaS dentro do ContractForge.

Matriz de paridade de tempo de execução​

ContractForge areaCapacidade nativa do AWSAdapter target statusImplementation direction
appendIceberg append through Glue Spark/DataFrame writerSUPPORTEDScript de tempo de execução gerado. Se a tabela de destino não existir, o trabalho a inicializa a partir do dataframe preparado antes de futuras execuções de acréscimos e aplica extensions.aws.iceberg.table_properties nesse caminho de criação. Mantenha a versão do formato da tabela e a configuração do catálogo explícitas.
overwriteIceberg criar/substituir ou substituir padrõesSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado com criação/substituição hoje e aplica extensions.aws.iceberg.table_properties; adicione substituição com reconhecimento de partição/escopo antes de reivindicar paridade total de produção.
upsertSpark SQL MERGE INTO against IcebergSUPPORTEDScript de tempo de execução gerado com proteções de chave de mesclagem. Se a tabela de destino não existir, o trabalho inicializa-a a partir do dataframe preparado e aplica extensions.aws.iceberg.table_properties antes de execuções futuras do MERGE. Precisa de teste de integração AWS para simultaneidade e grandes volumes de upsert.
hash_diff_upsertHash staging plus Iceberg mergeSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado: mescla merge_keys, calcula row_hash de hash_keys ou hash_strategy: all_columns_except, exclui colunas declaradas e geradas pelo usuário, pré-filtra linhas inalteradas antes de Iceberg MERGE e registra execuções sem alteração como SKIPPED/no_hash_changes. Se a tabela de destino não existir, o trabalho a inicializa a partir do dataframe preparado e aplica extensions.aws.iceberg.table_properties. O aviso de desempenho/simultaneidade permanece até ser validado no Glue.
historicalIceberg merge/history patternREVIEW_REQUIREDDatações viáveis, mas eficazes, exclusões, políticas de chegada tardia e escritores simultâneos precisam de testes AWS explícitos.
snapshot_reconcile_soft_deleteFull snapshot reconciliation plus Iceberg mergeREVIEW_REQUIREDViável somente quando a integridade da fonte e a simultaneidade do alvo forem comprovadas.
required_columnsQualidade de dados Glue ColumnExists via EvaluateDataQualitySUPPORTEDAvaliado nativamente no trabalho; A gravidade do abort falha na execução, os resultados persistem para ctrl_ingestion_quality.
not_nullQualidade de dados Glue IsComplete via EvaluateDataQualitySUPPORTED_WITH_WARNINGSAvaliado nativamente; As regras warn registram evidências de qualidade e continuam; As regras quarantine em nível de linha gravam linhas incorretas em ctrl_ingestion_quarantine, descartam-nas antes da gravação de destino e atualizam as contagens de quarentena da execução.
unique_keyQualidade de dados Glue IsUnique/IsPrimaryKey via EvaluateDataQualitySUPPORTEDAvaliado nativamente no trabalho; A gravidade do abort falha na execução, os resultados persistem para ctrl_ingestion_quality.
accepted_valuesQualidade de dados Glue ColumnValues... in [...] via EvaluateDataQualitySUPPORTED_WITH_WARNINGSAvaliado nativamente; resultados não abortivos registram evidências de qualidade. quarantine em nível de linha grava linhas incorretas em ctrl_ingestion_quarantine, descarta-as antes da gravação de destino e as atualizações executam contagens de quarentena.
max_null_ratioLimite Glue de qualidade de dados Completeness via EvaluateDataQualitySUPPORTED_WITH_WARNINGSAvaliado nativamente; Resultados warn registrados como evidência de qualidade.
Qualidade expressionSpark SQL DataFrame filter checksSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado fora do DQDL porque o dialeto da expressão é Spark SQL. abort falha na execução; warn registra evidências; quarantine em nível de linha grava linhas incorretas e as filtra antes da gravação de destino.
select_columnsSpark DataFrame projectionSUPPORTEDScript de tempo de execução gerado.
column_mappingSpark DataFrame renameSUPPORTEDScript de tempo de execução gerado com verificações de colisão.
filter_expressionSpark SQL/DataFrame filterSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado; O dialeto da expressão é Spark SQL, portanto, filtros complexos de plataforma cruzada podem precisar de revisão.
shape.parse_jsonSpark from_json e estruturas de esquemaSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado para esquemas concretos (e schema_ref resolvido), com cast_input: STRING e drop_source opcionais.
shape.arrays.explodeSpark explode functionsSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado para todos os modos (size/to_json/first/explode/explode_outer). explode/explode_outer são bloqueados em bronze, a menos que allow_cardinality_change_on_bronze; irmão explode sob a necessidade de um dos pais allow_cartesian.
shape.zip_arraysSpark arrays_zip plus transform field renamingSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado com colunas de matriz temporárias para que os caminhos aninhados mantenham nomes de campos de estrutura determinísticos.
transform.castSpark DataFrame castsSUPPORTEDImplement in AWS renderer before broad transform support.
transform.standardizeSpark string functionsSUPPORTEDImplement trim/lower/upper/whitespace/null normalization.
transform.deriveSpark SQL expressionsSUPPORTED_WITH_WARNINGSViável; o dialeto da expressão deve ser Spark SQL.
transform.composite_keysSpark concat/coalesce functionsSUPPORTEDUsa Spark concat_ws/coalesce com a semântica do delimitador do contrato principal.
transform.deduplicateSpark window/groupingSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado: Window.partitionBy(keys).orderBy(order_by) + row_number() == 1. order_by é exigido pelo contrato principal (determinístico); list-of-dicts e cláusulas simples de string de coluna são renderizadas, enquanto strings SQL de forma livre e inseguras tornam-se apenas para revisão.
shape.flattenIntrospecção do esquema Spark + seleçãoSUPPORTED_WITH_WARNINGSRenderiza um auxiliar _cf_flatten de tempo de execução que expande campos de estrutura para colunas folha com o separador/incluir/excluir/max_depth do contrato (matrizes mantidas intactas). O Relationalize nativo do Glue não é usado porque ele dinamiza matrizes em quadros separados com nomenclatura fixa.
shape.columnsSpark select projectionSUPPORTEDScript de tempo de execução gerado: a abreviação de string mapeia um caminho para um alias; o formato do objeto suporta expression (Spark SQL), cast e alias.
incremental_filesMarcadores de trabalho Glue para formatos S3 selecionados ou estado de evidênciaSUPPORTED_WITH_WARNINGSRenderiza um marcador S3 create_dynamic_frame.from_options lido com transformation_ctx para JSON/CSV/Parquet/ORC/Avro/XML. As opções CSV portáteis são traduzidas para opções Glue DynamicFrame (header -> withHeader, delimiter -> separator) e opções somente Spark, como inferSchema, não são passadas para leituras de marcadores Glue. enable_job_bookmark conecta --job-bookmark-option. Os formatos não suportados permanecem apenas para revisão.
JDBC incrementalMarcadores de trabalho Glue para chaves de marcadores JDBCSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado quando source.incremental.watermark_column é uma coluna simples e o JDBC URL/conector é mapeado para um tipo de conexão Glue JDBC; caso contrário, ele retornará ao leitor Spark JDBC mais aos predicados/estado de evidência da marca d'água principal.
evidência estadualIceberg state tables in Glue CatalogSUPPORTED_WITH_WARNINGSOs trabalhos Glue gerados atualizam o ctrl_ingestion_state após gravações confirmadas com ID de execução, status, linhas gravadas, ID de instantâneo Iceberg e candidatos de marca d'água em lote quando a coluna de marca d'água declarada existe no DataFrame preparado. O progresso do ponto de verificação de streaming é rastreado no ctrl_ingestion_streams.
evidência de mudança de esquemaTabela de alteração de esquema Iceberg no catálogo GlueSUPPORTED_WITH_WARNINGSAs tarefas Glue geradas comparam o esquema da tabela de destino antes/depois da gravação, acrescentam colunas adicionadas e linhas de alteração de tipo ao ctrl_ingestion_schema_changes e copiam o resumo na evidência de execução. Decisões complexas de políticas de esquema ainda exigem revisão.
kafka_bounded / eventhubs_boundedSpark bounded Kafka/Event Hubs read in GlueSUPPORTED_WITH_WARNINGSScript de tempo de execução gerado; os jars do conector Spark correspondentes devem ser fornecidos e a semântica de deslocamento/intervalo permanece de propriedade do conector.
kafka_available_now / eventhubs_available_nowStreaming estruturado Glue com o gatilho availableNowSUPPORTED_WITH_WARNINGSRenderiza um trabalho readStream + writeStream.foreachBatch com trigger(availableNow=True) e o checkpoint_location do contrato; preparação/qualidade/gravação executada por microlote para modos de acréscimo/mesclagem. A evidência por lote é gravada no ctrl_ingestion_streams e transformada na evidência de execução final. Valide o progresso do deslocamento/ponto de verificação antes da produção.
row filtersLake Formation data filtersREVIEW_REQUIREDRenderiza uma estrutura CreateDataCellsFilter (expressão de linha false com falha fechada) mais uma concessão SELECT no filtro; a função de filtro de linha não pode ser traduzida automaticamente para um LF FilterExpression, portanto, um revisor a conclui. O planejamento permanece REVIEW_REQUIRED.
column masksLake Formation column/cell filtersREVIEW_REQUIREDRenderiza uma estrutura de filtro de células de dados que exclui a coluna mascarada (segurança em nível de coluna); LF não tem função de mascaramento de valor, portanto, um valor transformado deve vir do trabalho de ingestão ou de uma visão do consumidor. O planejamento permanece REVIEW_REQUIRED.
concessões de acessoConcessões Lake Formation e políticas IAMSUPPORTED_WITH_WARNINGSrender_aws_lake_formation_plan emite solicitações GrantPermissions aplicáveis ​​(.lakeformation.json), além de evidência ctrl_ingestion_access SQL. As permissões de função de trabalho de gravação são separadas das concessões ao consumidor.
anotaçõesAWS Glue Metadados de tabela/coluna do catálogoSUPPORTED_WITH_WARNINGSRenderiza .annotations.json com alterações planejadas de metadados glue:UpdateTable e .annotations_evidence.sql para ctrl_ingestion_annotations. A aplicação permanece explícita porque as atualizações da tabela Glue devem preservar o TableInput atual completo.
metadados de operaçõesTabela de evidências Iceberg no catálogo GlueSUPPORTEDRenderiza .operations.json e .operations.sql normalizados para ctrl_ingestion_operations, preservando proprietários, grupos, criticidade, SLA, sinalizadores de alerta, runbook e tags.
metadados/linhagem de origemGlue JobRun, metadados de esquema Spark, exportação OpenLineage opcionalSUPPORTED_WITH_WARNINGSAs tarefas Glue geradas persistem metadados de origem, leitura de linhas, contagem de colunas de origem e esquema de origem de tempo de execução para ctrl_ingestion_metadata e, em seguida, anexa eventos compatíveis com OpenLineage a ctrl_ingestion_lineage. Catálogo Glue O enriquecimento API continua sendo um trabalho futuro de propriedade do adaptador.
cost signalsGlue DPUSeconds, tipo/contagem de trabalhadores e duração do trabalhoSUPPORTEDA reconciliação mapeia Glue DPUSeconds em ctrl_ingestion_cost; *.cost.sql estima USD somente quando uma taxa explícita de DPU-hora é fornecida.
http_file (http_csv/json/text)Driver-side bounded fetch + Spark in-memory parseSUPPORTED_WITH_WARNINGSO auxiliar _cf_http_dataframe de tempo de execução valida o host resolvido (rejeita private/IMDS) e recusa redirecionamentos; segredos de autenticação são resolvidos por meio do Secrets Manager.
rest_apiCliente REST limitado por núcleo compartilhadoSUPPORTED_WITH_WARNINGSO trabalho Glue chama contractforge_core.connectors.read_rest_api_records (paginação/autenticação/limites, implementado em contractforge_core.connectors.api.rest); requer contractforge-core no trabalho. O cliente compartilhado valida URLs de token API e OAuth, rejeita esquemas/hosts privados não suportados por padrão e recusa redirecionamentos. Os segredos são resolvidos por meio do Secrets Manager.
delta_shareSpark Delta Sharing readerSUPPORTED_WITH_WARNINGSspark.read.format('deltaSharing'); forneça o jar delta-sharing-spark.
passagem nativaConectores nativos Glue, conectores personalizados, padrões AppFlow/DMSREVIEW_REQUIREDRenderiza .native_passthrough.json com recomendações nativas de AWS e candidatos em formato API somente de revisão para AppFlow CreateFlow, DMS CreateReplicationConfig e Glue CreateConnection. Não implemente algoritmos SaaS em ContractForge.

  1. Preparation parity

    • Keep transform.cast, transform.standardize, transform.derive, transform.composite_keys covered by AWS Glue script tests.
    • Adicione transform.deduplicate apenas com validação de ordem determinística. Concluído: a geração do tempo de execução requer keys e order_by e, em seguida, renderiza uma janela Spark e row_number() == 1.
    • Adicione shape.parse_json para esquemas concretos antes da explosão do array. Concluído: a geração de tempo de execução suporta esquemas concretos/schema_ref resolvido, cast_input: STRING opcional, matrizes, matrizes zip, colunas e nivelamento com guarda-corpos.

  2. Qualidade nativa AWS

    • Renderize artefatos DQDL para todas as regras de qualidade portáteis com equivalentes fiéis do DQDL. Concluído: render_aws_quality_dqdl emite um conjunto de regras Rules = [...] (artefato .quality.dqdl) mapeando required_columns/not_null/unique_key/accepted_values/row_count_minimum/max_null_ratio; As regras expression são avaliadas pelas verificações de tempo de execução Spark SQL em vez de DQDL.
    • Adicione um caminho de tempo de execução do Data Quality Glue (EvaluateDataQuality). Concluído: o trabalho avalia o conjunto de regras DQDL no trabalho, particionado por gravidade — as regras abort aumentam em caso de falha, as regras warn/quarantine continuam.
    • Persista os resultados do DQ nas tabelas de evidências ContractForge. Concluído: uma linha imutável por regra é anexada ao ctrl_ingestion_quality (_cf_persist_quality_evidence) compartilhando o _cf_run_id da execução.
    • Habilite o comportamento de tempo de execução de quarentena/aviso. Feito para regras de nível de linha mapeadas: regras de não interrupção são registradas e nunca falham na execução; As regras de quarentena not_null e accepted_values usam rowLevelOutcomes para gravar linhas incorretas em ctrl_ingestion_quarantine e filtrá-las antes da gravação de destino. Spark As regras de quarentena de expressão SQL usam filtros DataFrame para o mesmo comportamento de evidência. As regras de quarentena agregadas/esquemáticas permanecem apenas como evidências registradas.

  3. Incremental ingestion

    • Renderize a configuração do marcador Glue para fontes S3/JDBC elegíveis. Concluído: arquivos incrementais S3 e fontes incrementais JDBC elegíveis renderizam leituras de marcadores DynamicFrame e ativam o sinalizador de implantação de marcadores de trabalho.
    • Registre a estratégia incremental selecionada no estado/evidência.
    • Fallback para tabelas de estado ContractForge quando os marcadores não conseguem preservar a semântica.

  4. Governança

    • Gere filtro de dados Lake Formation e conceda artefatos. Concluído: render_aws_lake_formation_plan emite solicitações GrantPermissions e scaffolds CreateDataCellsFilter (.lakeformation.json).
    • Keep application behind explicit apply commands.
    • Registrar evidências de aplicação de governança.

  5. Modos de gravação avançados

    • Implemente hash_diff_upsert com preparação de propriedade do adaptador. Concluído: a geração em tempo de execução calcula um hash de linha compatível com o núcleo e mescla apenas as linhas alteradas.
    • Protótipo historical e snapshot_reconcile_soft_delete em testes de integração antes de alterar o status de planejamento.

  6. Passagem nativa

    • Adicione artefatos de conector nativo Glue para sistemas SaaS compatíveis.
    • Adicione artefatos de revisão/aplicação do AppFlow/DMS onde esses serviços preservam a intenção do contrato melhor do que o código Glue.

Known AWS Constraints To Preserve​

  • Os filtros Lake Formation aplicam-se ao acesso de leitura. Eles não são a mesma coisa que rejeição de linha no tempo de gravação ou funções de tabela do lado do mecanismo.
  • Os marcadores de trabalho Glue rastreiam o progresso da origem; eles não limpam ou reconciliam os dados de destino durante o retrocesso/redefinição.
  • Os marcadores JDBC dependem de chaves de marcadores adequadas e não suportam colunas de marcadores que diferenciam maiúsculas de minúsculas.
  • O Glue Data Quality pode avaliar conjuntos de regras avançados, mas a quarentena em nível de linha ContractForge só é habilitada onde Glue rowLevelOutcomes pode identificar linhas incorretas sem alterar a semântica da regra.
  • O suporte ao Iceberg varia de acordo com a versão do Glue. O adaptador deve manter a versão Glue na configuração e evidência de tempo de execução.
  • AWS As dependências SDK ficam fora do caminho de importação do adaptador base. Os auxiliares de tempo de execução podem usar contractforge-aws[runtime] ou clientes fornecidos pelo chamador.

Official References​