{
  "license": "CC BY 4.0",
  "recipe": {
    "slug": "authentication-failure-rate",
    "title": "Analyze Authentication Failure Rate",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-28"
  },
  "contract": {
    "tableName": "authentication_events",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "Authentication outcome time in UTC."
      },
      {
        "name": "actor_id",
        "type": "Utf8",
        "description": "Privacy-safe stable identity or session identifier."
      },
      {
        "name": "authentication_method",
        "type": "Utf8",
        "description": "password, oauth, sso, passkey, or another controlled value."
      },
      {
        "name": "outcome",
        "type": "Utf8",
        "description": "success or failed."
      },
      {
        "name": "failure_reason",
        "type": "Utf8",
        "description": "Controlled category; never a password or raw provider response."
      },
      {
        "name": "ip_country",
        "type": "Utf8",
        "description": "Coarse country code derived under the product's privacy policy."
      }
    ]
  },
  "query": "SELECT\n  date_trunc('hour', timestamp_utc) AS hour,\n  authentication_method,\n  failure_reason,\n  COUNT(*) AS attempts,\n  COUNT(DISTINCT actor_id) AS affected_actors,\n  SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS failed_attempts,\n  100.0 * SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END)\n    / NULLIF(COUNT(*), 0) AS failure_rate_pct\nFROM authentication_events\nWHERE timestamp_utc >= now() - INTERVAL '24 hours'\nGROUP BY\n  date_trunc('hour', timestamp_utc),\n  authentication_method,\n  failure_reason\nHAVING COUNT(*) >= 20\nORDER BY failed_attempts DESC, failure_rate_pct DESC;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "actor_id": "actor_id_example_1",
      "authentication_method": "authentication_method_example_1",
      "outcome": "success",
      "failure_reason": "failure_reason_example_1",
      "ip_country": "ip_country_example_1"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "actor_id": "actor_id_example_2",
      "authentication_method": "authentication_method_example_2",
      "outcome": "failed",
      "failure_reason": "failure_reason_example_2",
      "ip_country": "ip_country_example_2"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "actor_id": "actor_id_example_3",
      "authentication_method": "authentication_method_example_3",
      "outcome": "success",
      "failure_reason": "failure_reason_example_3",
      "ip_country": "ip_country_example_3"
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "actor_id": "actor_id_example_1",
      "authentication_method": "authentication_method_example_1",
      "outcome": "success",
      "failure_reason": "failure_reason_example_1",
      "ip_country": "ip_country_example_1"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "actor_id": "actor_id_example_2",
      "authentication_method": "authentication_method_example_2",
      "outcome": "failed",
      "failure_reason": "failure_reason_example_2",
      "ip_country": "ip_country_example_2"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "actor_id": "actor_id_example_3",
      "authentication_method": "authentication_method_example_3",
      "outcome": "success",
      "failure_reason": "failure_reason_example_3",
      "ip_country": "ip_country_example_3"
    }
  ],
  "expectedOutput": {
    "columns": [
      "hour",
      "authentication_method",
      "failure_reason",
      "attempts",
      "affected_actors",
      "failed_attempts",
      "failure_rate_pct"
    ],
    "rows": [
      {
        "hour": "2026-07-28 10:00",
        "authentication_method": "sso",
        "failure_reason": "provider_timeout",
        "attempts": 680,
        "affected_actors": 412,
        "failed_attempts": 156,
        "failure_rate_pct": 22.94
      },
      {
        "hour": "2026-07-28 10:00",
        "authentication_method": "password",
        "failure_reason": "invalid_credential",
        "attempts": 4280,
        "affected_actors": 3110,
        "failed_attempts": 318,
        "failure_rate_pct": 7.43
      },
      {
        "hour": "2026-07-28 10:00",
        "authentication_method": "passkey",
        "failure_reason": "user_cancelled",
        "attempts": 910,
        "affected_actors": 842,
        "failed_attempts": 48,
        "failure_rate_pct": 5.27
      }
    ]
  },
  "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."
  ]
}