Skip to content

BigQuery finops: surface bq_region + actionable error messages + warehouse_add warning #755

@anandgupta42

Description

@anandgupta42

Sub-issue split out of #754 to make a focused PR. Covers four of the seven items.

Scope (this issue)

  1. Surface bq_region in BigQuery finops tool responses — every finops tool (finops_query_history, finops_analyze_credits, finops_expensive_queries, finops_warehouse_advice, finops_unused_resources, finops_role_grants) returns the queried region as a top-level field on success and error paths. Lets the agent (and humans inspecting tool output) see which region was actually queried after the silent us fallback in fix: BigQuery finops SQL — correct INFORMATION_SCHEMA columns + multi-region support #739.

  2. augmentBqError(error, region) helper — appends a region hint to BQ errors that look region-related (anchored to region-<x>.INFORMATION_SCHEMA and Not found: patterns), idempotent, safe on non-region errors. Wired into all five finops catch blocks.

  3. isBqPermissionError(error) helper — detects the TABLE_STORAGE 403 pattern that finops_unused_resources hits routinely on project-scoped service accounts, with a word-boundary \b403\b check so unrelated numerics (4031, 40322, port 4030) don't false-positive. Produces an actionable message naming bigquery.resourceAdmin.

  4. warehouse_add non-fatal warning — fires when a BigQuery connection is registered without a location field (or with a whitespace-only value). Lists the affected finops tools and tells the user to re-add the connection with "location": "<region>" for non-US projects.

Out of scope (remain in #754)

  1. Distinguish "no location provided" vs "location provided but sanitized to empty" — behaviour change with cross-region compliance implications, needs separate consideration.
  2. Refactor BQ finops builders to options-object — pure code structure change.
  3. E2E test silent-skip warning — test infrastructure improvement.

Reference

Surfaced during the v0.6.1 release review (CTO/PM/Data Engineer/Tech Lead/Chaos Gremlin five-persona panel + 8-model consensus review).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions