Convertir Parquet a NDJSON

Un archivo Parquet declara el tipo de cada columna en su pie. Conviértelo a CSV o a texto separado por tabuladores y esa declaración desaparece: todos los valores pasan a ser caracteres, y lo siguiente que lea el archivo vuelve a deducir los tipos a partir del aspecto de esos caracteres, normalmente de otra manera y siempre sin el esquema que estaba ahí al lado.

JSON tiene tipos propios. Un número sigue siendo número, un booleano sigue siendo booleano y un nulo sigue siendo nulo, así que el registro que llega al otro extremo dice de sí mismo lo mismo que decía la columna. No es una diferencia menor cuando el destino es un servicio o una cola con esquema, porque elimina toda una clase de «la API lo rechazó porque el campo era una cadena» de la mitad de la tubería.

Esta es la limitación que conviene conocer antes de construir nada encima del resultado. Parquet guarda listas, estructuras y mapas de forma nativa, y esas columnas se escriben en el JSON como cadenas que contienen JSON, no como JSON anidado. Una columna de lista llega escrita como una cadena con corchetes dentro: es un registro correcto y completo del valor, y no es la forma que aceptará un consumidor que espere un vector.

Se arregla en una pasada. Un `jq` con `fromjson` sobre ese campo lo convierte en un vector de verdad, y lo mismo vale para una estructura. Hacerlo de forma explícita es además la ocasión de decidir cómo debería llamarse ese campo y si el destino lo quiere anidado siquiera; muchos lo aceptan como cadena sin protestar. Lo que importa es saberlo, porque un campo que parece anidado en una revisión de código y es texto en ejecución es un descubrimiento desagradable.

JSON no tiene tipo de fecha. Una columna de marca temporal se escribe por tanto como una cadena en formato ISO 8601, que cualquier lenguaje, base de datos y validador de esquema interpreta sin que haya que indicarle un patrón, y que además ordena cronológicamente como texto plano.

La alternativa sería un número de época y es peor en un registro que alguna persona puede tener que leer: un campo con trece dígitos es ininteligible sin saber el origen y la unidad, y las dos unidades habituales se diferencian en un factor de mil. Si el destino insiste en milisegundos de época, convertir desde ISO es una expresión y la dirección no es ambigua; al revés, a partir de un número pelado, exige una suposición que habría que documentar.

Parquet tiene un entero de 64 bits, y los números de JSON están limitados en la práctica por lo que los analizadores de ambos extremos representan con exactitud, que para la mayoría son 53 bits. Un valor que pase de ahí no se puede transportar como número sin cambiarlo.

La conversión los escribe como cadenas. Un valor dentro del rango seguro se mantiene como número, uno fuera se convierte en una cadena entrecomillada con todos sus dígitos, y una columna que cruce la frontera contendrá las dos cosas. Ese tipo mixto es levemente molesto y es el intercambio correcto: una referencia de pedido redondeada tiene el mismo aspecto que una referencia de pedido, no coincide con nada y es muy difícil de rastrear. Si el destino tiene esquema, declara ese campo como cadena y conviértelo al llegar.

Una columna de bytes sin anotación de texto no tiene una forma textual fiel, así que se escribe como hexadecimal en minúsculas. Es reversible, no contiene delimitadores y nadie va a confundirlo con prosa, que son las tres propiedades que hacen falta.

Merece un aviso porque el tamaño se duplica: cada byte ocupa dos caracteres. Una columna con hashes o identificadores binarios que en el Parquet apenas pesaba puede convertirse en la mitad del archivo de salida. Si el destino no necesita esa columna, lo sensato es dejarla fuera desde el origen y no arrastrarla hasta aquí para descartarla después.

El archivo es un objeto JSON completo por línea y nada más: ni corchete de apertura, ni comas entre registros, ni cierre. Un analizador que espere un vector JSON fallará en la segunda línea, y eso es el formato funcionando como debe, no una avería.

Lo que compra esa ausencia es que un consumidor pueda leer una línea, actuar sobre ella, descartarla y seguir, sea cual sea el tamaño del archivo. También hace la salida direccionable por número de línea: las mil primeras líneas son a su vez una entrada válida para todo lo demás, partir el archivo produce trozos cargables, y una carga fallida se reanuda desde una línea en vez de empezar de cero.

Esta es la forma habitual del trabajo. Una tabla vive en una plataforma de datos y algo de fuera —un índice de búsqueda, una cola de mensajes, un servicio que hay que rellenar hacia atrás, un entorno de pruebas que necesita datos realistas— habla JSON y no ha oído hablar de Parquet nunca. NDJSON es el formato que se sienta entre los dos y no necesita más envoltorio que un salto de línea.

Un bucle de consola que lea líneas y publique cada una basta para una recarga pequeña, y para una grande el mismo archivo alimenta un extremo masivo o un productor sin modificarlo. Lo único que conviene revisar antes son los nombres de campo: una plataforma de datos pone a las columnas los nombres que le dejó la tubería que las produjo, y un servicio suele querer otros. Renombrar con `jq` es una expresión y se revisa mejor que un mapeo escondido dentro del consumidor.

Un nulo de una columna de Parquet se escribe como `null` en el JSON, lo que preserva una distinción que ningún formato delimitado puede llevar: nulo y cadena vacía son valores distintos y llegan distintos.

Eso importa donde el destino tiene esquema. Un campo declarado como cadena rechazará un nulo salvo que se haya declarado admisible, y el validador te lo dirá en el registro concreto donde ocurrió y no al final de la carga. Las dos cosas son mejores fallos que la alternativa delimitada, donde un nulo y una cadena vacía son los mismos cero caracteres y la diferencia ya se perdió antes de que nada la comprobara.

Al leer, todo se normaliza: los enteros grandes pasan a número o a cadena, las fechas a texto ISO, lo binario a hexadecimal y lo anidado a JSON dentro de una cadena. Al escribir de vuelta hacia Parquet, los tipos se vuelven a deducir de los datos y solo se emiten unos pocos tipos físicos, con la regla de que un único valor no numérico convierte toda la columna en texto.

La conclusión práctica es que un viaje de Parquet a texto y de vuelta a Parquet no conserva el esquema, y no conviene describir esta conversión como fiel a los tipos en ese sentido. Es fiel a los valores. Si el esquema es parte de lo que hay que preservar, anótalo desde la fuente antes de convertir o quédate con el Parquet original como copia buena.

El lector de Parquet es una biblioteca que esta página carga cuando hace falta, y el JSON se escribe ahí mismo, así que ninguna petición lleva el archivo. Para un extracto tomado de la mitad de una plataforma —antes de la agregación, antes del enmascarado— eso suele ser lo que decide si se puede usar un conversor en línea o no.

Todas las filas se materializan antes de escribir nada, de modo que el techo es la memoria. Parquet viene comprimido, así que un archivo modesto se expande bastante y el límite llega antes de lo que sugiere su tamaño en disco; el tope declarado es de 100 MB por archivo. Para una tabla grande, DuckDB lee el Parquet y escribe JSON por líneas en una sola instrucción sin sostener ninguno de los dos, y además permite elegir solo las columnas que el destino quiere.

Si el consumidor sabe leer Parquet, déjalo leer Parquet. Todos los almacenes, todos los motores de consulta y casi todas las bibliotecas de datos modernas lo hacen, y pasar el original conserva el esquema, mantiene pequeña la transferencia y elimina un paso en el que los tipos pueden desviarse.

Convierte cuando el consumidor de verdad habla JSON y nada más, que es el caso de la mayoría de los servicios, las colas y los índices de búsqueda. Esa frontera es real y permanente —los sistemas operacionales intercambian registros y los analíticos intercambian columnas— y esta conversión es el puente, no un sustituto de ninguno de los dos lados.