{
  "license": "CC BY 4.0",
  "recipe": {
    "slug": "usage-quota-burn-by-account",
    "title": "Calculate Usage Quota Burn by Account",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-28"
  },
  "contract": {
    "tableName": "usage_meter_events",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "When the billable activity completed in UTC."
      },
      {
        "name": "meter_event_id",
        "type": "Utf8",
        "description": "Idempotency key for one logical usage record."
      },
      {
        "name": "account_id",
        "type": "Utf8",
        "description": "Stable billing-account identifier."
      },
      {
        "name": "plan",
        "type": "Utf8",
        "description": "Plan that owned the quota when usage occurred."
      },
      {
        "name": "billable_units",
        "type": "Float64",
        "description": "Normalized units added by this event."
      },
      {
        "name": "included_units",
        "type": "Float64",
        "description": "Monthly included quota for the account and plan."
      }
    ]
  },
  "query": "WITH deduplicated_usage AS (\n  SELECT\n    meter_event_id,\n    account_id,\n    plan,\n    MAX(billable_units) AS billable_units,\n    MAX(included_units) AS included_units\n  FROM usage_meter_events\n  WHERE timestamp_utc >= date_trunc('month', now())\n  GROUP BY meter_event_id, account_id, plan\n)\nSELECT\n  account_id,\n  plan,\n  COUNT(*) AS meter_events,\n  SUM(billable_units) AS used_units,\n  MAX(included_units) AS included_units,\n  100.0 * SUM(billable_units)\n    / NULLIF(MAX(included_units), 0) AS quota_used_pct,\n  SUM(billable_units) - MAX(included_units) AS overage_units\nFROM deduplicated_usage\nGROUP BY account_id, plan\nORDER BY quota_used_pct DESC;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "meter_event_id": "meter_event_id_example_1",
      "account_id": "account_1",
      "plan": "plan_example_1",
      "billable_units": 420,
      "included_units": 420
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "meter_event_id": "meter_event_id_example_2",
      "account_id": "account_2",
      "plan": "plan_example_2",
      "billable_units": 840,
      "included_units": 840
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "meter_event_id": "meter_event_id_example_3",
      "account_id": "account_3",
      "plan": "plan_example_3",
      "billable_units": 610,
      "included_units": 610
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "meter_event_id": "meter_event_id_example_1",
      "account_id": "account_1",
      "plan": "plan_example_1",
      "billable_units": 420,
      "included_units": 420
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "meter_event_id": "meter_event_id_example_2",
      "account_id": "account_2",
      "plan": "plan_example_2",
      "billable_units": 840,
      "included_units": 840
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "meter_event_id": "meter_event_id_example_3",
      "account_id": "account_3",
      "plan": "plan_example_3",
      "billable_units": 610,
      "included_units": 610
    }
  ],
  "expectedOutput": {
    "columns": [
      "account_id",
      "plan",
      "meter_events",
      "used_units",
      "included_units",
      "quota_used_pct",
      "overage_units"
    ],
    "rows": [
      {
        "account_id": "account_harbor",
        "plan": "growth",
        "meter_events": 18420,
        "used_units": 1126000,
        "included_units": 1000000,
        "quota_used_pct": 112.6,
        "overage_units": 126000
      },
      {
        "account_id": "account_lumen",
        "plan": "growth",
        "meter_events": 12880,
        "used_units": 842000,
        "included_units": 1000000,
        "quota_used_pct": 84.2,
        "overage_units": -158000
      },
      {
        "account_id": "account_north",
        "plan": "starter",
        "meter_events": 3610,
        "used_units": 168000,
        "included_units": 250000,
        "quota_used_pct": 67.2,
        "overage_units": -82000
      }
    ]
  },
  "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."
  ]
}