Convertir TSV a NDJSON

Un índice de búsqueda no admite ficheros delimitados. Los motores de este tipo ingieren por un punto de entrada masiva que lee JSON delimitado por saltos de línea, las herramientas de importación de las bases documentales leen por defecto un documento por línea y los almacenes analíticos tienen un formato de carga con ese mismo nombre. Ninguno mira una tabla con tabuladores.

No es un capricho. Un almacén de documentos guarda documentos, y un documento tiene campos con nombre y con tipo, cosa que una fila delimitada no tiene. La conversión es por tanto un cambio de modelo tanto como de sintaxis: cada fila deja de ser una posición dentro de una tabla y pasa a ser un objeto que se describe a sí mismo, indexable por campo y capaz de convivir con documentos que no tienen los mismos campos.

La salida es un objeto JSON completo por línea y nada más: sin corchete de apertura, sin comas entre registros y sin corchete de cierre. Esa ausencia es el formato. Permite que un cargador lea una línea, la indexe, la descarte y siga adelante sin sostener nunca el fichero entero.

También significa que el conjunto no es JSON válido, y que un analizador que espere un array fallará en la segunda línea. No es un defecto: es exactamente la propiedad que permite cargar un fichero de cien millones de líneas con un proceso de memoria pequeña. Si algo aguas abajo lo rechaza, lo que hay que comprobar es si ese consumidor quería un array, en cuyo caso el destino correcto era JSON.

La fila de cabecera aporta los nombres de campo tal y como están escritos. «Título del producto» se queda con su espacio y su tilde, y «precio (EUR)» conserva los paréntesis. No se normaliza nada, porque un conversor que reescribiera los nombres en silencio haría imposible cuadrar los documentos cargados con el fichero de origen.

Varios destinos son más quisquillosos que el propio JSON. El punto dentro de un nombre de campo suele interpretarse como separador de ruta, así que una columna llamada con un punto en medio produce un campo anidado en lugar de uno plano y un conflicto de mapeo poco después. Otros almacenes exigen que el nombre empiece por letra y no lleve más que letras, dígitos y guiones bajos, y rechazan la carga entera si no. Arreglar la cabecera antes de convertir es una edición; arreglar un millón de documentos ya cargados no lo es.

El JSON se escribe en UTF-8 y los caracteres no ingleses se emiten tal cual: «España», «señor» y «kilómetros» aparecen legibles al abrir el fichero, no convertidos en secuencias de escape. Para un catálogo en español eso es lo que quieres, porque el fichero se puede revisar a ojo antes de cargarlo.

La consecuencia práctica es que el destino tiene que leerlo como UTF-8, cosa que hacen todos los que se nombran aquí. Si en el índice aparecen caracteres extraños en lugar de acentos, el problema no está en la conversión sino en alguna capa intermedia que está suponiendo una codificación antigua, y ahí es donde hay que mirar.

JSON tiene tipos y una tabla delimitada no, así que el analizador los deduce. Lo que se lee como número pasa a número, las palabras true y false a booleanos, un campo vacío a null y el resto se queda como cadena. En un catálogo eso significa que los precios y las existencias llegan numéricos y se pueden agregar sin forzar el mapeo, que suele ser lo deseable.

La deducción se equivoca donde se equivoca siempre: en los identificadores. Una referencia escrita 00123 se convierte en el número 123 y un código de barras sin guiones se convierte en un entero grande. En un índice de búsqueda eso es peor que en otros sitios, porque un campo numérico no se analiza y no responderá a una búsqueda por el término original. Corrige esas columnas en la exportación, o en una pasada sobre el fichero convertido antes de cargarlo.

Un detalle que aparece constantemente en exportaciones hechas en España o en Latinoamérica y que la documentación en inglés no menciona nunca. La inferencia reconoce el punto decimal; un valor escrito 12,50 no encaja y llega al documento entrecomillado.

El efecto en un índice es que el campo se mapea como texto y luego no se puede ordenar ni agregar por él, y arreglarlo obliga a reindexar. Mira las primeras líneas del fichero convertido antes de cargar nada: si los importes van entre comillas, decide ahí mismo si se normalizan en el origen o en una pasada intermedia, y no cuando ya haya un millón de documentos dentro.

Las columnas que se van a indexar suelen ser precisamente las incómodas: descripciones de producto, cuerpos de artículo, texto de reseñas, campos de anotación. En un fichero con tabuladores son las que rompen las cosas, porque un tabulador pegado añade una columna y un salto de línea termina la fila antes de tiempo.

En JSON son contenido de cadena corriente. El tabulador y el salto de línea se escapan, las comillas se escapan, y ninguno de ellos puede afectar a la estructura del documento, porque la estructura vive en la puntuación del objeto y no en los caracteres del dato. Para una carga de búsqueda ese es el motivo entero de que la conversión sea segura: el texto que indexas es el texto que había en el campo, no el que había hasta el primer carácter significativo.

La salida son documentos y nada más. Los puntos de entrada masiva de los motores de búsqueda esperan una línea de metadatos antes de cada documento —un objeto pequeño que nombra la operación y normalmente el índice—, así que enviar este fichero tal cual produce un error de análisis en la segunda línea y una pila de mensajes confusos detrás.

Se arregla con una sola pasada de una herramienta de línea de órdenes que intercale esa línea antes de cada documento. El resto de destinos no necesitan ese paso: una importación a una base documental lee el fichero como está, un trabajo de carga en un almacén analítico lo lee como está, y una tubería de ingesta que procesa líneas lo lee como está.

Un campo vacío se escribe como null en lugar de como cadena vacía, y las claves salen de la cabecera y no de las filas: una línea con más campos de los que hay en la cabecera no inventa nombres para los sobrantes, sino que los agrupa en una lista aparte dentro de ese documento concreto.

Las dos cosas interactúan con el mapeo. Un motor de búsqueda no deduce el tipo de un campo a partir de un nulo, así que una columna que viene vacía durante varios miles de documentos y numérica después acaba tipada por el primer valor no nulo que aparezca; si ese valor resulta ser una nota al pie en lugar de un número, todos los documentos posteriores fallan al indexarse en ese campo. Definir el mapeo antes de la carga es la solución, y leer las cien primeras líneas del fichero convertido es la forma de saber qué campos lo necesitan.

Repetir el nombre de cada campo en cada línea hace el fichero más grande, y bastante más en una tabla ancha de valores cortos. En un catálogo con mucho texto el efecto queda amortiguado, porque las descripciones dominan los bytes y los nombres de campo son ruido a su lado.

Además importa menos que en otros casos, porque este fichero es un artefacto de transporte y no un almacén: existe para que un cargador lo lea una vez y luego se borra, y la copia duradera es el índice o la tabla que produjo. La compresión elimina casi toda la diferencia en tránsito y todos los destinos citados aceptan un fichero comprimido.

Tanto el lector de la tabla como el escritor de JSON son JavaScript corriente cargado por esta página, así que ninguna petición lleva el fichero. Un catálogo antes del lanzamiento, un conjunto de datos sin publicar o un extracto con texto escrito por clientes no se copia a un tercero solo para cambiarle la forma.

El techo son 100 MB por fichero y cien ficheros por tanda. La tabla entera se construye en memoria antes de escribir nada, lo que deja decenas de megabytes cómodamente dentro y pone la tensión cerca del tope. Para una exportación mayor, la herramienta correcta es un lector por flujo dentro de un script; y como el destino es una carga por flujo, ese script suele ser el que ibas a acabar escribiendo de todos modos.

Los almacenes analíticos leen texto delimitado directamente y cargan una tabla con tabuladores más rápido que documentos JSON, porque no tienen que analizar un nombre de campo en cada fila. Si el destino es una tabla con un esquema que ya definiste, esta conversión no te está comprando nada.

Parquet vuelve a ser mejor respuesta cuando los mismos datos se van a consultar muchas veces en lugar de ingerirse una, porque guarda los nombres de campo una sola vez y los valores en columnas tipadas. El NDJSON se gana su sitio cuando el destino tiene de verdad forma de documento: un índice de búsqueda, un almacén documental o una tubería que procesa líneas.