Multi-Agent Joins

What you'll learn

Inner-join two agents on a shared field in a single SaQL query.

Join query shape

{
  "type":   "join",
  "agents": ["users", "orders"],
  "on":     "user_id"
}

Both agents must have records with the user_id field. The join returns matched pairs.

Setup — write records to two agents with shared user_id

`bash # Users curl -s -X POST http://localhost:7475/v1/agents/users/write \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"payload": {"user_id": "usr_001", "name": "Alice", "plan": "pro"}}' \ | python3 -m json.tool

# Orders curl -s -X POST http://localhost:7475/v1/agents/orders/write \ -H "Content-Type: application/json" \ -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \ -d '{"payload": {"user_id": "usr_001", "amount": 299.99, "status": "paid"}}' \ | python3 -m json.tool `

Execute the join

curl -s -X POST http://localhost:7475/v1/agents/users/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{
    "type":   "join",
    "agents": ["users", "orders"],
    "on":     "user_id"
  }' | python3 -m json.tool

Response: `json { "join_results": [ { "key": "usr_001", "users": {"user_id": "usr_001", "name": "Alice", "plan": "pro"}, "orders": {"user_id": "usr_001", "amount": 299.99, "status": "paid"} } ] } `

Join semantics

• Inner join: only returns rows where user_id exists in BOTH agents
• Users without orders: excluded
• Orders without matching users: excluded

Challenge

Set up a join between products and reviews on product_id. Write 3 products and 5 reviews (some products have multiple reviews, one has none). Run the join and confirm the unreviewed product is excluded.

---