JQ Query (Parse JSON)

JQ Query (Parse JSON) es una herramienta que te permite filtrar, transformar y limpiar datos JSON de manera rápida y flexible. Utiliza la sintaxis de JQ, un lenguaje de consultas poderoso, para seleccionar solo la información que necesitas y dejar tu flujo de trabajo más sencillo y limpio.

¿Cómo funciona?

El componente recibe como entrada un objeto de datos (puede ser un Message o un Data).

Serializa el objeto a una cadena JSON.
Si el JSON está mal formado, repara la cadena con json_repair.
Convierte cada elemento en un diccionario Python y los agrupa en una lista.
Compila la consulta JQ que introduces y la aplica a la lista completa.
Si seleccionas Flatten Data records, aplanará cada registro para que quede en un solo nivel.
Si activas Remove Empty Keys, eliminará cualquier clave cuyo valor sea vacío o un array sin elementos.
Devuelve el resultado como una lista de objetos Data, donde cada valor que no sea un objeto JSON se envuelve en una clave text.

Entradas

Campos de Entrada

Input: Objeto de datos que deseas filtrar y transformar. Puede ser un mensaje o un objeto Data.
Flatten Data records: Si la entrada es una lista de objetos, esta opción aplanará cada registro en un solo nivel de atributos.
JQ Query:

Enter a JQ query to filter and transform your JSON data. The input is always a JSON list.
Learn JQ syntax at https://jqlang.org/manual/
Escribe la consulta JQ que definirá qué datos quieres extraer y cómo transformarlos.
Remove Empty Keys: Elimina las claves que tienen valores vacíos o arrays sin elementos.

Salidas

Filtered Data: Una lista de objetos Data que contiene los resultados de la consulta JQ. Cada elemento puede ser un objeto JSON completo o, si el resultado es un valor primitivo, un objeto con una sola clave text que contiene su representación en cadena.

Ejemplo de Uso

Supón que tienes la siguiente entrada de datos: json [ {“name”:“Alice”,“age”:30,“email”:""}, {“name”:“Bob”,“age”:25,“email”:“bob@example.com”} ]

Y quieres obtener solo los nombres y edades, eliminando cualquier campo vacío:

JQ Query: .[] | {name, age, email}
Flatten Data records: ❌
Remove Empty Keys: ✅

El resultado será: json [ {“name”:“Alice”,“age”:30}, {“name”:“Bob”,“age”:25,“email”:“bob@example.com”} ]

Notas Importantes

🔒 Untrusted JSON May Be Altered 🟡
El componente usa json_repair para corregir JSON mal formados antes de procesarlo. Esto puede cambiar el contenido original y eliminar o modificar datos. Evita usarlo con información sensible a menos que verifiques el resultado reparado.

⚠️ JSON Input Only 🟡
Solo acepta datos que puedan representarse como JSON. Si pasas un objeto que no sea serializable, el componente lanzará un error. Convierte tus datos a una forma serializable primero.

⚠️ Input Must Be List‑Like 🟡
El componente espera que la entrada sea una lista JSON. Si proporcionas un solo objeto, se envolverá en una lista internamente, pero estructuras anidadas complejas pueden no manejarse como esperas.

📋 Dependencies Must Be Installed 🟡
El componente depende de los paquetes Python jq y json_repair. Si no están instalados, el componente fallará. Asegúrate de que estén presentes en tu entorno.

💡 Write Clear JQ Queries 🟢
Proporciona una consulta JQ específica para filtrar solo los campos que necesitas. Una consulta genérica como . devolverá todo el payload, que puede ser grande.

💡 Use Flatten Option Wisely 🟢
El interruptor Flatten Data records solo funciona cuando la entrada es una lista de objetos Data. Si lo activas sobre un solo objeto, se ignorará. Usa la opción solo con arreglos de registros.

💡 Handle Primitive Results 🟢
Si una consulta JQ devuelve un valor primitivo (cadena, número, etc.), el componente lo envuelve en una clave text. Si necesitas el valor sin envoltorio, postprocesa la salida.

⚙️ Remove Empty Keys Setting 🟢
Al activar Remove Empty Keys se eliminará cualquier clave con valor vacío o un array vacío. Úsalo solo si quieres un payload más limpio y no necesitas esos marcadores de posición.

ℹ️ Non‑Object Results Are Wrapped 🟢
Si la consulta JQ produce un valor que no es un objeto JSON, el componente lo convierte automáticamente en un objeto con una sola clave text que contiene su representación en cadena. Así, todas las salidas pueden tratarse como objetos Data.

Consejos y Mejores Prácticas

Usa consultas JQ específicas para evitar devolver datos innecesarios.
Activa Flatten Data records solo cuando trabajes con listas de registros.
Considera desactivar Remove Empty Keys si los valores vacíos son relevantes para tu lógica posterior.
Cuando la consulta devuelva valores primitivos, procesa la salida para extraer el valor real si lo necesitas.

Consideraciones de Seguridad

Ten cuidado al procesar datos no confiables. json_repair puede cambiar la estructura original de tu JSON, eliminando o alterando información. Si manejas datos sensibles, valida el contenido reparado antes de usarlo en tu flujo de trabajo.