bq-usage-report

name	bq-usage-report
description	Report BigQuery usage from INFORMATION_SCHEMA.JOBS_BY_PROJECT. Use when the user asks how much BigQuery quota, bytes processed, slot time, or expensive query usage a project/account has consumed recently.

bq-usage-report

Summarize recent BigQuery job usage. This skill inspects job metadata, not table contents.

Defaults

• Billing project: use the project in docs/bigquery/AGENTS.md, gcloud config get-value project, or ask the user.
• Region: default to region-us unless project docs specify another region.
• Windows: support 1, 7, and 30 days.

Query Template

Use Standard SQL:

SELECT
  COUNT(*) AS job_count,
  SUM(total_bytes_processed) AS bytes_processed,
  SUM(total_slot_ms) AS slot_ms,
  COUNTIF(cache_hit) AS cache_hit_count,
  COUNTIF(statement_type != 'SELECT') AS non_select_count
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY);

For expensive jobs:

SELECT
  creation_time,
  user_email,
  job_id,
  statement_type,
  total_bytes_processed,
  total_slot_ms,
  cache_hit,
  CAST(NULL AS STRING) AS query
FROM `region-us`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE creation_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
ORDER BY total_bytes_processed DESC
LIMIT 20;

Default to omitting full query text. If the user explicitly asks to inspect query text, include it in terminal output only, then summarize instead of pasting full queries into project docs.

Reporting

Report bytes in both raw bytes and human units. Mention whether usage is driven by table scans, metadata queries, cached jobs, or non-SELECT jobs when visible.

If the user asks whether a query is safe to run, use dry-run first. Compare the estimated bytes processed with the project's threshold from docs/bigquery/AGENTS.md or the default 100GB.