> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery

Google BigQuery is a serverless data warehouse built for fast SQL analytics over large datasets. Connecting BigQuery to Duvo lets your agents query your data warehouse directly, pulling metrics, running analyses, and feeding results into automated workflows.

## Setup

<Steps>
  <Step title="Confirm prerequisites" icon="circle-check">
    <Check>A Google Cloud project with the [BigQuery API enabled](https://console.cloud.google.com/apis/library/bigquery.googleapis.com).</Check>
    <Check>A service account with a JSON key file.</Check>

    <Tip>
      Need to create a key? Follow Google's [Create and delete service account keys](https://cloud.google.com/iam/docs/keys-create-delete) guide.
    </Tip>
  </Step>

  <Step title="Grant the required permissions" icon="key">
    Grant the service account these IAM roles on the project (or on specific datasets if you prefer tighter scoping):

    * **BigQuery Job User** (`roles/bigquery.jobUser`) — required to run query jobs
    * **BigQuery Data Viewer** (`roles/bigquery.dataViewer`) — required to read table and view data

    If your tables use column-level access control, the service account also needs the **Data Catalog Fine-Grained Reader** role (`roles/datacatalog.categoryFineGrainedReader`) on the relevant policy tags to read protected columns.

    <Warning>
      Treat the service account JSON key as a secret. Don't share it or commit it to source control, and rotate the key in Google Cloud if you suspect it has been exposed. Scope the service account's roles to only the projects and datasets your agents need.
    </Warning>
  </Step>

  <Step title="Add the connection in Duvo" icon="plug">
    On the [Connections page](https://app.duvo.ai/integrations), open BigQuery and fill in these fields:

    <ParamField body="Service Account" type="JSON" required>
      The full contents of your service account JSON key file. Open the downloaded `.json` file in a text editor, copy everything, and paste it here. The JSON must include `project_id`, `client_email`, and `private_key` fields.
    </ParamField>
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Third-party documentation" icon="book">
    * [Authenticating with a service account key file](https://cloud.google.com/bigquery/docs/authentication/service-account-file)
    * [BigQuery IAM roles and permissions](https://cloud.google.com/bigquery/docs/access-control)
    * [Control access to resources with IAM](https://cloud.google.com/bigquery/docs/control-access-to-resources-iam)
  </Accordion>
</AccordionGroup>

## Capabilities

* **Run SQL queries** — Execute standard SQL against any dataset and table your service account can access, including aggregation and filtering queries.
* **Explore schemas** — List available datasets, tables, and column definitions using BigQuery's `INFORMATION_SCHEMA` views.
* **Export results** — Query results are automatically saved as files in your workspace, optimized for efficient downstream processing by your agent.

## Key Benefits

* **Direct warehouse access** — Query petabytes of data without manual exports or CSV downloads.
* **Real-time insights** — Pull current metrics and KPIs straight from your data warehouse into automated workflows.
* **Secure, scoped access** — Service account permissions control exactly which projects and datasets your agents can reach.
* **Data-driven automation** — Combine warehouse data with other connections to make intelligent decisions within a workflow.

## Things to Know

* **Query results are capped** — A single query export returns at most 1,000,000 rows (or roughly 1 GiB of result data, not bytes scanned, whichever is hit first). Queries under the cap are unaffected.
* **Truncated results are flagged** — When a result hits the cap, the agent receives the rows up to the cap along with a clear truncation notice, so a partial result is never mistaken for the full set. The agent can then refine the query, for example by adding filters, aggregating in SQL, or selecting fewer columns.
* **To retrieve more than the cap, page through the results** — Request successive batches using a stable sort key, with `WHERE key > last-key ORDER BY key`. Adding a `LIMIT` does not help: it returns fewer rows, not the rest.
* **Design queries for summaries, not dumps** — For very large tables, ask agents to aggregate or filter in SQL rather than exporting raw rows. This keeps results under the cap and speeds up downstream processing.

## Works Well With

<CardGroup cols={3}>
  <Card title="Google Sheets" icon="https://mintcdn.com/duvo-d8027998/O3tlM6eCuFk2uJpN/images/connections/google-sheets.svg?fit=max&auto=format&n=O3tlM6eCuFk2uJpN&q=85&s=0ef8d55e05c34e7a4a618933bdf0ceb3" href="/user-guide/connections/available-connections/google-sheets" width="24" height="24" data-path="images/connections/google-sheets.svg">
    Query BigQuery for raw data, then write summaries or reports into a spreadsheet for stakeholders.
  </Card>

  <Card title="Slack" icon="https://mintcdn.com/duvo-d8027998/O3tlM6eCuFk2uJpN/images/connections/slack.svg?fit=max&auto=format&n=O3tlM6eCuFk2uJpN&q=85&s=8a64bdd1af39e903923e4a273b4a4618" href="/user-guide/connections/available-connections/slack" width="512" height="512" data-path="images/connections/slack.svg">
    Pull key metrics from your warehouse and post automated updates to team channels.
  </Card>

  <Card title="Gmail" icon="https://mintcdn.com/duvo-d8027998/O3tlM6eCuFk2uJpN/images/connections/gmail.svg?fit=max&auto=format&n=O3tlM6eCuFk2uJpN&q=85&s=ad4e229283f3fe2f26c0f96a49f28e13" href="/user-guide/connections/available-connections/gmail" width="88" height="66" data-path="images/connections/gmail.svg">
    Generate data-driven reports from BigQuery and email them on a schedule.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.