Arquivos

estável

Use o conectores de arquivo por path para caminhos que o Spark pode ler diretamente: teste local caminhos, caminhos compatíveis com DBFS, volumes do Unity Catalog, locais externos e caminhos de nuvem montados.

Use-o quando a autenticação já for tratada pelo runtime. Use a nuvem conectores específicos (s3, azure_blob, gcs) quando o contrato deve declarar credenciais específicas da nuvem ou semântica de caminho.

Quando usar

Acesso gerenciado em runtime

Caminhos legíveis pelo Spark

Utilize este conector quando o runtime do Databricks já souber ler o caminho através de um volume, local externo, caminho montado, caminho compatível com DBFS ou caminho de teste local.

Aterrissagem multiformato

Formatos de arquivo Direct Spark

Use o mesmo formato de contrato para conectores diretos como CSV, JSON, Parquet, ORC, Delta e text. Use conectores de object storage com source.format para Avro, XML, JSONL e NDJSON quando o runtime suportar esses readers.

Armazenamento governado

Volumes e localizações externas

Prefira caminhos governados quando o acesso for controlado pelo Catálogo e credenciais do Unity não deve aparecer em contratos de ingestão.

Semântica específica da nuvem

Use conectores de provedor quando necessário

Use s3, azure_blob ou gcs quando o contrato deve declarar específico do provedor autenticação, semântica de caminho ou orientação de runtime.

Formatos suportados

Formatar	Valor do conector	Notas
CSV	csv	Use opções explícitas de cabeçalho, delimitador, cotação e esquema para ingestão estável.
JSON	json	O JSON multilinha deve ser explícito com as opções do leitor Spark.
Linhas JSON	source.format=jsonl ou ndjson com object_storage/conector de provedor	Recomendado para arquivos de eventos grandes.
Parquete	parquet	Preferido para arquivos lakehouse tipados.
Avro	source.format=avro com object_storage/conector de provedor	Requer suporte Avro no runtime.
ORC	orc	Compatível quando o runtime do Spark inclui ORC.
Delta	delta	Lê caminhos Delta diretamente.
Texto	text	Útil para pouso bruto ou análise personalizada.
XML	source.format=xml com object_storage/conector de provedor	Requer o pacote Spark XML ou suporte DBR dependendo do runtime.

Leitura de pasta

YAML

source:
  type: connector
  connector: parquet
  path: /Volumes/main/landing/orders
  options:
    recursiveFileLookup: true

Python

source = {
    "type": "connector",
    "connector": "parquet",
    "path": "/Volumes/main/landing/orders",
    "options": {"recursiveFileLookup": True},
}

CSV com esquema explícito

YAML

source:
  type: connector
  connector: csv
  path: /Volumes/main/landing/orders_csv/
  schema: "order_id STRING, customer_id STRING, amount DOUBLE, updated_at TIMESTAMP"
  options:
    header: true
    mode: FAILFAST

Python

source = {
    "type": "connector",
    "connector": "csv",
    "path": "/Volumes/main/landing/orders_csv/",
    "schema": "order_id STRING, customer_id STRING, amount DOUBLE, updated_at TIMESTAMP",
    "options": {"header": True, "mode": "FAILFAST"},
}

JSON e forma

Mantenha a análise JSON e a normalização estrutural explícitas. O esquema de origem descreve como o Spark lê o arquivo; transform.shape descreve como ContractForge se prepara colunas de negócios.

YAML

source:
  type: connector
  connector: json
  path: /Volumes/main/landing/orders_json/
  schema: "payload STRING, ingest_ts TIMESTAMP"

transform:
  shape:
    parse_json:
      payload:
        schema: "STRUCT<order_id: STRING, items: ARRAY<STRUCT<sku: STRING, qty: INT>>>"
        target: parsed
    flatten:
      - path: parsed
        prefix: ""

Python

source = {
    "type": "connector",
    "connector": "json",
    "path": "/Volumes/main/landing/orders_json/",
    "schema": "payload STRING, ingest_ts TIMESTAMP",
}

transform = {
    "shape": {
        "parse_json": {
            "payload": {
                "schema": "STRUCT<order_id: STRING, items: ARRAY<STRUCT<sku: STRING, qty: INT>>>",
                "target": "parsed",
            }
        },
        "flatten": [{"path": "parsed", "prefix": ""}],
    }
}

Avro, Parquet e XML

YAML

# Parquet

source:
  type: connector
  connector: parquet
  path: /Volumes/main/landing/orders_parquet/
  options:
    recursiveFileLookup: true

---

# Avro

source:
  type: connector
  connector: object_storage
  path: /Volumes/main/landing/orders_avro/
  format: avro

---

# XML

source:
  type: connector
  connector: object_storage
  path: /Volumes/main/landing/orders_xml/
  format: xml
  options:
    rowTag: order

Python

parquet_source = {
    "type": "connector",
    "connector": "parquet",
    "path": "/Volumes/main/landing/orders_parquet/",
    "options": {"recursiveFileLookup": True},
}

avro_source = {
    "type": "connector",
    "connector": "object_storage",
    "path": "/Volumes/main/landing/orders_avro/",
    "format": "avro",
}

xml_source = {
    "type": "connector",
    "connector": "object_storage",
    "path": "/Volumes/main/landing/orders_xml/",
    "format": "xml",
    "options": {"rowTag": "order"},
}

Opções do leitor

Opção	Caso de uso
recursiveFileLookup	Leia arquivos em pastas aninhadas sem depender da descoberta de partições.
pathGlobFilter	Restrinja nomes de arquivos usando padrões glob do Spark.
modifiedBefore / modifiedAfter	Filtragem de arquivos Spark quando compatível com o runtime.
mergeSchema	Leituras de evolução do esquema Parquet/Delta. Use com cuidado em pastas grandes.
multiline	Registros JSON ou CSV multilinhas.

Para correspondência avançada de nomes de arquivos que não podem ser representados pelo Spark glob padrões, use um processo de preparação ou um filtro futuro específico do conector. Não codificar a filtragem comercial na seleção do nome do arquivo quando ele pertencer filter_expression.