s3 / minio¶

fonte

lê arquivos do seu próprio bucket s3 ou minio — parquet, csv, json ou excel. use este conector quando os dados de origem já existem como arquivos em um object storage que você controla (exports de sistemas, dumps de terceiros, arquivos entregues por parceiros).

quando usar¶

ler exports periódicos que um sistema legado deposita em um bucket (csv, excel)
consumir arquivos parquet entregues por um parceiro de dados ou por outra área da empresa
processar uma pasta inteira de arquivos que chegam com nomes previsíveis (ex: vendas_2024-01-01.csv, vendas_2024-01-02.csv, ...) sem reprocessar o que já foi lido

formatos suportados¶

formato	observações
`parquet`	mais eficiente — leitura colunar direta
`csv`	detecção automática de schema e cabeçalho
`json`	suporta tanto arquivos de array quanto envelope com campo de registros aninhado
`excel`	suporta leitura de múltiplos arquivos combinados em um único dataset

configuração¶

campo	tipo	obrigatório	descrição
`bucket`	string	não	nome do bucket · padrão: bucket do lakehouse do workspace
`key`	string	sim	caminho do arquivo no bucket. suporta `{{variavel}}` e padrões glob (`*`, `?`, `[...]`)
`file_format`	enum	não	`parquet`, `csv`, `json`, `excel` · padrão: `parquet`
`csv_delimiter`	string	não	delimitador para csv · padrão: `,`
`json_records_field`	string	não	quando o json é um envelope (`{"data": [...]}`), informe o campo que contém a lista de registros
`incremental`	bool	não	quando `true` e `key` é um padrão glob, pula arquivos já lidos em execuções anteriores

leitura de múltiplos arquivos (glob)¶

quando key contém um padrão glob (ex: exports/vendas/*.csv), todos os arquivos que casam com o padrão são lidos e combinados em um único dataset — mesmo que tenham colunas ligeiramente diferentes entre si (colunas ausentes em um arquivo recebem null).

{
  "bucket": "meu-bucket",
  "key": "exports/vendas/*.parquet",
  "file_format": "parquet"
}

extração incremental por arquivo novo¶

com incremental: true, cada execução do pipeline lê apenas os arquivos criados/modificados depois da última execução — útil para pastas onde novos arquivos chegam periodicamente (ex: vendas_YYYY-MM-DD.csv depositado todo dia):

{
  "bucket": "meu-bucket",
  "key": "exports/vendas/vendas_*.csv",
  "file_format": "csv",
  "incremental": true
}

não é cdc

o rastreamento incremental é feito pela data de modificação do arquivo no bucket — não olha o conteúdo interno do arquivo. se um arquivo já lido for sobrescrito com dados novos mas sem atualizar sua data de modificação, ele não será relido automaticamente.

exemplos¶

ler parquet de um caminho fixo¶

{
  "key": "exports/clientes/2024-01/data.parquet",
  "file_format": "parquet"
}

quando bucket não é informado, o conector usa o bucket do lakehouse padrão do workspace.

ler csv com ponto-e-vírgula¶

{
  "bucket": "meu-bucket-externo",
  "key": "uploads/vendas_2024.csv",
  "file_format": "csv",
  "csv_delimiter": ";"
}

caminho dinâmico com variável¶

{
  "key": "exports/{{entidade}}/{{ano}}-{{mes}}/data.parquet",
  "file_format": "parquet"
}

se as variáveis de pipeline entidade=clientes, ano=2024, mes=01 estiverem configuradas, o caminho resolvido será exports/clientes/2024-01/data.parquet.

ler json com envelope de registros¶

{
  "bucket": "dados-raw",
  "key": "api-dumps/produtos.json",
  "file_format": "json",
  "json_records_field": "data"
}

quando o arquivo tem a forma {"data": [{...}, {...}]}, json_records_field: "data" extrai a lista de registros automaticamente.

ler excel¶

{
  "bucket": "uploads",
  "key": "relatorios/relatorio_mensal.xlsx",
  "file_format": "excel"
}

excel é mais custoso

arquivos excel são baixados por completo antes da leitura (diferente de parquet/csv, que são lidos de forma mais eficiente). para volumes grandes e recorrentes, prefira que a fonte já entregue os dados em csv ou parquet.

consumindo dados de outro pipeline¶

dados já governados por um pipeline DataBlixt (camada bronze/silver/gold) não devem ser lidos por este conector — use o lakehouse reader, que resolve automaticamente a tabela e a camada certas sem que você precise conhecer o caminho físico do arquivo.