JQ Query (Parse JSON)

Parses and filters JSON data using JQ queries.

How it Works

The component takes any data that can be turned into JSON – such as a Message or a Data object – and runs a JQ query against it. Internally it:

1. Converts the input to a JSON string (repairing malformed JSON if needed).
2. Loads the string into a Python dictionary/list.
3. Runs the JQ query with the jq library on that structure.
4. Wraps any primitive results (strings, numbers, etc.) into a Data object with a text field so all outputs are consistent.
5. Optionally flattens nested lists of Data objects into a single‑level list or removes keys that are empty, based on the user’s toggles.

No external services are called; all processing happens locally inside the dashboard.

Inputs

• Input: Data object to filter.
  The raw data you want to query – can be a single object or a list of objects.

• Flatten Data records: Flatten the data to a single level.
  When enabled and the input is a list of Data objects, nested lists will be flattened.

• 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/
  Write the JQ expression that selects or transforms the parts of the JSON you need.

• Remove Empty Keys: Remove keys with empty values or arrays with no items from the data.
  Clean up the output by dropping any keys that have no useful value.

Outputs

• Filtered Data: Data
  The result of applying the JQ query. Each item is a Data object that can be passed to other components in the workflow.

Usage Example

You have a list of customer records and you want only the names and emails.

1. Input – provide the JSON list of customers.
2. JQ Query – type:

   .[] | {name: .name, email: .email}

3. Flatten Data records – leave unchecked (the query already returns a flat list).
4. Remove Empty Keys – check if you want to drop any missing fields.

The component outputs a list of Data objects, each containing just the name and email fields, ready to be sent to the next step in your workflow.

Important Notes

🔒 Untrusted JSON May Be Altered 🟡
The component automatically repairs malformed JSON before processing. This can change the original content and might remove or modify data. Avoid using it with sensitive data unless you verify the repaired output.

⚠️ JSON Input Only 🟡
Only data that can be represented as JSON is accepted. If you pass a non‑JSON object or something that can’t be serialized, the component will raise an error. Convert your data to a serializable form first.

⚠️ Input Must Be List‑Like 🟡
The component expects the input to be a JSON list. If you provide a single object, it will be wrapped into a list internally, but complex nested structures may not be handled as expected.

📋 Dependencies Must Be Installed 🟡
The component relies on the jq and json_repair Python packages. If they are not present, the component will fail to run. Ensure these packages are installed in your environment.

💡 Write Clear JQ Queries 🟢
Provide a specific JQ query to filter only the fields you need. A generic query like . will return the entire payload, which may be large.

💡 Use Flatten Option Wisely 🟢
The Flatten Data records toggle only works when the input is a list of Data objects. If you enable it on a single object, the component will ignore it. Set the toggle only when working with arrays of records.

💡 Handle Primitive Results 🟢
When a JQ query returns a primitive value (string, number, etc.), the component wraps it in a text field for consistency. If you need the raw value, post‑process the output accordingly.

⚙️ Remove Empty Keys Setting 🟢
Enabling Remove Empty Keys will strip any key whose value is empty or an empty array. This can simplify the output but may also remove useful information if you rely on empty placeholders. Set it only if you want a cleaner payload.

ℹ️ Non‑Object Results Are Wrapped 🟢
If the JQ query produces a value that is not a JSON object, the component automatically converts it to an object with a single text key containing the string representation of the value. This ensures all output can be treated as a Data object.

Tips and Best Practices

• Use a specific JQ query instead of . to keep the output lightweight.
• Enable Remove Empty Keys when you want a clean, minimal payload.
• If you need to process single objects, wrap them in a list ([object]) before feeding them to the component.
• Verify the repaired JSON when working with data from untrusted sources.

Security Considerations

The automatic JSON repair feature may alter or strip parts of the input. For highly sensitive data, consider validating the JSON beforehand or disabling repair (not available as an option in the dashboard) and handling errors yourself.