Skip to main content

JSON Query

Extract and transform specific data from JSON objects using powerful query expressions.

What is JSON Query?​

The JSON Query node allows you to extract, transform, and manipulate data from JSON objects using three powerful query languages: JSONata, JMESPath, or JSONPath. This node serves as a crucial tool for data extraction and transformation in your workflows, enabling you to select specific fields or values from complex JSON structures and reshape them according to your needs.

Whether you're working with API responses, database results, or any structured data, JSON Query gives you precise control over extracting exactly what you need.

How to use it?​

  1. Add the JSON Query Node to Your Workflow:

    • Drag the JSON Query node from the Conversion category into your workflow canvas
    • Position it after a node that outputs JSON data you want to query

  2. Select a Query Language:

    • From the "Query Language" dropdown, choose between:
      • JSONata: Comprehensive expression language with functional programming features
      • JMESPath: Clean syntax for extracting and transforming JSON elements
      • JSONPath: XPath-like syntax for navigating JSON documents

  3. Connect Input Sources:

    • Connect a "Query Expression" input to provide your query string
      • This can come from a Text node or any node that outputs text
      • If not connected, you can type your query directly in the default field
    • Connect a "JSON" input from a node that provides the JSON data to query
      • This typically comes from API responses, Data Conversion, or other JSON sources

  4. Configure Output Format:

    • Select either "JSON" or "Text" output format:
      • JSON: Maintains the object structure for further JSON processing
      • Text: Converts the result to a string, useful for text-based components

  5. Connect to Downstream Nodes:

    • Connect your JSON Query output to subsequent nodes that will use the extracted data

Example of usage: Process Weather API Data​

Let's build a workflow that fetches weather data, extracts specific information, and formats it for display:

  1. Set Up the API Request:

    • Add an API Action node and set:
      • Request Method: GET
      • URL Source: External URL
      • Connect a Text node to the URL input with: https://api.open-meteo.com/v1/forecast?latitude=52.52&longitude=13.41&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m,wind_speed_10m

  2. Convert API Response to JSON:

    • Add a Data Conversion node
    • Connect the API Action output to its input
    • Set Input type to "Text" and Output type to "JSON"

  3. Extract Specific Weather Information:

    • Add a JSON Query node
    • Select "JSONata" as the Query Language
    • Connect the Data Conversion JSON output to the JSON Query's JSON input
    • Connect a Text node to the Query Expression input with this JSONata expression: 
      {
         "temperature": current.temperature_2m,
         "wind_speed": current.wind_speed_10m
       }
    • Set Output format to "JSON"

  4. Format the Weather Information as Text:

    • If you want you can now feed the extracted data to an llm to create e.g. an article out of it.

  5. Output the Formatted Weather Report:

    • Add an Output node connected to the LLM's output

Example JSON Query Expressions​

JSONata Examples​

  • Basic field access: weather[0].description
  • Create new structure: {"temp": main.temp, "conditions": weather[0].main}
  • Mathematical operations: {"celsius": main.temp, "fahrenheit": main.temp * 9/5 + 32}
  • Conditional logic: {"advice": $main.temp < 10 ? "Wear a coat" : "It's warm today"}

JMESPath Examples​

  • Extract nested fields: main.temp
  • Pick multiple fields: {temp: main.temp, city: name, country: sys.country}
  • Format conditions: weather[0].{condition: main, description: description}

JSONPath Examples​

  • Get temperature: $.main.temp
  • Get all weather descriptions: $.weather[*].description
  • Find conditions: $..description

Advanced Capabilities​

JSONata Features​

JSONata is particularly powerful for transformations, with capabilities including:

  • Array processing: weather[description = "clear sky"].id
  • Aggregation: $average(hourly.temperature)
  • String manipulation: $uppercase(weather[0].description)
  • Conditional logic: $weather[0].main = "Rain" ? "Take an umbrella" : "No umbrella needed"
  • Object transformation: {"report": $string(main.temp) & "°C and " & weather[0].description}

Combining with Other Nodes​

The JSON Query node works especially well with:

  1. API Action: Query external API responses
  2. Data Conversion: Transform between data formats
  3. LLM: Send structured data for AI processing
  4. Vector Store Writer: Extract fields for vector database storage
  5. Condition Routing: Route workflow based on query results

Troubleshooting​

Best Practices​

  • Start Simple: Begin with basic field access before writing complex expressions
  • Choose the Right Language:
    • JSONata for complex transformations and calculations
    • JMESPath for clean, consistent syntax
    • JSONPath when familiar with XPath or for simple extraction
  • Test Incrementally: Build your query step-by-step to ensure each part works
  • Consider Output Format: Use JSON when structure matters, Text for simple values
  • Add Comments: For complex queries, add a Text node with documentation

By mastering the JSON Query node, you can precisely extract and transform data from any JSON structure, making it a fundamental tool for creating powerful and flexible workflows in Nocodo AI.