Convertir Parquet a JSON

Parquet es lo que reparte una plataforma de datos y JSON es lo que come todo lo demás. En ese hueco vive esta conversión: un fixture que tiene que quedarse en el repositorio junto a la prueba que lo lee, una semilla para un servicio simulado en local, un cuerpo que pegar en una petición mientras averiguas por qué un endpoint la rechaza, o cincuenta filas que quieres mirar en un visor sin instalar DuckDB.

Fíjate en que todos los casos interesantes son pequeños. Parquet existe para que las tablas enormes salgan baratas de consultar, y nada de eso sobrevive al viaje: ni la disposición por columnas, ni la compresión, ni las estadísticas que permiten a un lector saltarse grupos de filas enteros. Lo que obtienes es un documento de texto, y un documento de texto es el artefacto adecuado para cien filas y el equivocado para diez millones.

El archivo se transpone de vuelta a filas y esas filas se escriben como un array JSON de primer nivel, con sangría de dos espacios y un salto de línea final. Los nombres de columna se convierten en claves del objeto tal como los escribe el esquema, incluidos los que un identificador de JavaScript no podría llevar.

No hay envoltorio ni bloque de metadatos. Si el destino espera los registros bajo un nombre —lo habitual es una clave rows o data— añádelo tú; con jq es un paso. La longitud del array es el número de filas, así que también es la comprobación más rápida de que la extracción contiene lo que te dijeron que contenía. Esta pareja, por cierto, no tiene ninguna opción: no hay nada que configurar y por tanto nada que dejar mal puesto.

Esta es la sorpresa de la página y conviene leerla dos veces. Parquet tiene tipos anidados de verdad —LIST, STRUCT y MAP— y el lector los devuelve como objetos, que después se serializan a texto y se colocan en el campo como una cadena. Una columna etiquetas con dos valores no aparece en la salida como un array. Aparece entre comillas, con las comillas interiores escapadas.

No se pierde nada y todo queda a un paso de distancia. Un acceso directo del tipo .[0].etiquetas[0] devuelve un error diciendo que una cadena no tiene índices; pasar antes ese campo por fromjson devuelve el valor. Si el JSON va a un fixture, lo honesto es desenvolver esas columnas una vez y guardar la versión ya estructurada, en lugar de dejar una doble codificación para que la descubra quien lea el fixture después.

Una columna de marcas de tiempo en Parquet es un entero con tipo, con una unidad y una marca de zona horaria anotadas en el pie del archivo. JSON no tiene ningún tipo de fecha, así que cada valor se escribe como cadena ISO 8601, que no es ambigua, ordena lexicográficamente en el orden correcto y la entienden Date.parse, datetime.fromisoformat y cualquier validación de esquema con formato de fecha y hora.

Lo que ha desaparecido es la declaración. El archivo ya no dice que la columna sea una fecha; dice que es una cadena que casualmente lo parece. Todo lo que venga después tiene que enterarse otra vez, con un argumento de análisis, un esquema o una conversión explícita. Para un fixture eso está bien y es explícito. Para una carga es un sitio más donde equivocarse de zona horaria.

Parquet tiene un tipo entero de 64 bits y los números de JavaScript llevan 53 bits de precisión entera. En lugar de redondear en silencio, un valor que no quepa se escribe como cadena entre comillas; uno que quepa se escribe como número pelado.

El intercambio es deliberado y está en el sentido correcto: un número de pedido que vuelve desviado en una unidad es un error que nadie encuentra hasta que importa, mientras que una columna que a veces es número y a veces cadena está al menos a la vista. Eso sí, significa que una columna puede cambiar de tipo a mitad del archivo, cosa que disgusta a un esquema JSON estricto. Si ese es tu destino, convierte la columna entera a texto en la consulta que produjo la extracción y el JSON saldrá homogéneo.

Un BYTE_ARRAY de Parquet sin anotación UTF8 son bytes y no texto, y los bytes no tienen representación fiel en JSON. Cada valor de ese tipo se escribe como una cadena hexadecimal en minúsculas: dos caracteres por byte, sin separador y sin prefijo.

El hexadecimal es reversible y no aparenta ser prosa, que es la razón de elegirlo en vez de intentar descodificarlo. También ocupa el doble que los bytes que representa, así que si una columna binaria es grande y no la necesitas, quítala en la consulta en lugar de arrastrarla por la conversión. Una columna de hashes no molesta; una con miniaturas incrustadas sí.

Un valor ausente en Parquet se convierte en null en el JSON, distinto de una cadena vacía y distinto de un cero. Suena poco notable hasta que lo comparas con los destinos delimitados, donde tanto el nulo como el vacío se aplastan en la nada entre dos separadores y ninguna consulta posterior puede distinguirlos.

Para un fixture esa diferencia es todo el asunto. Una prueba que afirma algo sobre la ausencia de un valor necesita que la ausencia sea representable, y JSON es aquí el único destino de texto que la representa. Es también la razón de que una ida y vuelta por JSON conserve más de un archivo Parquet que una por CSV, aunque ninguno de los dos lleve el esquema.

Los nombres de columna pasan a claves tal como vengan, así que un esquema con año, descripción, código_postal o nº_pedido produce un JSON con esas mismas claves. El archivo se escribe en UTF-8 y JSON admite cualquier carácter dentro de una clave, de modo que no hace falta renombrar nada antes de convertir.

Donde eso sí importa es en el código que lea el resultado: en muchos lenguajes tendrás que acceder por índice de diccionario en lugar de por atributo, porque año no es un identificador válido en todas partes. Es un detalle pequeño y se paga una sola vez, y suele ser preferible a renombrar columnas y perder la correspondencia con la tabla de origen.

Muchísimo, y por tres caminos a la vez. Parquet guarda cada columna una vez con su tipo declarado, codifica por diccionario los valores repetidos y comprime las páginas; el JSON repite el nombre de cada columna en cada fila, escribe cada número como dígitos decimales y además esta salida pone cada campo en su propia línea sangrada.

Cuenta con un orden de magnitud y no con un porcentaje, y con más cuando la tabla es ancha o los valores se repiten mucho: una columna de estado con cinco cadenas distintas no cuesta casi nada en Parquet y cuesta su longitud entera en cada fila del JSON. El documento se ensambla además en memoria como una única cadena antes de poder guardarse, que es el techo práctico bastante antes del límite de 100 MB. Pon un LIMIT en la extracción en vez de convertir una tabla del almacén y confiar.

Si lo que vas a hacer con las filas es alimentar una cola, un índice o un proceso que las trate de una en una, el documento único es la forma equivocada: obliga a quien lo lea a tener el array entero en memoria antes de empezar. Para eso está el destino NDJSON, que escribe una fila por línea y se puede leer en flujo.

El JSON de una sola pieza es para lo contrario: un artefacto que una persona va a abrir, leer y comprometer en un repositorio. Elegir bien entre los dos ahorra la mitad de los problemas de tamaño de la sección anterior, y la elección depende de quién lee el archivo y no de cuántas filas tiene.

El pie que hacía el archivo autodescriptivo no cruza. Los nombres de columna sobreviven como claves y nada más lo hace: ni los tipos declarados, ni la nulabilidad, ni la compresión, ni las estadísticas de los grupos de filas, ni los metadatos de clave y valor que el productor pudiera haber escrito dentro.

Si tienes DuckDB, un DESCRIBE sobre el archivo imprime el esquema en una línea de consola y cuesta diez segundos, y saber qué columnas eran INT64 y no DOUBLE explica casi todo lo que después parezca raro en el JSON. Si no lo tienes, convierte primero un puñado de filas y léelas: los enteros entrecomillados, las cadenas ISO y las columnas anidadas escapadas te dicen cada una cuál era el tipo de origen.

En esta pestaña. Un lector de Parquet escrito en JavaScript se descarga la primera vez que usas una de estas parejas y a partir de ahí trabaja en local; el archivo en sí no se manda a ninguna parte, y la pestaña de red durante una conversión enseña cómo llega el lector y cómo no sale nada.

Esa distinción importa en este formato más que en la mayoría, porque un Parquet es un artefacto de almacén. Los archivos con esa extensión son extracciones de tablas de producción —clientes, pedidos, eventos, nóminas— y llegan a través de un equipo de datos que tendría que declarar una subida. Aquí no hay ninguna que declarar.