{
  "license": "CC BY 4.0",
  "recipe": {
    "slug": "database-replica-staleness-by-region",
    "title": "Measure Database Replica Staleness by Region",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-28"
  },
  "contract": {
    "tableName": "database_replica_read_events",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "Replica read completion time."
      },
      {
        "name": "region",
        "type": "Utf8",
        "description": "Application region."
      },
      {
        "name": "replica_role",
        "type": "Utf8",
        "description": "primary, replica, or failover target."
      },
      {
        "name": "replay_lag_ms",
        "type": "Float64",
        "description": "Observed or reported replay lag."
      },
      {
        "name": "consistency_outcome",
        "type": "Utf8",
        "description": "fresh, stale, failed, or unknown."
      },
      {
        "name": "operation_name",
        "type": "Utf8",
        "description": "Controlled application read operation."
      }
    ]
  },
  "query": "SELECT\n  region,\n  replica_role,\n  operation_name,\n  COUNT(*) AS reads,\n  approx_percentile_cont(replay_lag_ms, 0.95) AS p95_replay_lag_ms,\n  SUM(CASE WHEN consistency_outcome = 'stale' THEN 1 ELSE 0 END)\n    AS stale_reads,\n  SUM(CASE WHEN consistency_outcome = 'failed' THEN 1 ELSE 0 END)\n    AS failed_reads\nFROM database_replica_read_events\nWHERE timestamp_utc >= now() - INTERVAL '24 hours'\nGROUP BY region, replica_role, operation_name\nORDER BY stale_reads DESC, p95_replay_lag_ms DESC;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "region": "region_example_1",
      "replica_role": "replica_role_example_1",
      "replay_lag_ms": 12,
      "consistency_outcome": "success",
      "operation_name": "operation_name_example_1"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "region": "region_example_2",
      "replica_role": "replica_role_example_2",
      "replay_lag_ms": 37,
      "consistency_outcome": "failed",
      "operation_name": "operation_name_example_2"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "region": "region_example_3",
      "replica_role": "replica_role_example_3",
      "replay_lag_ms": 24,
      "consistency_outcome": "success",
      "operation_name": "operation_name_example_3"
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "region": "region_example_1",
      "replica_role": "replica_role_example_1",
      "replay_lag_ms": 12,
      "consistency_outcome": "success",
      "operation_name": "operation_name_example_1"
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "region": "region_example_2",
      "replica_role": "replica_role_example_2",
      "replay_lag_ms": 37,
      "consistency_outcome": "failed",
      "operation_name": "operation_name_example_2"
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "region": "region_example_3",
      "replica_role": "replica_role_example_3",
      "replay_lag_ms": 24,
      "consistency_outcome": "success",
      "operation_name": "operation_name_example_3"
    }
  ],
  "expectedOutput": {
    "columns": [
      "region",
      "replica_role",
      "operation_name",
      "reads",
      "p95_replay_lag_ms",
      "stale_reads",
      "failed_reads"
    ],
    "rows": [
      {
        "region": "ap-southeast",
        "replica_role": "replica",
        "operation_name": "subscription-status",
        "reads": 18400,
        "p95_replay_lag_ms": 4820,
        "stale_reads": 214,
        "failed_reads": 18
      },
      {
        "region": "eu-west",
        "replica_role": "replica",
        "operation_name": "project-list",
        "reads": 42100,
        "p95_replay_lag_ms": 740,
        "stale_reads": 31,
        "failed_reads": 2
      }
    ]
  },
  "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."
  ]
}