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

# Connect BigQuery

> Set up Google sign-in or a service account, grant read access, and verify a query from Deepline.

You need a Deepline workspace owner or admin and a Google Cloud admin who can grant access to the billing project and the datasets you want to query.

## 1. Find your project, dataset, and location

1. Open [BigQuery Studio](https://console.cloud.google.com/bigquery). In **Explorer**, expand the project and click the dataset you want Deepline to read.
2. On **Details**, record the **Dataset ID** and **Data location**. Use the exact location, such as `US`, `EU`, or `us-central1`.
3. Choose the Google Cloud project that will run and pay for query jobs. Copy its **Project ID**, such as `aero-396620`. The project ID can differ from the project that contains the data. If the two projects differ, leave **Default dataset** blank and use fully qualified table names in queries.
4. In that billing project, open **APIs & Services > Library**, search for **BigQuery API**, and enable it if needed. Confirm that billing is enabled for the project.

| Deepline field | Value |
| - | - |
| **Billing project ID** | The Google Cloud project ID where query jobs run. |
| **Default dataset** | Optional. Enter only the dataset ID, such as `analytics_123456789`, if it belongs to the billing project. |
| **Location** | Optional. Set it to the dataset's exact **Data location** for predictable query routing. |

## 2. Choose how Deepline signs in

### Google sign-in

Use the Google account that will run queries. Its email address is the principal for the access grants below. After the grants are in place, select **Sign in with Google** in Deepline, enter the billing project and optional query settings, then click **Sign in with Google** to open consent. Choose the same Google account and return to Deepline after granting access.

### Service account

1. In Google Cloud, open **IAM & Admin > Service Accounts**. Select the project that will own the service account.
2. Click **Create service account**, enter a name such as `deepline-bigquery-reader`, and click **Done** after creating it. Copy its full email address. This is the principal for the grants below.
3. After granting access, open the service account, select **Keys > Add key > Create new key > JSON > Create**. Open the downloaded JSON file and paste its full contents into **Service account JSON** in Deepline. The file includes `type: service_account`, `project_id`, `client_email`, and `private_key`. Enter the billing project and optional query settings, then click **Save**.

If your organization blocks creation of JSON keys, use Google sign-in or ask your Google Cloud admin for an approved credential. Paste keys only into the Deepline credential field. [Create or rotate a service account key](https://docs.cloud.google.com/iam/docs/keys-create-delete)

### Grant access to the principal you chose

1. **Billing project:** Open **IAM & Admin > IAM** in the project that runs query jobs. Click **Grant access**, enter the user or service account email, and assign **BigQuery Job User** (`roles/bigquery.jobUser`).
2. **Each source dataset:** In BigQuery Studio, select the dataset, then **Sharing > Permissions > Add principal**. Enter the same email and assign **BigQuery Data Viewer** (`roles/bigquery.dataViewer`). Repeat for each dataset Deepline should read.
3. In Deepline, switch to the correct workspace and open [Integrations > BigQuery](https://code.deepline.com/dashboard/integrations?connect=bigquery). Click **Connect** or **Change credentials** and complete the sign-in method you selected above.

## 3. Verify the connection and dataset

After the Integrations page shows BigQuery as connected, click **Test** on the BigQuery row. This runs `SELECT 1 AS ok` and checks that the connected identity can start a query job. Then test access to the actual dataset. For example, replace the project, dataset, and table below with your values.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline run bigquery_run_query --input '{
  "query": "SELECT 1 AS ok FROM `data-project.analytics_123456789.events_20261115` LIMIT 1",
  "rowLimit": 1,
  "maximumBytesBilled": "10000000"
}'
```

Expect a row with `ok = 1` for a nonempty table. An empty table can return zero rows without an error. To verify the scorecard, use one daily table from your GA4 export dataset and confirm the dataset location matches your connection.

| Error or symptom | What to check |
| - | - |
| `bigquery.jobs.create` denied | Grant **BigQuery Job User** on the **billing project** to the principal you connected. |
| Test passes but reading a table fails with access denied | Grant **BigQuery Data Viewer** on the **source dataset**, then check the fully qualified table name. |
| Dataset or table was not found in a location | In BigQuery Studio, check the dataset's **Data location**. Update **Location** in Deepline and check the data project, dataset, and table IDs. |
| Service account JSON is invalid | Paste the complete downloaded key. Check that it contains the service account project ID and that Google Cloud lists the key as active. |
| Google rejects the authorization request | Start a fresh sign-in from the BigQuery form. If your Workspace blocks the Deepline app, ask your Google Workspace admin to review app access. |

See [Google's guide to BigQuery access](https://docs.cloud.google.com/bigquery/docs/create-authorized-views) for the distinction between the project that runs a job and the dataset that contains the data.


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