{
  "license": "CC BY 4.0",
  "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
  "recipe": {
    "slug": "llm-time-to-first-token",
    "title": "Measure LLM Time to First Token",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-27"
  },
  "contract": {
    "tableName": "llm_requests",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "Model request completion time."
      },
      {
        "name": "model",
        "type": "Utf8",
        "description": "Provider model identifier."
      },
      {
        "name": "feature",
        "type": "Utf8",
        "description": "Product feature making the request."
      },
      {
        "name": "status",
        "type": "Utf8",
        "description": "Final request outcome."
      },
      {
        "name": "time_to_first_token_ms",
        "type": "Float64",
        "description": "Milliseconds until the first streamed token."
      },
      {
        "name": "latency_ms",
        "type": "Float64",
        "description": "Total request duration in milliseconds."
      }
    ]
  },
  "query": "SELECT\n  feature,\n  model,\n  COUNT(*) AS requests,\n  approx_percentile_cont(time_to_first_token_ms, 0.50) AS p50_ttft_ms,\n  approx_percentile_cont(time_to_first_token_ms, 0.95) AS p95_ttft_ms,\n  approx_percentile_cont(latency_ms, 0.95) AS p95_total_latency_ms\nFROM llm_requests\nWHERE timestamp_utc >= now() - INTERVAL '7 days'\n  AND status = 'success'\n  AND time_to_first_token_ms IS NOT NULL\nGROUP BY feature, model\nHAVING COUNT(*) >= 30\nORDER BY p95_ttft_ms DESC;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_1",
      "status": "success",
      "time_to_first_token_ms": 820,
      "latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_2",
      "status": "failed",
      "time_to_first_token_ms": 1640,
      "latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_3",
      "status": "success",
      "time_to_first_token_ms": 970,
      "latency_ms": 312
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_1",
      "status": "success",
      "time_to_first_token_ms": 820,
      "latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_2",
      "status": "failed",
      "time_to_first_token_ms": 1640,
      "latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "model": "configured-model",
      "feature": "feature_example_3",
      "status": "success",
      "time_to_first_token_ms": 970,
      "latency_ms": 312
    }
  ],
  "expectedOutput": {
    "columns": [
      "feature",
      "model",
      "requests",
      "p50_ttft_ms",
      "p95_ttft_ms",
      "p95_total_latency_ms"
    ],
    "rows": [
      {
        "feature": "report_generation",
        "model": "large-reasoning",
        "requests": 842,
        "p50_ttft_ms": 1280,
        "p95_ttft_ms": 4620,
        "p95_total_latency_ms": 18400
      },
      {
        "feature": "draft_reply",
        "model": "small-fast",
        "requests": 6810,
        "p50_ttft_ms": 310,
        "p95_ttft_ms": 920,
        "p95_total_latency_ms": 3840
      },
      {
        "feature": "search_summary",
        "model": "balanced",
        "requests": 2420,
        "p50_ttft_ms": 480,
        "p95_ttft_ms": 1380,
        "p95_total_latency_ms": 6210
      }
    ]
  },
  "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."
  ]
}