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

# How to connect

> How to connect the Google BigQuery data source to Adriel: authorize a Google account, choose a project, dataset, and table, and query it live from dashboards.

Google BigQuery lets any table in a Google Cloud project act as a custom data source in Adriel: its columns become candidate metrics, breakdowns, and date fields based on their BigQuery type. Connecting it brings customer-side data — orders, signups, internal events, and similar tables not available through standard ad or analytics data sources — directly into dashboards.

## Before you connect

The following are required:

* A Google account with read access to the target BigQuery dataset. The **BigQuery Data Viewer** and **BigQuery Job User** roles are sufficient.
* The Google Cloud project, dataset, and table to connect.
* An optional pre-filter clause, if every query should be scoped to a fixed `WHERE` condition (for example, a tenant column).
* Workspace permission to add a new data source.

<Note>
  Queries run live on demand each time a widget loads, and each query is billed by Google Cloud. Identical queries are served from a short result cache for 10 minutes to limit redundant scans.
</Note>

## Connect Google BigQuery

<Steps>
  <Step title="Authorize a Google account">
    On the **Data Sources** page, search for **Google BigQuery** and select it. Click **Sign in with Google** in the pop-up and sign in with the account that has read access to the target dataset. Click **Continue** to grant the requested BigQuery scope. Authorization returns to the data source setup screen.
  </Step>

  <Step title="Choose the project, dataset, and table">
    On the data source settings, choose the **Project**, **Dataset**, and **Table** to connect. Only projects and datasets readable by the authorized Google account appear. Each table becomes its own data source.
  </Step>

  <Step title="Add a pre-filter (optional)">
    Configure a **pre-filter** to scope every query against this data source — either a free-form `WHERE` clause or a column-level filter. The two modes are mutually exclusive.
  </Step>

  <Step title="Submit">
    Click **Submit** to validate the connection and finalize the data source. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

Table columns become available as metrics or breakdowns depending on their type. A synthetic `rowCount` field returns `COUNT(*)` for total-row dashboards. Date-typed columns can be mapped through Blend Data settings to drive widget-level date filtering.

For supported column types, query behavior, filter operators, and the full field model, see the [Google BigQuery data reference](/data-sources/g-n/google-bigquery/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="REFRESH_TOKEN_INVALID error">
    The OAuth refresh token has been revoked — usually because the Google account lost access, its password changed, or the connection was revoked from Google account permissions. The data source is automatically disconnected when this fires. Reconnect via **Connections** → **Google BigQuery** → **Reconnect**.
  </Accordion>

  <Accordion title="Queries return zero rows despite data in BigQuery">
    A pre-filter configured at connection time runs on every query. If the clause references a missing column or filters on an incorrect value, no rows match. Edit or remove the filter in the data source settings.
  </Accordion>

  <Accordion title="Results appear truncated">
    Each query is limited to 1,000 rows for stability and performance. Narrow the query with a pre-filter or a mapped date column so the rows that matter fall within the cap.
  </Accordion>

  <Accordion title="BigQuery costs rise after connecting">
    Every widget triggers a live query, and each query is billed by Google Cloud. Map a date column through Blend Data so queries scan less data, reduce the number of BigQuery-backed widgets, and use unfold actions sparingly. Identical queries within a 10-minute window are cached automatically.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Google BigQuery data reference" href="/data-sources/g-n/google-bigquery/data-reference">
    Column types, query behavior, filter operators, and the full field model.
  </Card>

  <Card title="Google BigQuery FAQs" href="/data-sources/g-n/google-bigquery/faqs">
    Common questions and expected behaviors for the Google BigQuery data source.
  </Card>

  <Card title="How to connect Postgres" href="/data-sources/o-z/postgres/how-to-connect">
    Connect a Postgres database as a custom data source.
  </Card>

  <Card title="How to connect Redshift" href="/data-sources/o-z/redshift/how-to-connect">
    Connect an Amazon Redshift warehouse as a custom data source.
  </Card>
</CardGroup>