Convertir JSON a Parquet

Un archivo Parquet lleva su esquema en el pie: cada columna tiene un nombre y exactamente un tipo, y todas las filas lo cumplen. Eso es lo que permite que un motor de consulta te diga la forma de un archivo de dos gigabytes sin leer una sola fila, y es la propiedad por la que existe el formato.

Un array JSON no garantiza nada parecido. Los registros son objetos libres de llevar las claves que tengan, y nada impide que el cuadragésimo guarde texto en un campo donde los treinta y nueve anteriores guardaban un número. La conversión tiene que fabricar el esquema que el archivo nunca tuvo, y todos los casos incómodos de esta página salen de esa única frase.

Una extracción JSON suele llegar como un objeto con una clave que contiene el array: `data`, `results`, `registros`. Cuando el objeto tiene exactamente una clave y su valor es un array, ese array es lo que se convierte, porque es la forma que devuelve prácticamente cualquier extremo paginado y desenvolverlo es lo que se quería.

Con dos claves se acaba la magia. Un archivo con la forma `{"meta": …, "data": […]}` no tiene un array preferible, así que el objeto entero se convierte en una sola fila y los registros se aplanan por índice dentro de ella: `data.0.id`, `data.1.id` y así hasta el final. El síntoma es inconfundible cuando ya lo conoces: un Parquet con una fila y varios miles de columnas. Recorta el archivo al array antes de convertir.

Parquet no tiene dónde poner un objeto dentro de una celda, así que cada registro se aplana antes de transponerlo: un objeto `cliente` con una `ciudad` dentro se convierte en una columna llamada `cliente.ciudad`. Es exactamente el mismo aplanado que hacen los escritores de CSV, TSV, SQL y XLSX de este sitio, y es deliberado: una misma extracción anidada da los mismos nombres de columna la mandes al destino que la mandes.

Merece la pena decir que esto no siempre fue así. Hasta agosto de 2026 un valor anidado escrito a Parquet salía como el texto literal `[object Object]`, porque la ruta no pasaba por el aplanado que sí usaban los demás formatos. Si tienes archivos convertidos aquí antes de esa fecha, ese es el aspecto que tendría el problema.

Un array `etiquetas` con dos elementos produce dos columnas, `etiquetas.0` y `etiquetas.1`, y la lista de columnas es la unión a lo largo de todo el archivo. Un campo que casi siempre tiene dos elementos y de vez en cuando cuarenta genera cuarenta columnas, treinta y ocho de ellas nulas en casi todas las filas.

Donde una lista es genuinamente de longitud variable, unirla a una sola cadena antes de convertir da un esquema con el que se puede consultar. Es un paso de una línea en jq y evita un archivo que técnicamente está bien y en la práctica es incómodo de leer para cualquiera.

Los registros que no coinciden en qué claves tienen se reconcilian tomándolas todas. Un campo presente en el primero y ausente en el segundo produce una columna con un nulo en la segunda fila, y un campo que solo aparece en los últimos diez registros de un millón también se convierte en columna.

Esa reconciliación lee el array entero antes de escribir nada, que es el coste honesto de no muestrear. A cambio, un campo raro nunca se pierde en silencio, y la sorpresa que produce es predecible: convertir una muestra de diez registros da menos columnas que convertir el archivo completo. Toma el esquema de una conversión del archivo entero y nunca de la prueba.

La escritura emite solo `BOOLEAN`, `INT32`, `DOUBLE` y `STRING`. El tipo se decide por columna a partir de todos sus valores, no de una muestra: todo booleanos da `BOOLEAN`; todos enteros dentro del rango de 32 bits da `INT32`; cualquier otro número da `DOUBLE`; y cualquier otra cosa da texto. Los nulos no cuentan, así que una columna numérica con huecos sigue siendo numérica.

La ventaja de venir de JSON en vez de una hoja de cálculo es que aquí los tipos existen de verdad en el origen: un número llega como número y un booleano como booleano, sin deducir nada a partir de los caracteres. La inferencia solo tiene que resolver los desacuerdos entre registros, no inventarse la naturaleza de cada valor.

Es la decisión conservadora y va deliberadamente en esa dirección. Un campo que es número en casi todos los registros y texto en unos pocos —un identificador que unos sistemas entrecomillan y otros no, una cantidad con un «n/d» dentro— hace que toda la columna sea texto, y los valores numéricos se escriben como texto a su lado.

La alternativa tentadora, quedarse con el tipo del primer registro y anular el resto, produce archivos válidos que cargan sin quejarse y han borrado en silencio justo los valores que no encajaban. Una columna de texto se ve, y convertirla es una expresión; unos nulos donde había datos no se ven hasta que alguien los busca.

Los dos casos que más duelen en datos en español son identificadores hechos de cifras. Un código postal de Vitoria es `01001` y uno de Barcelona `08001`: si el JSON de origen los escribió como números, el cero inicial ya se perdió antes de que ningún conversor viera el archivo, y aquí llegan como 1001 y 8001.

El NIF va por el otro lado y sale bien precisamente por llevar letra: como no es numérico, la columna entera se convierte en texto y se conserva tal cual. La regla general que se deduce de los dos es sencilla y vale para cualquier exportación: si una columna es una clave, escríbela como cadena en el origen y ninguna inferencia tendrá que decidir nada por ti.

Parquet tiene un entero de 64 bits y esta conversión no lo emite. Los valores pasan por números de JavaScript, que llevan 53 bits de precisión entera, así que un valor fuera del rango de 32 bits se escribe como `DOUBLE` en lugar de reclamar una exactitud que ya no tiene.

Para referencias y números de pedido eso importa, y el arreglo está aguas arriba. Una exportación que escriba las referencias como cadenas las mantiene exactas a través de la conversión y las deja en una columna de texto, que es lo que debería ser un identificador de todas formas. Una que las escriba como números desnudos ya ha perdido precisión pasadas las dieciséis cifras antes de que ningún conversor toque el archivo.

Buena parte de las extracciones JSON en español vienen de un portal de datos abiertos o de la API de una plataforma: padrones, licitaciones, calidad del aire, series de un instituto de estadística. Casi todas comparten la misma forma —un objeto con metadatos y un array de registros— y casi todas se descargan página a página.

Ahí es donde conviene recordar las dos reglas anteriores. Une las páginas en un único array antes de convertir, y quítale el envoltorio si trae más de una clave. Con el array limpio, un volcado de miles de registros pasa a un archivo que DuckDB o pandas leen directamente y que se consulta sin volver a interpretar el JSON en cada pregunta.

Lo primero es el esquema, no las diez primeras filas. Dos preguntas resuelven casi todo: si alguna columna ha salido como texto cuando la esperabas numérica, y si el número de columnas es el que esperabas. La primera te dice qué registros no se ponían de acuerdo sobre un tipo; la segunda, si algún campo anidado o algún array de longitud variable ha ensanchado el archivo más de lo que pretendías.

Conviene añadir una advertencia sobre los viajes de ida y vuelta: al leer un Parquet aquí los tipos se vuelven a deducir en vez de arrastrarse, de modo que Parquet a otro formato y de vuelta a Parquet no conserva el esquema. Trata el archivo como un destino, no como un formato intermedio.

En el navegador. El escritor de Parquet es JavaScript que esta página carga cuando hace falta, sin WebAssembly y sin servidor, así que ninguna petición lleva la extracción a ninguna parte y no hay cuenta, ni cola, ni plan. El tope declarado son 100 MB por archivo.

El techo real, sin embargo, es la memoria: el array se interpreta entero, se transpone a columnas y se escribe, de modo que todo el conjunto de datos existe a la vez. Decenas de megabytes son rutina y varios cientos son donde la pestaña empieza a sufrir. A partir de ahí el instrumento correcto es un lector en flujo dentro de un script, y decirlo es mejor que fallar a medio archivo.