BigQuery least privilege for agents

Agents should never hold a BigQuery project owner key. They should not even hold a service account that can list every dataset. Least privilege for agent-backed analytics means the agent authenticates to a semantic layer, and only that layer holds a narrow BigQuery identity.

datahashi is the thin layer in that path. You connect BigQuery with a dedicated read-only principal, publish metrics as an immutable YAML artifact, and let MCP clients call list_catalog, describe_metric, and run_semantic_query. No SQL in. No SQL out. The warehouse stays thick; the agent stays on the metric contract.

Separate three identities

Treat identity as three concentric rings:

1. Human admins who manage connections, publish models, and review YAML.
2. datahashi service principal that runs compiled SQL against BigQuery with the minimum dataset and table grants you need for published metrics.
3. Agent or MCP client credentials that talk only to datahashi, never to BigQuery directly.

If an agent config file is copied into a ticket, the blast radius stops at semantic queries the credential already allows. It does not become a stolen BigQuery key.

What the BigQuery principal should get

Create a dedicated Google Cloud service account for datahashi. Grant it bigquery.jobs.create at the project (or a job-scoped equivalent your org prefers) plus bigquery.dataViewer only on the datasets that back certified metrics. Prefer dataset-level or table-level grants over project-wide Data Viewer. Avoid roles that can mutate datasets, create transfers, or export to arbitrary buckets from this account.

Do not reuse the ETL writer identity. Writers need insert and update paths; semantic serving needs select and job create. Mixing them makes rotation painful and invites accidental write paths into agent infrastructure.

Point datahashi at that connection. Keep transforms, marts, and history in BigQuery. datahashi maps entities, dimensions, measures, and metrics; it does not become a second transformation system.

Agent surface stays metric-shaped

With the warehouse principal locked down, still lock the agent surface. An agent that can send freeform SQL through any tool will fish through schemas even under a read-only role. datahashi’s MCP tools are fixed on purpose:

• list_catalog to discover published metrics and dimensions
• describe_metric to learn grain, definition, and allowed slices
• run_semantic_query to execute the same request shape REST and the console use

That sameness is the governance payoff. A Slack answer and a Looker tile can cite the same metric version without inventing joins in the agent.

Row filters and field grants still matter

Least privilege is not only IAM. Bind field grants and row-level rules on the published model so the agent credential cannot request dimensions or rows outside policy. Metering already records principal, tenant, metric payload, and outcome. Use those logs when an agent asks for something surprising: inspect the semantic request first, then the compiled SQL in admin-only engine logs if your policy requires it.

What not to sell as day-one acceleration

Correct definitions come before acceleration fairy tales. Metering exists so you can observe usage. Rollups have shipped for repeated questions. They are not a p99 latency target. BigQuery slot and bytes-billed controls remain warehouse concerns.

Checklist to ship

1. Create a dedicated BigQuery service account for semantic reads.
2. Grant job create plus narrow data viewer on metric-backing datasets only.
3. Connect that account in datahashi; keep writer credentials elsewhere.
4. Publish an immutable metric model with field and row rules.
5. Issue agent credentials for datahashi only; register the six MCP tools.
6. Verify an agent can describe and run a metric, and cannot open a BigQuery client with the same secret.

Least privilege for agents on BigQuery is a stack of constraints: narrow warehouse IAM, server-side connection secrets, and a SQL-free MCP surface. datahashi is built to sit in the middle of that stack without widening any ring.