S3

validado

Use o connector S3 para paths s3a:// quando ContractForge declarar o source path e o formato. O runtime ainda determina como credenciais e acesso de rede são resolvidos.

Quando usar

AWS serverless

External Location ou Volume

Use storage governado pelo Unity Catalog quando o workspace Databricks roda na AWS e o compute serverless não deve receber credenciais S3A diretas.

Serverless cross-cloud

Localização externa ou política de rede

Use um caminho governado quando o workspace não roda na AWS ou quando credenciais diretas de filesystem são bloqueadas pela política da plataforma.

Classic cluster

Acesso S3A direto

Use chaves de acesso com escopo, tokens de sessão temporários, perfis de instância ou Hadoop AWS configuration quando o runtime do cluster permite configuração direta de S3A.

Papel do connector

Caminho, formato e evidência

Mantenha acesso ao objeto explícito em source; use transform e quality rules para normalização de negócio depois da leitura dos arquivos.

Orientação de runtime

Runtime	Caminho de acesso recomendado
Databricks serverless na AWS	Unity Catalog External Location ou Volume com backend S3.
Databricks serverless fora da AWS	External Location ou network policy, se suportada pelo workspace.
Classic cluster	Acesso direto s3a:// com Hadoop AWS configuration, instance profile ou scoped access keys.

Serverless é mais rígido por design. Se credenciais diretas não estiverem disponíveis para o Spark runtime, use uma External Location e aponte o connector para o Volume ou external path.

Pasta Parquet

YAML

source:
  type: connector
  connector: s3
  path: s3a://company-landing/orders/
  format: parquet
  options:
    recursiveFileLookup: true

Python

source = {
    "type": "connector",
    "connector": "s3",
    "path": "s3a://company-landing/orders/",
    "format": "parquet",
    "options": {"recursiveFileLookup": True},
}

Credenciais diretas em clusters clássicos

YAML

source:
  type: connector
  connector: s3
  path: s3a://company-landing/orders/
  format: json
  auth:
    type: access_key
    access_key_id: "{{ secret:contractforge-aws/aws_access_key_id }}"
    secret_access_key: "{{ secret:contractforge-aws/aws_secret_access_key }}"
    session_token: "{{ secret:contractforge-aws/aws_session_token }}"

Python

source = {
    "type": "connector",
    "connector": "s3",
    "path": "s3a://company-landing/orders/",
    "format": "json",
    "auth": {
        "type": "access_key",
        "access_key_id": "{{ secret:contractforge-aws/aws_access_key_id }}",
        "secret_access_key": "{{ secret:contractforge-aws/aws_secret_access_key }}",
        "session_token": "{{ secret:contractforge-aws/aws_session_token }}",
    },
}

session_token é necessário quando as credenciais da AWS são temporárias. Mantenha fichas de curta duração e armazena todos os valores em segredos do Databricks.

Opções

Opção	Propósito
recursiveFileLookup	Lê pastas aninhadas.
pathGlobFilter	Filtra nomes de arquivos usando a sintaxe glob do Spark.
mergeSchema	Permite a mesclagem de esquemas para formatos compatíveis.
header, delimiter, mode	Opções de análise de CSV.

Use filter_expression para filtragem de linha após leitura. Use opções de conector para comportamento apenas no nível do leitor.