# BigQuery

> Connect a Search Console bulk export in BigQuery so the Traffic lists read every query and page from it instead of the API.

Page: https://serplyze.com/docs/bigquery

The Search Console API returns a limited number of rows per request. If your property exports its data to BigQuery with Search Console's bulk data export, Serplyze can read the query and page lists from that export instead and show more rows.

You connect one export per project with a Google Cloud service account. Serplyze only runs read queries against it.

> **Plan:** The BigQuery connection is part of the paid plans. On Free the card shows what it does and a link to the plans.

## Before you start

- The bulk data export must be turned on for the property in Google Search Console, under **Settings → Bulk data export**. Google starts filling the dataset after that; Serplyze cannot turn it on for you or backfill it.
- The export dataset must contain the two tables Google writes: `searchdata_site_impression` and `searchdata_url_impression`. The default dataset name is `searchconsole`.
- You need permission in the Google Cloud project to create a service account and grant it roles.
- In Serplyze you must be an owner or admin of the workspace.

## Create the service account

1. In the Google Cloud project that holds the export, create a service account.
2. Grant it **BigQuery Data Viewer** on the export dataset, so it can read the tables.
3. Grant it **BigQuery Job User** on the project, so it can run queries.
4. Create a JSON key for the service account and download the file.

No other role is needed. Serplyze does not write to the dataset, and the two roles limit what the key can do.

## Connect it in Serplyze

1. Open **Settings → Search Console** for the project and find the **BigQuery bulk export** card.
2. Select **Set up BigQuery export**.
3. Enter the **Google Cloud project id** and the **Dataset** name. **Location** is optional (for example `US` or `EU`).
4. Under **Service-account key (JSON)**, choose the key file you downloaded.
5. Select **Connect and test**. Serplyze saves the key and runs the test query right away.

The file must be a service-account key: JSON with `type` set to `service_account`, a `client_email`, a `private_key` and a `project_id`. Other files are rejected with a message that says what is missing.

## The test query

The test reads the first and the last day in `searchdata_site_impression`. It scans one date column, so it is cheap. The card then shows one of these states:

| Status | Meaning |
| --- | --- |
| Working | The test succeeded. The card shows the days the export covers, for example data from 2025-01-03 to 2026-03-12. |
| Not working | The last test failed. The card shows Google's error, usually a missing role, a wrong dataset name or a wrong location. |
| Not tested yet | A key is saved but no test has finished. Select **Test again**. |
| Not set up | No connection for this project. |

Use **Test again** after you change roles in Google Cloud, and **Replace key** to upload a new key or change the project, dataset or location.

## What changes once connected

Only a connection with the status Working is used. While it is in any other state, or while the workspace is on Free, Serplyze reads from the Search Console API as before.

- The Pages, Queries and Query × page lists of the [Traffic](https://serplyze.com/docs/traffic.md) screen read from BigQuery.
- The daily chart on a page's detail view reads from BigQuery.
- The query search you use when adding keywords reads from BigQuery.
- The `pages` and `queries` endpoints of the [REST API](https://serplyze.com/docs/rest-api.md) and the Pages and Queries datasets of [live CSV links](https://serplyze.com/docs/google-sheets.md) return the same lists; the API marks them with `source.kind` set to `bigquery`.

| List | Search Console API | BigQuery export |
| --- | --- | --- |
| Queries | up to 50,000 rows per range | up to 100,000 rows per range |
| Pages | up to 25,000 rows per range | up to 100,000 rows per range |
| Query × page | up to 50,000 rows per range | up to 100,000 rows per range |

> **Limit:** Tracked keyword positions, site totals and breakdowns are still synced from the Search Console API, not from BigQuery. The export only holds the days Google has written to it; the card shows which days those are.

## Costs

Queries run as jobs in the Google Cloud project you entered, so BigQuery usage is billed by Google to that project under your own BigQuery pricing. Serplyze does not charge extra for the connection. Lists are cached after they are fetched, so reopening the same view does not run the query again.

## How the key is stored

- The key file is sent once, when you save the dialog, and is encrypted on the server with the same envelope encryption as your Google tokens. See [Security and privacy](https://serplyze.com/docs/security-and-privacy.md).
- It is never shown again, not to you and not to other members. The card shows only the service account's email address, the project and the dataset.
- Only the background service that fetches data from Google can read the encrypted key.

## Disconnect

1. Open the **BigQuery bulk export** card in **Settings → Search Console**.
2. Select **Remove connection** and confirm.

- The stored service-account key is deleted.
- The Traffic lists of the project go back to the Search Console API.
- Your BigQuery export itself is not changed. To stop access on the Google side as well, delete the key or the service account in Google Cloud.
- You can remove a connection on any plan, including after a downgrade to Free.

## Read next

- [Traffic](https://serplyze.com/docs/traffic.md): The Traffic screen: site totals, breakdowns and the full lists of pages, queries, folders and page groups from Search Console.
- [REST API](https://serplyze.com/docs/rest-api.md): Read projects, tracked keywords, groups, site totals, breakdowns, pages, queries, alerts and notes as JSON with a workspace API key.
- [Google access](https://serplyze.com/docs/google-access.md): Which Google permission Serplyze asks for, what it can and cannot do with it, and how to reconnect or revoke it.
- [Security and privacy](https://serplyze.com/docs/security-and-privacy.md): How you sign in, what Serplyze can read at Google, how workspaces are kept apart, how secrets are encrypted and who processes your data.