> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/destinations/categories/database/big_query.md).

# BigQuery

Send data to BigQuery with automatic schema detection and append mode via Coupler.io.

Google BigQuery is a fully managed, serverless data warehouse that lets you run fast SQL queries on large datasets. It's ideal for analytics, reporting, and data pipelines — and it scales automatically as your data grows.

Using BigQuery as a Coupler.io destination lets you load structured data from any supported source directly into your data warehouse, without writing any ETL code.

## Why use BigQuery as a destination?

* **Centralize your data** — pull from marketing tools, CRMs, spreadsheets, and more into a single place for SQL-based analysis
* **Automate pipelines** — schedule data loads on any cadence without manual exports or scripts
* **Works with any Coupler.io source** — any source Coupler.io supports can be routed to BigQuery
* **Flexible schema control** — let BigQuery auto-detect column types, or define your own schema manually for full control
* **BI-ready** — data lands in BigQuery ready for Data Studio, Power BI, or any SQL-compatible analytics tool

## Prerequisites

Before you start, make sure you have:

* A **Google Cloud Platform account** with a BigQuery project and dataset already created
* A **Service Account** with the correct IAM roles (see [Permission errors](#bigquery-common-issues) if you're unsure)
* A **JSON key file** downloaded from your GCP Service Account — this is how Coupler.io authenticates with BigQuery

## Quick start

{% hint style="success" %}
Have your GCP JSON key file ready before you begin. You'll upload it during the connection step. If you haven't created one yet, follow Coupler.io's guide on generating a Google Cloud JSON key file first.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Add a source to your data flow.** In Coupler.io, create a new data flow and configure at least one source. This can be any supported integration — Airtable, Facebook Ads, Clockify, and so on. You must have a source connected before you can save and run the data flow.
{% endstep %}

{% step %}
**Select BigQuery as your destination.** In the Destination step of your data flow, choose **BigQuery** from the list of available destinations.
{% endstep %}

{% step %}
**Upload your JSON key file.** Click **Select file** and upload the JSON key file you downloaded from your GCP Service Account. This file authenticates Coupler.io with your BigQuery project. Once uploaded, click **Save** to establish the connection.
{% endstep %}

{% step %}
**Set your dataset and table name.** Enter the **Dataset name** exactly as it appears in BigQuery (for example, `my_analytics_dataset`). Then enter a **Table name** — you can use an existing table or type a new name, and Coupler.io will create it automatically on the first run.
{% endstep %}

{% step %}
**Configure the schema (optional but recommended).** By default, BigQuery auto-detects column types from your data. If you need precise type control — or if your source sometimes returns empty datasets — disable the **Autodetect table schema** toggle and enter your schema as JSON. See the [schema definition guide](https://github.com/coupler-io/knowledge-base/blob/main/destinations/how-to-generate-bigquery-schema.md) for the format.
{% endstep %}

{% step %}
**Choose a write mode.** Select **Replace** to overwrite the table with fresh data on every run, or **Append** to add new rows below existing data. Replace is best for snapshots; Append is best for building historical logs.
{% endstep %}

{% step %}
**Run the data flow.** Click **Save and Run**. Coupler.io will load your data into BigQuery. Once the run completes successfully, open BigQuery to verify your table and data.
{% endstep %}
{% endstepper %}

## Supported features

| Feature                          | Supported                   |
| -------------------------------- | --------------------------- |
| Replace mode                     | Yes                         |
| Append mode                      | Yes                         |
| Automatic scheduling             | Yes                         |
| Type enforcement (manual schema) | Yes                         |
| OAuth sign-in                    | No (JSON key file required) |
| Templates                        | No                          |

## BigQuery common issues

### Connection issues

<details>

<summary>"Save and Run" button is greyed out</summary>

This happens when your data flow has no source connected yet. BigQuery requires at least one source to be fully configured before the data flow can be saved and run.

Go back to the Source step and make sure your source is connected and returning data, then return to the Destination step.

</details>

<details>

<summary>Connection fails after uploading the JSON key file</summary>

Double-check that you uploaded the correct file. The key file must be in **JSON format** and downloaded directly from a GCP Service Account. Common mistakes include uploading a `.p12` key, a key from the wrong project, or a file that has been renamed or modified.

If the file looks correct, verify that the Service Account is not disabled in GCP and that the key has not been revoked.

</details>

### Permission errors

<details>

<summary>"User does not have bigquery.datasets.create permission" or "Access Denied"</summary>

This means the GCP Service Account used for the connection doesn't have sufficient IAM permissions. Your Service Account needs one of the following combinations:

**Option 1 — Predefined roles:**

* `bigquery.dataEditor`
* `bigquery.jobUser`

**Option 2 — Individual permissions:**

* `bigquery.tables.create`
* `bigquery.tables.updateData`
* `bigquery.jobs.create`

After updating the roles in GCP, you must **generate a new JSON key file** and re-upload it to Coupler.io. Updating roles alone without replacing the key will not fix the error.

{% hint style="warning" %}
Role changes in GCP can take a few minutes to propagate. Wait a moment before generating and uploading the new key.
{% endhint %}

</details>

### Data issues

<details>

<summary>Column names appear as string_field_0, string_field_1, etc.</summary>

Coupler.io uses BigQuery's auto schema detection by default. BigQuery generates generic column names like `string_field_0` when it can't infer a proper schema. This happens in two situations:

1. **All columns contain only text values** — BigQuery needs at least one boolean, date/time, or numeric field to anchor the schema.
2. **The source dataset is empty** — BigQuery has no data to sample.

**To fix this:**

* If the dataset was empty, expand your reporting period or remove filters so data is returned, then rerun in **Replace** mode.
* If all columns are text, consider defining the schema manually by disabling **Autodetect table schema** and entering your column definitions as JSON.

See the [schema definition guide](https://github.com/coupler-io/knowledge-base/blob/main/destinations/how-to-generate-bigquery-schema.md) for the manual schema format.

</details>

<details>

<summary>"BigQuery doesn't allow values of multiple types in a single column"</summary>

This error occurs when a column's data type in BigQuery does not match the data type of the values Coupler.io is trying to load.

Currently, Coupler.io uses the schema defined on the **Datasets** preview tab. However, older BigQuery destination connectors have an option to either use BigQuery's automatic schema detection or a manually specified schema.

This error commonly occurs in the following situations:

* The source API starts returning a field as a different type. For example, integers sent as `545652.0` instead of `545652` .
* A column contained mixed types across different runs, and BigQuery locked in the wrong type
* **For the latest BigQuery destination connector:** The import mode is set to **Append**, but the data type defined in the existing BigQuery table does not match the data type defined in the **Datasets** preview.

{% hint style="danger" %}
This error will disable your data flow if left unresolved. Do not just retry — the underlying schema conflict needs to be fixed first.
{% endhint %}

**How to resolve the error:**

**If you're using an older BigQuery destination connector**

You have several options:

1. **Create a new BigQuery destination connector**\
   Create a new BigQuery destination connector and delete the old one. This allows the data types defined in the **Datasets** preview to take effect.
2. **Recreate the BigQuery table**\
   If the BigQuery table was auto-created, you may need to delete it and rerun the data flow in Replace mode to recreate it with the correct schema.
3. **Define the schema manually**\
   1\. Disable **Autodetect table schema** in your BigQuery destination settings.\
   2\. Define the schema manually, setting the affected column to the correct type (for example, `FLOAT` instead of `INTEGER`).\
   Please see more details on how to define the schema manually [here](https://docs.coupler.io/destinations/categories/database/big_query/how-to-generate-bigquery-schema-to-define-column-types-manually).

**If you're using the latest BigQuery destination connector**

Make sure that the data types defined in the **Datasets** preview match the corresponding data types in your existing BigQuery table.

If you're using **Append** mode, the existing table's schema must be compatible with the incoming data. If the schemas don't match, update the table schema or adjust the data types in the **Datasets** preview before running the data flow again.

</details>

<details>

<summary>A new column added to the source isn't appearing in BigQuery</summary>

When you add a new field to your source (for example, a new Airtable column), you also need to refresh the source schema inside Coupler.io. Open the Source step of your data flow, refresh the field list, confirm the new column is selected, then save and rerun.

If you're using a manually defined schema in BigQuery, you'll also need to add the new column to your schema definition before running — otherwise BigQuery will reject the extra field.

</details>

<details>

<summary>Source row limit reached — only partial data loads into BigQuery</summary>

If fewer rows are arriving in BigQuery than exist in your source, the limit is coming from your **Coupler.io plan**, not from BigQuery.

Upgrade your Coupler.io plan to increase the row limit for metered sources.

</details>

## BigQuery FAQ

<details>

<summary>Can I load data into a BigQuery table that doesn't exist yet?</summary>

Yes. If you enter a table name that doesn't exist in your BigQuery dataset, Coupler.io will create it automatically on the first run. You don't need to pre-create the table in BigQuery.

</details>

<details>

<summary>How does Coupler.io determine column types when loading data?</summary>

By default, Coupler.io relies on BigQuery's built-in **schema auto-detection**. BigQuery samples up to 500 rows from your data to infer column types. This works well for most cases, but can produce unexpected results when data contains mixed types or when the source returns an empty dataset.

If you need precise control over types, disable auto-detection and define your schema manually in the destination settings.

</details>

<details>

<summary>What's the best write mode for my use case?</summary>

It depends on what you want to do with the data:

* **Replace** — Best for dashboards and reports that always reflect the current state of your source. Every run overwrites the table with fresh data.
* **Append** — Best for building historical logs or tracking changes over time. Each run adds new rows below the existing data without touching what's already there.

If you're unsure, start with Replace. You can always switch to Append once your pipeline is stable.

</details>

<details>

<summary>How do I prevent schema type conflicts from breaking my data flow?</summary>

The most reliable approach is to disable **Autodetect table schema** and define your column types manually. Auto-detection samples a limited number of rows, so a field that's normally an integer but occasionally returns a float (like `545652.0`) can cause BigQuery to lock in the wrong type.

With a manual schema, you control exactly what type each column expects — and BigQuery won't change it between runs. See the [schema definition guide](https://github.com/coupler-io/knowledge-base/blob/main/destinations/how-to-generate-bigquery-schema.md) for instructions.

{% hint style="info" %}
If your data flow is already broken due to a schema conflict, you may need to delete the existing BigQuery table and rerun in Replace mode to recreate it with the correct schema.
{% endhint %}

</details>

<details>

<summary>What are the rules for BigQuery column names?</summary>

BigQuery column names must follow these rules:

* Only letters (`a–z`, `A–Z`), numbers (`0–9`), and underscores (`_`)
* Must start with a letter or underscore
* Maximum 300 characters
* Cannot begin with the reserved prefixes `_TABLE_`, `_FILE_`, or `_PARTITION_`

If your source has column names with spaces or special characters, use Coupler.io's transformation step to rename them before they reach BigQuery.

</details>

<details>

<summary>Can I force all columns to load as STRING type?</summary>

Yes. The most reliable way is to disable auto-detection and set all columns to `STRING` in your manual schema definition. Alternatively, you can structure your source data so that BigQuery's auto-detection infers strings — but manual schema definition is more predictable and easier to maintain.

</details>

<details>

<summary>Does Coupler.io support multiple sources sending data to the same BigQuery table?</summary>

Yes. A single Coupler.io data flow can include multiple sources. You can use **Append** or **Join** transformations to combine data from different sources before it lands in BigQuery. This lets you merge data from different tools into a single table without writing any code.

</details>

<details>

<summary>Where can I learn more about setting up the GCP Service Account and key file?</summary>

{% hint style="info" %}
Coupler.io has a dedicated guide on generating a Google Cloud JSON key file, including step-by-step instructions for creating a Service Account and assigning the correct roles. Look for it in the BigQuery setup section of the Help Center.
{% endhint %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/destinations/categories/database/big_query.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.