Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-09-08

Tutorial — importar un archivo (CSV, JSON o Parquet)

Paso a paso para depositar un archivo en la landing (push) y cargarlo en la capa Bronze, con opciones de formato y saneamiento automático.

En esta página (14)

Lee antes: Cómo fluyen los datos · Pipeline medallón.


Qué es#

Traer un archivo al datalake por el modo push ("Tú depositas"): envías el archivo a la landing e Ingestia lo carga en Bronze automáticamente. Formatos soportados: CSV, JSON (líneas/JSONL o array) y Parquet.

CSV, JSON y Parquet solo aceptan depósito. No existe "nosotros buscamos" para un formato de archivo: para que Ingestia busque archivos en una carpeta o en un bucket suyo, el camino son los conectores de object storage — Amazon S3, Google Cloud Storage, Azure Blob Storage y los compatibles (MinIO, Wasabi, Cloudflare R2, Backblaze B2, DigitalOcean Spaces), además de SFTP, Google Drive, Dropbox, OneDrive/SharePoint y archivo por HTTP. Todos están en Acceso limitado: la liberación es conector por conector, después de validarse con una credencial real de su cuenta. Este tutorial cubre el depósito, que es el camino más simple.

Para qué sirve#

Subir extracciones puntuales, dumps u hojas de cálculo exportadas sin configurar una conexión de base de datos — ideal para empezar rápido o para datos que no viven en un sistema conectable.

Cuándo usar / cuándo no usar#

  • Úsalo cuando: tienes un archivo listo (CSV/JSON/Parquet) y quieres cargarlo ya.
  • No lo uses cuando: el dato se actualiza solo en una base/SaaS (prefiere un pull programado) — el push es una carga que tú disparas.

Plan y permisos#

  • Núcleo del producto · verificación de acceso · interruptor de apagado de ejecución de ingesta.

Requisitos previos#

  1. El archivo en CSV, JSON o Parquet.
  2. Para CSV: conocer el delimitador (coma, punto y coma, tabulación o pipe).
  3. Para JSON: saber si es líneas (JSONL/ndjson) o array único.
  4. Parquet es autodescriptivo — sin opciones de formato.

Paso a paso#

  1. En la consola, ve a ETL/ELT → Conexiones y elige el formato: CSV, JSON o Parquet (categoría Archivos), en el modo Tú depositas (push).
  2. Ajusta las opciones de formato:
    • CSV → Delimitador: Coma (,), Punto y coma (;), Tabulación o Pipe (|).
    • JSON → Formato: Líneas (JSONL / ndjson) o Array único.
    • Parquet → nada que configurar.
  3. Usa el área de carga para enviar el archivo a la landing.
  4. Dispara la carga en Tablas de Bronze → Ingerir en vivo (o deja que la programación se encargue).
  5. Sigue los pasos en vivo: validar → landing → bronze → registrar.

Ejemplo (sintético)#

CSV de ventas con punto y coma como delimitador (vendas.csv):

csv
pedido_id;data_pedido;uf;categoria;preco_unitario;quantidade;status
P-1001;2026-01-03;SP;Bebidas;12,90;3;pago
P-1002;2026-01-03;RJ;Limpeza;29,90;1;pago
P-1003;2026-01-04;MG;Bebidas;12,90;2;cancelado

El mismo dato en JSONL (una línea por objeto):

json
{"pedido_id":"P-1001","data_pedido":"2026-01-03","uf":"SP","preco_unitario":"12,90","quantidade":"3","status":"pago"}
{"pedido_id":"P-1002","data_pedido":"2026-01-03","uf":"RJ","preco_unitario":"29,90","quantidade":"1","status":"pago"}

Resultado esperado#

  • El archivo llega a la landing y se carga en Bronze con el tipo de cada columna detectado por los valores (número, fecha, texto) y las marcas técnicas. Ninguna fila se descarta en Bronze.
  • Atención a los identificadores solo con dígitos (CPF sin puntuación, CEP, código de producto como 00123): la detección los lee como número y el cero a la izquierda se pierde en Bronze. Envía esos campos con puntuación (071.518.203-05) o con un carácter no numérico, y revisa la columna después de la primera carga.
  • El paso registrar actualiza el catálogo y la última sincronización.
  • Después, ejecuta el pipeline para llevarlo a Silver/Gold.

Saneamiento automático (por qué la carga no se rompe por un nombre de columna)#

Si un encabezado tiene acento, espacio o viene vacío ("preço", "nome do cliente"), un load directo fallaría (Invalid field name). Cuando eso pasa, Ingestia sanea el archivo y lo vuelve a cargar: minúsculas, sin acento, _ en lugar de espacio; una columna vacía se convierte en coluna; un nombre que empieza con número se convierte en col_.... También desenvuelve envoltorios ({meta..., data:[...]}) y convierte array/pretty-JSON a NDJSON. Regla conservadora: una línea no parseable se mantiene tal cual — Ingestia nunca inventa datos.

Límites y costos#

  • Carga a Bronze: por defecto batchSize 5.000, maxRows 200.000.
  • La carga en el datalake es cobrable.

Seguridad#

  • El archivo va a la landing de tu workspace (landing/{prefix}/...); nunca se cruza con otro cliente.
  • No pongas secretos ni PII innecesaria en el archivo — las columnas PII se enmascaran en el profiling, pero lo mejor es no traer lo que no necesitas.

Errores comunes#

SíntomaCausa probableQué hacer
Todas las columnas en una soladelimitador incorrecto en el CSVSelecciona el delimitador correcto (; es común en Brasil)
El JSON no cargaformato marcado incorrectamenteAlterna entre Líneas (JSONL) y Array único
Invalid field nameencabezado con acento/espacioEl saneamiento vuelve a cargar solo; revisa los nombres resultantes
CPF/CEP sin el cero a la izquierdala columna solo tiene dígitos y se leyó como númeroEnvía el campo formateado (con puntos/guion) y vuelve a crear la tabla; en Silver usa LPAD(CAST(col AS STRING), 11, '0') para el CPF

Solución de problemas#

  • Revisa en la pantalla de ejecución los pasos validar → landing → bronze → registrar.
  • Compara, en la capa Bronze, el número de filas ingeridas con el del archivo.

Relacionados#


Última revisión: 2026-09-08.

Enlaces relacionados