Graph Compose

JSONata Expressions ✨

Transform data like a wizard! JSONata expressions are your magic wand for accessing, transforming, and combining data in your workflows.

🚀 TLDR: JSONata is like JavaScript for JSON:

  • Get data: user.name
  • Transform arrays: items.{ "id": id, "total": price * quantity }
  • Do math: $sum(items.price)
  • Chain it all: orders[status = "completed"].total

Why JSONata? 🤔

JSONata makes data transformation fun and powerful:

  • 🎯 Access any data with simple dot notation
  • 🔄 Transform arrays and objects like a pro
  • 🧙‍♂️ Write expressions that are actually readable
  • 🎨 Shape your data exactly how you want it
  • 🚀 Do more with less code

💡 Think of JSONata as your data's personal stylist - it helps transform your data into exactly what you need!

The Basics ✨

Getting data is super easy:

// Given this data:
{
  "user": {
    "name": "Alice",
    "email": "alice@example.com",
    "orders": [
      { "id": "123", "total": 50 }
    ]
  }
}

// These expressions:
user.name              // "Alice"
user.orders.id         // ["123"]
user.orders.total      // [50]

Fun with Arrays 🎪

Arrays are your playground:

// Given this data:
{
  "items": [
    { "name": "Laptop", "price": 1200, "category": "Electronics" },
    { "name": "Book", "price": 20, "category": "Books" },
    { "name": "Phone", "price": 800, "category": "Electronics" }
  ]
}

// These expressions:
items.name                     // ["Laptop", "Book", "Phone"]
items[price > 1000].name      // ["Laptop"]
$sum(items.price)             // 2020
items.{                       // Transform each item
  "id": name,
  "cost": price * 1.2,       // 20% markup
  "type": category
}

Magic Tricks 🎩

Here are some cool things you can do:

Combining Data 🤹

// Given this data:
{
  "user": { "name": "Alice", "email": "alice@example.com" },
  "orders": [
    { "id": "123", "items": ["book", "pen"], "total": 25 }
  ]
}

// This expression:
{
  "customer": user.name,
  "email": user.email,
  "orderCount": $count(orders),
  "totalSpent": $sum(orders.total)
}

Smart Conditions 🎲

// Time-based greeting
$case(
  $hour() < 12 ? 'Good morning',
  $hour() < 17 ? 'Good afternoon',
  'Good evening'
)

// Conditional pricing
amount > 100 ? amount * 0.9 : amount  // 10% discount over 100

Data Cleanup 🧹

// Given this data:
{
  "tags": ["js", null, "typescript", "", "react", null],
  "categories": ["books", "electronics", "books", "games"]
}

// These expressions:
tags[$ != null and $ != ""]    // Remove empty values
$distinct(categories)          // Get unique values

💡 Important: In Graph Compose, JSONata expressions are typically used inside double curly braces ({{ ... }}). You'll usually access data from previous nodes using results.[nodeId] (e.g., {{ results.get_user.data.email }}) or from the initial workflow context using context.key (e.g., {{ context.userId }}). The examples below show how JSONata is applied within these handlebar expressions in different parts of a node configuration.

Using JSONata in Workflows 🔄

In our workflows, JSONata powers dynamic data resolution in several places:

URL Parameters 🔗

{
  url: "https://api.example.com/users/:userId",
  urlParams: {
    userId: {
      jsonataExpression: "user.id"  // Resolves to the actual user ID
    }
  }
}

Query Parameters 🔍

{
  queryParams: {
    status: {
      jsonataExpression: "order.status"
    },
    limit: {
      jsonataExpression: "$number(pagination.limit)"
    }
  }
}

Request Bodies 📦

{
  body: {
    jsonataExpression: `{
      "userId": user.id,
      "items": cart.items.{
        "productId": id,
        "quantity": quantity
      },
      "total": $sum(cart.items.(price * quantity))
    }`
  }
}

Pro Tips 💫

Make your expressions awesome:

  • 🎯 Start simple, add complexity as needed
  • 🔍 Use the JSONata playground to test
  • 📝 Break complex expressions into parts
  • ✨ Remember: readability > cleverness
  • 🎨 Format your expressions nicely

Ready to transform some data? Let's go! 🚀

Try the JSONata Playground ✨