Convertir JSON a NDJSON

Este es el mecanismo entero y conviene decirlo antes que nada. Si el documento es un array, cada elemento se escribe en una línea. Si es cualquier otra cosa —un objeto, una cadena, un número— el documento completo se escribe en una sola línea, porque NDJSON se define como un valor JSON completo por línea y un objeto es un valor.

Ninguno de los dos resultados es un error y el conversor no te va a avisar, así que la comprobación es tuya: abre el archivo y mira el primer carácter. Un corchete produce el archivo que querías. Una llave produce una única línea larguísima, que es NDJSON perfectamente válido, se carga sin protestas en casi cualquier consumidor y representa un registro donde esperabas miles.

Las respuestas de una API casi nunca son un array pelado. Son un objeto con una clave —data, resultados, items, registros— cuyo valor es el array. En las conversiones tabulares de este sitio ese envoltorio se abre solo, porque una tabla no tiene dónde ponerlo. En esta pareja no se abre, y la diferencia pilla a mucha gente.

La razón es que aquí el envoltorio es un registro legítimo. NDJSON admite objetos de cualquier forma, así que no hay manera de distinguir «una envoltura que hay que tirar» de «un registro que contiene una lista», y adivinar significaría descartar datos en silencio en los archivos donde la adivinanza falle. El arreglo son diez segundos en un editor: borra la llave de apertura con su clave, borra la de cierre, guarda y convierte. Si lo haces a menudo, jq con la expresión .data hace lo mismo sin abrir el archivo.

Cualquier otro destino de este sitio para una exportación JSON tiene que aplanar. Un CSV, un TSV, una sentencia SQL o una columna Parquet no tienen dónde meter un objeto dentro de un valor, así que el anidamiento se convierte en nombres de columna con puntos y los arrays en columnas numeradas. NDJSON no tiene ese problema: cada línea es JSON, de modo que un pedido con la dirección del cliente anidada y cinco líneas de detalle llega completo.

Eso convierte a esta conversión en la elección correcta cuando la estructura es el dato. Si el destino sabe leer JSON delimitado por saltos de línea —y casi todos los cargadores de almacén, productores de cola y agentes de registro saben— obtienes las propiedades de flujo y de recuento de líneas sin pagarlas en estructura. Las conversiones que aplanan son para destinos que sinceramente no pueden guardar un árbol.

Cada registro se escribe de forma compacta: sin sangría, sin saltos de línea dentro del registro, una línea sin espacios sobrantes por elemento. Si el original venía formateado para leerlo con comodidad, el archivo encoge bastante aunque no se haya quitado nada, porque una exportación JSON con sangría es a menudo más espacio en blanco que datos.

El orden de las claves dentro de cada registro se conserva y no se añade ni se quita ninguna. Un registro al que le faltaba un campo dentro del array sigue sin ese campo en su línea: NDJSON no reconcilia unos registros contra otros como sí hacen los escritores tabulares, y no le hace falta, porque no hay una cabecera común que rellenar.

Un salto de línea dentro de una cadena va escapado dentro del JSON y no escrito literalmente, así que nada de los datos puede producir un corte de línea. Eso convierte el límite de línea en una garantía real y no en una convención: wc -l es el número de registros, split -l 50000 produce trozos válidos y head -1 muestra un registro completo.

También cambia lo que cuesta un archivo roto. Un array JSON mal formado no te da nada: el análisis falla y no puedes saber qué registro tuvo la culpa. Una línea mal formada en un NDJSON te cuesta esa línea, y al volver a leerlo el conversor nombra el número de línea culpable, que es la diferencia entre un arreglo de cinco minutos y una tarde con un editor hexadecimal.

Hay una ironía en esta pareja que conviene reconocer. Toda la ventaja de NDJSON es que quien lo consume nunca tiene que sostener el archivo entero, y producirlo aquí exige exactamente eso: un array JSON no es válido hasta que llega su corchete de cierre, así que el documento se analiza completo antes de poder escribir la primera línea.

El límite práctico es por tanto tu propia memoria y no un escalón de tarifa. Un documento de varios cientos de megabytes es donde una pestaña empieza a sufrir. Si los datos los produces tú, el arreglo bueno está aguas arriba: haz que el origen emita NDJSON desde el principio, que en la mayoría de los exportadores es una línea de código y quita el análisis del archivo completo de la canalización para siempre.

Bastantes lo aceptan directamente: los trabajos de carga de BigQuery y Snowflake apuntando a JSON delimitado por líneas, DuckDB leyendo el archivo dentro de una cláusula FROM, ClickHouse con su formato JSONEachRow, y la mayoría de las rutinas de importación de aplicaciones que describen su entrada como un objeto por línea.

Un grupo más pequeño quiere un protocolo en lugar de registros. Las peticiones masivas de Elasticsearch y OpenSearch intercalan una línea de instrucción antes de cada documento, así que el cuerpo tiene el doble de líneas que registros y esta salida es la materia prima y no la carga útil. Para saber en cuál de los dos casos estás, busca las palabras acción o metadatos en la descripción del formato: si aparecen, te están pidiendo que generes las líneas extra.

Nada de esta conversión es de un solo sentido. Convertir el resultado otra vez a JSON reagrupa las líneas en un array, y como cada línea ya era un valor completo, el array que recibes es el array del que partiste: los mismos registros, el mismo anidamiento, el mismo orden de claves.

Eso conviene saberlo al decidir qué se guarda. Si el NDJSON es un artefacto de transporte para una sola carga, no hay motivo para archivarlo: el JSON contiene la misma información y más herramientas lo leen sin preguntar. Si van a seguir llegando registros, el NDJSON es la forma mejor a largo plazo, porque añadir es escribir una línea al final en vez de reescribir un corchete al final de un archivo grande.

Buena parte de lo que se publica en los portales de datos abiertos de España y de América Latina llega como un JSON de un solo documento: un array de expedientes, de centros, de estaciones de medición o de licitaciones, envuelto además en la respuesta de la API que lo sirve. Se descarga bien y se carga mal, porque quien lo va a cargar quiere registros y no un documento.

Convertirlo a NDJSON antes de tocarlo resuelve dos cosas de golpe. La primera es que ya puedes contar registros con una herramienta de línea de órdenes en lugar de con un analizador. La segunda es que puedes trocear el archivo por líneas y cargar una muestra pequeña, que es la manera sensata de descubrir que un campo de fecha viene en tres formatos distintos antes de comprometerse con un esquema.

No todos los consumidores ganan. Si el destino es un programa que va a leer el archivo entero de una vez —un fichero de prueba, un script de datos iniciales, el cuerpo de una petición, una importación de configuración— un array JSON es lo que espera, y NDJSON solo añade un paso de recomposición al otro lado.

Y si los registros se van a consultar muchas veces en lugar de cargarse una, ninguna de las dos formas es ideal. Las dos repiten cada clave en cada registro, que en un archivo real es una parte enorme del peso. Un formato columnar guarda las mismas filas en una fracción de los bytes y responde a una pregunta sobre dos campos leyendo dos campos, cosa que un flujo por líneas no puede hacer.

En esta pestaña, en JavaScript corriente, sin subida y sin cuenta. El plan gratuito acepta hasta 100 MB por archivo, y más allá de eso el freno es la memoria y no ninguna política nuestra.

El argumento de privacidad es muy concreto para quien prepara una carga masiva. Los archivos que se convierten para ingesta son registros de eventos, históricos de pedidos, ficheros de personas y pistas de auditoría, y entregar uno de esos a un servicio web para que le quite los corchetes sería un intercambio notable. Aquí no se envía nada, y comprobarlo es abrir la pestaña de red y convertir un archivo.