{
  "license": "CC BY 4.0",
  "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
  "recipe": {
    "slug": "query-nested-tool-events",
    "title": "Query Nested AI Tool-Call Events",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-27"
  },
  "contract": {
    "tableName": "agent_events",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "When the tool call completed."
      },
      {
        "name": "event_name",
        "type": "Utf8",
        "description": "agent_tool_called for these events."
      },
      {
        "name": "data.tool_name",
        "type": "Utf8",
        "description": "Nested tool identifier exposed as a dotted column."
      },
      {
        "name": "data.status",
        "type": "Utf8",
        "description": "Nested success or failed status."
      },
      {
        "name": "data.args.operation",
        "type": "Utf8",
        "description": "Safe, categorized operation rather than raw arguments."
      },
      {
        "name": "data.latency_ms",
        "type": "Float64",
        "description": "Nested tool-call latency."
      }
    ]
  },
  "query": "SELECT\n  \"data.tool_name\" AS tool_name,\n  \"data.args.operation\" AS operation,\n  COUNT(*) AS calls,\n  SUM(CASE\n    WHEN \"data.status\" = 'failed' THEN 1 ELSE 0\n  END) AS failures,\n  100.0 * SUM(CASE\n    WHEN \"data.status\" = 'failed' THEN 1 ELSE 0\n  END) / NULLIF(COUNT(*), 0) AS failure_rate_pct,\n  approx_percentile_cont(\"data.latency_ms\", 0.95) AS p95_latency_ms\nFROM agent_events\nWHERE event_name = 'agent_tool_called'\n  AND timestamp_utc >= now() - INTERVAL '7 days'\nGROUP BY \"data.tool_name\", \"data.args.operation\"\nHAVING COUNT(*) >= 20\nORDER BY failure_rate_pct DESC, calls DESC;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_1",
      "data.status": "success",
      "data.args.operation": "data.args.operation_example_1",
      "data.latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_2",
      "data.status": "failed",
      "data.args.operation": "data.args.operation_example_2",
      "data.latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_3",
      "data.status": "success",
      "data.args.operation": "data.args.operation_example_3",
      "data.latency_ms": 312
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_1",
      "data.status": "success",
      "data.args.operation": "data.args.operation_example_1",
      "data.latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_2",
      "data.status": "failed",
      "data.args.operation": "data.args.operation_example_2",
      "data.latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "event_name": "workflow_completed",
      "data.tool_name": "data.tool_name_example_3",
      "data.status": "success",
      "data.args.operation": "data.args.operation_example_3",
      "data.latency_ms": 312
    }
  ],
  "expectedOutput": {
    "columns": [
      "tool_name",
      "operation",
      "calls",
      "failures",
      "failure_rate_pct",
      "p95_latency_ms"
    ],
    "rows": [
      {
        "tool_name": "crm_lookup",
        "operation": "search_contact",
        "calls": 842,
        "failures": 61,
        "failure_rate_pct": 7.24,
        "p95_latency_ms": 2180
      },
      {
        "tool_name": "order_api",
        "operation": "fetch_order",
        "calls": 2210,
        "failures": 44,
        "failure_rate_pct": 1.99,
        "p95_latency_ms": 940
      },
      {
        "tool_name": "knowledge_search",
        "operation": "semantic_search",
        "calls": 4510,
        "failures": 19,
        "failure_rate_pct": 0.42,
        "p95_latency_ms": 720
      }
    ]
  },
  "notes": [
    "The compact input rows demonstrate field names and JSON types; they are not claimed to generate the displayed aggregate by themselves.",
    "The expected output is deterministic synthetic review data for the documented output shape.",
    "Adapt time windows, thresholds, identities, and business definitions before operational use."
  ]
}