# Google BigQuery

Nimbata's Google BigQuery integration adds a row to a table in your own Google BigQuery for each call or form submission a workflow sends there. You can then query your calls with SQL, join them with your other data, or report on them in Looker Studio and other tools. Each row has Nimbata's own columns (which call or form submission it is, its project, its time and what sent it), then one text column for each field you choose, such as the caller's number, the tracking source or the tags.

Each Nimbata project has its own setup, and one project can send to several tables, such as one for calls and one for form submissions. Several projects can also send to the same table.

**Before you start**

- Permissions: Google BigQuery, under Integrations, in your Nimbata role
- A Google Cloud project with billing turned on (see the warning below).
- A Google account that can create tables and write to them in that project, such as one with the **BigQuery Data Editor** role there.
- The **Google BigQuery** tile on your Integrations page. Google BigQuery comes with the same plans as Google Sheets. On a plan that does not include it, **Go to integration** offers an upgrade instead.

> **Warning:** Nimbata streams rows into BigQuery as they happen, and BigQuery takes streamed rows only in a Google Cloud project with billing turned on, not in its free sandbox. Turn on billing for the project in the Google Cloud console before you start. Without it, the test row fails with "This Google Cloud project has no billing, which BigQuery needs before it takes rows. Turn on billing in Google Cloud, or choose another project."

> **Note:** A dataset or table made while the project was still in BigQuery's sandbox expires after 60 days, and keeps that expiration after you turn on billing. Remove the expiration in Google Cloud, or create a new dataset once billing is on.

Google bills that project for the rows Nimbata streams into it and for the queries you run, at the rates on Google's BigQuery pricing page. Streaming is billed by the amount of data, and the row of a call or form submission is small.

## Connect Google BigQuery

1. **Open the Google BigQuery integration**

   Go to **Integrations** and click **Go to integration** on the **Google BigQuery** tile (1).

   [The Google BigQuery tile on the Integrations page, with Go to integration marked 1]

   *Open the Google BigQuery tile (1).*

2. **Click Continue with Google**

   Click **Continue with Google** (1). If another project of your organization is already connected to Google BigQuery, Nimbata first asks which account to use, under **Connect Google BigQuery**: pick that account, and this project shares its connection, or click **Use another account** to sign in to Google.

   [The Google BigQuery integration page before it is connected, with the Continue with Google button marked 1]

   *Click Continue with Google (1).*

3. **Allow access to BigQuery**

   Sign in with the Google account that can use your Google Cloud project, and allow the access Google asks for. Keep the box for Google BigQuery ticked: without it, Nimbata does not connect and says "Google BigQuery access wasn't granted, so tables can't be listed, created or written to. Please connect again and, on Google's consent screen, tick the box that allows access to your data in Google BigQuery."

   Once you are connected, the page shows your Google account's email next to **Google BigQuery**.

To disconnect later, open the three-dot menu at the top right and click **Disconnect**. When other projects share the connection, it says **Disconnect this project**: only this project stops sending, and the others keep the Google account. Your tables stay set up.

## Add a table

Each card on the Google BigQuery page sends one kind of event, calls or form submissions, to one BigQuery table. The page starts with a card named **BigQuery table 1**, and **Add table** at the top adds another. A card shows **Needs attention** until its table is added.

1. **Name the card**

   Click the card's name, **BigQuery table 1**, type a name such as `Calls`, and press Enter. Workflows list the table by this name. A name has up to 100 letters, digits, spaces and underscores.

2. **Choose calls or forms**

   At the top of the card, choose **Call** (1) to send calls, or **Form** to send form submissions. This cannot change once the table is added, because a table has the columns of its kind.

3. **Choose the Google Cloud project**

   Under **Destination table**, choose your project in **Google Cloud project** (2). The list holds the projects your Google account can use. If yours is missing, click **Not listed? Enter its ID** and type the project's ID, such as `my-project-123`.

4. **Choose or create the dataset**

   Choose a dataset in **Dataset** (3). To make a new one, type its name under **or create a new dataset** (letters, numbers and underscores), choose where BigQuery stores it, such as **US (multiple regions in the United States)**, and click **Create**. Nimbata creates it and chooses it. A dataset's location cannot change later.

5. **Choose or create the table**

   To have Nimbata create the table, type its name under **or create a new table** (4), such as `calls`. Nimbata creates it when you add the card, with its own columns, one column for each field and a `calls_latest` view (see [What your table looks like](#what-your-table-looks-like)).

   To use a table you already have, choose it in **Table** instead. Nimbata checks that it has Nimbata's columns, adds a column for each field it lacks and creates its `_latest` view. It removes and changes nothing. A table this project already sends to is marked **(already added)**.

   A table name has letters, numbers and underscores, and cannot end with `_latest`, the name Nimbata gives the table's view.

   [A new Google BigQuery table card: Call chosen, marked 1; the Google Cloud project Harbor & Pine Analytics (harborpine-analytics), marked 2; the dataset nimbata (US), marked 3; and calls typed as the new table's name, marked 4, above the Add table button]

   *Choose Call (1), the Google Cloud project (2) and the dataset (3), and name the new table (4).*

6. **Choose the fields**

   Under **Fields**, tick the fields to send (1). A new table starts with the fields a new Google Sheets sheet starts with. Each field becomes a text column named by the key under its label, such as `call_duration` for **Call Duration**. **Search fields** finds a field by its label or its key. A table sends up to 200 fields.

   A field marked **Not a column name** cannot be sent, because its key cannot name a BigQuery column: it starts with `nimbata_`, which Nimbata keeps for its own columns, or it has characters a column name cannot have.

   [The Fields list of a new call table, 18 selected, searched for duration: Call Duration (formatted) is ticked, and Call Duration, with its key call_duration, is marked 1]

   *Search for a field and tick it (1). The key under its label names its column.*

7. **Click Add table**

   Click **Add table** at the bottom of **Destination table**. Nimbata prepares the table in BigQuery and says "Table calls added. Add the Google BigQuery step to a workflow to send rows to it." If BigQuery refuses, the reason shows under the field it is about: see [Nimbata does not add the table](#nimbata-does-not-add-the-table).

### Change a table later

Once a table is added, its card shows where it sends: **Google Cloud project**, **Dataset**, **Table** and **Latest rows view**, with **Open in BigQuery** to open the table in the Google Cloud console. Only the card's name, its fields and its switch can change:

- To send other fields, tick or untick them and click **Save changes**. Nimbata adds a column for each new field. A field you remove stops being sent, and its column stays in the table.
- To send to another table, add a new card for it and choose it in your workflows.

## Test the integration

A test row is a real row in your table, built as a workflow builds one, with `test` in its `nimbata_trigger` column. The `_latest` view leaves test rows out.

1. **Click Send test row**

   Click **Send test row** under the table. The button shows once the table is added, and any change you have not saved is saved first. While the table's **Sending rows** switch is off, the button is disabled: switch the table on to send a test row.

2. **Send the row**

   A panel opens with a box for each field the table sends. Change any value, or keep them, and click **Send event**.

3. **Find the row in BigQuery**

   Nimbata says "Test row added to harborpine-analytics.nimbata.calls, with nimbata_trigger test. The calls_latest view leaves test rows out." Click **Open in BigQuery** on the card, and query the table itself, not its view:

   ```sql
   SELECT *
   FROM `harborpine-analytics.nimbata.calls`
   WHERE nimbata_trigger = 'test'
   ORDER BY nimbata_exported_at DESC
   LIMIT 10;
   ```

## Send rows with a workflow

Nothing is sent to BigQuery until a workflow sends it. Create a workflow on **Inbound Call** that fires when the **Call Ends**, add a **Google BigQuery** action and choose its table, then click **Enable** (1). You can also start one with **+ Create** in the panel at the top of the Google BigQuery page.

- The action offers the project's **Call** tables in a call workflow (**Inbound Call** or **Outbound Call**) and its **Form** tables in a **Form Submission** workflow. SMS workflows cannot send to BigQuery.
- Add filters before the action to send only some calls, such as calls over a minute long.
- Calls with the **Call Outcome** **Blocked** are not sent, unless they ended with the **Hangup Cause** **Invalid Key Entry**, and neither are calls that failed.

Detailed guide: [Create a workflow](https://help.nimbata.com/workflows/workflows#create-a-workflow).

[A workflow firing on Inbound Call, Call Ends, with a Google BigQuery action sending to the Calls table, and the Enable button marked 1]

*The workflow sends every inbound call to the Calls table when the call ends. Click Enable (1).*

### Send a call again when it changes

Each time a workflow's Google BigQuery action runs for a call, Nimbata sends the call's current values as a new row. To keep your table up to date when your team tags a call, sets its outcome or writes a note, add the same action to a workflow that fires when a user changes the call (**User Updates Property**). Form submissions work the same way. The table then holds one row per run, and its `_latest` view shows the newest row of each call.

## Check it worked

The Google BigQuery page now shows **Used in 1 workflow**, and the table's card lists the workflow that sends to it. Nimbata sends waiting rows to BigQuery every minute, so a row usually arrives a minute or two after its workflow runs. The card then shows **Last row sent** with the date and time, in the project's time zone.

[The Google BigQuery integration connected as sam\@harborpine.example and used in 1 workflow. The Calls table card lists the workflow BigQuery call rows and sends to harborpine-analytics.nimbata.calls, with Sending rows on and Last row sent 2026-10-14 09:42]

*The page shows Used in 1 workflow, the card lists its workflow, and Last row sent says when the last row went out.*

On plans with integration events, each row Nimbata delivers, or gives up on, is also listed under its call or form submission, with BigQuery's reason for a failure. See [Integration events](https://help.nimbata.com/workspace/integration-events).

## What your table looks like

Every table starts with Nimbata's columns:

| Column                 | Type      | Holds                                                                                                                                                                                                                                                                                              |
| ---------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `nimbata_event_id`     | STRING    | The call's or form submission's id, the same in every row of that call or form submission.                                                                                                                                                                                                         |
| `nimbata_project_id`   | STRING    | The Nimbata project's id.                                                                                                                                                                                                                                                                          |
| `nimbata_project_name` | STRING    | The Nimbata project's name.                                                                                                                                                                                                                                                                        |
| `nimbata_event_time`   | TIMESTAMP | When the call started or the form was submitted, in UTC.                                                                                                                                                                                                                                           |
| `nimbata_trigger`      | STRING    | What sent the row: `call_start`, `call_end` or `user_action` (a workflow that fires when the call starts, ends, or a user changes it), `transcription` (an action after a **Transcribe Call** step, once the transcript is ready), `form_submitted`, `form_user_action`, or `test` for a test row. |
| `nimbata_exported_at`  | TIMESTAMP | When Nimbata sent the row.                                                                                                                                                                                                                                                                         |

Then comes one `STRING` column for each field you chose. A list or an object is JSON text, a yes or no value is `true` or `false`, and an empty value is `NULL`. Columns are never removed or retyped, so a field you stop sending keeps its column, which stays empty from then on.

A table Nimbata creates is partitioned by day on `nimbata_event_time` and clustered by `nimbata_project_id` and `nimbata_event_id`, so a query that filters on them reads less of it.

### The latest rows view

The table is a log: a call gets a row each time a workflow sends it. Next to the table, Nimbata creates a view named after it with `_latest` at the end, such as `calls_latest`, which the card shows under **Latest rows view**. The view keeps the newest row of each call or form submission (the one with the latest `nimbata_exported_at`) and leaves test rows out. Query the view for each call's current values.

To find each call's newest row, the view compares every row of the table, so a query on the view may read the whole table, even when it filters on `nimbata_event_time`. For a very large table, query the table itself and filter on `nimbata_event_time` inside the query, as in the last example below: BigQuery then reads only the days you ask for, in a table Nimbata created.

## Example queries

Replace `harborpine-analytics.nimbata.calls` with your own project, dataset and table.

Calls per project in the last 30 days:

```sql
SELECT nimbata_project_name AS project, COUNT(*) AS calls
FROM `harborpine-analytics.nimbata.calls_latest`
WHERE nimbata_event_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)
GROUP BY project
ORDER BY calls DESC;
```

Calls per day and tracking source, with the **Tracking Source** field (`tracking_source`), which a new call table sends. `DATE` counts days in UTC unless you give it your time zone:

```sql
SELECT DATE(nimbata_event_time, 'America/Los_Angeles') AS day, tracking_source, COUNT(*) AS calls
FROM `harborpine-analytics.nimbata.calls_latest`
GROUP BY day, tracking_source
ORDER BY day, calls DESC;
```

Every row one call produced, to see how it changed (use the call's `nimbata_event_id`):

```sql
SELECT nimbata_trigger, nimbata_exported_at
FROM `harborpine-analytics.nimbata.calls`
WHERE nimbata_event_id = 'THE-CALL-ID'
ORDER BY nimbata_exported_at;
```

The newest row of each call of the last 7 days, read from the table itself so that BigQuery reads only those days:

```sql
SELECT * EXCEPT(nimbata_rn)
FROM (
  SELECT *, ROW_NUMBER() OVER (PARTITION BY nimbata_event_id ORDER BY nimbata_exported_at DESC) AS nimbata_rn
  FROM `harborpine-analytics.nimbata.calls`
  WHERE nimbata_trigger != 'test'
    AND nimbata_event_time >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
)
WHERE nimbata_rn = 1;
```

Field columns are text. Cast them when you need numbers, such as `SAFE_CAST(call_duration AS INT64)` for **Call Duration**.

## Send to one table from several projects

If several projects should send to the same table, set up one project and copy its table to the others.

1. **Click Copy to other projects**

   On an added table, click **Copy to other projects**. The button shows when you have more than one project.

2. **Choose the projects and copy**

   Choose the projects in **Select project(s)** (1) and click **Copy** (2). Each project gets a card for the same table, with the same fields. A project without its own Google BigQuery connection is connected with this project's Google account. Nimbata says "Copied the table settings to 1 project."

   [The Copy this table's settings to other projects window, with Harbor & Pine Drain Cleaning chosen, marked 1, the note about connections and test rows, and the Copy button, marked 2]

   *Choose the projects (1) and click Copy (2).*

3. **Send a test row from each project**

   Nothing is checked with Google when you copy. Open each project's Google BigQuery page and click **Send test row** to see that it can write to the table.

4. **Copy the workflow**

   Copy the workflow with the Google BigQuery action to the same projects, as in [Copy a workflow to another project](https://help.nimbata.com/workflows/workflows#copy-a-workflow-to-another-project). The copied action finds each project's own card by its table.

When a project already has a card for that table:

- If the card sends the same kind of events, the project keeps its card as it is.
- If the card sends the other kind (forms to a table you copy calls to, or the reverse), nothing is copied to that project, and the window lists it with "This project already sends forms or calls to one of these tables, so nothing was copied to it. Review its BigQuery tables." A table holds one kind of event, so review that project's tables.

A copy keeps its card's name, or gets `(Copy)` after it when the project already has a card of that name. All the projects then send rows to one table, and `nimbata_project_id` and `nimbata_project_name` tell them apart.

## Switch a table off

Every added table has a **Sending rows** switch, which saves as soon as you click it. While it is on, workflows with the Google BigQuery step send rows to the table. Switch it off to stop all sending to the table, including the rows already waiting:

- Rows already waiting are kept, however long the table stays off, and go out when you switch it on again.
- Calls and form submissions that happen while it is off are not sent to it, even after you switch it back on.
- The card shows **Off** next to its kind, and no error while it is off.
- **Send test row** is disabled until you switch the table on again.

## Troubleshooting

### Nimbata does not connect

- "Google BigQuery access wasn't granted, so tables can't be listed, created or written to.": click **Continue with Google** again and, on Google's consent screen, keep the box for Google BigQuery ticked.

### Your Google Cloud project is not in the list

- Click **Reload** next to the list, after a change in Google Cloud.
- Click **Not listed? Enter its ID** and type the project's ID.
- Check that the connected Google account has a BigQuery role in that project. Otherwise Nimbata says "Google refused the connected account access to this Google Cloud project, dataset or table. Give the account a BigQuery role there, or connect with another account."

### Nimbata does not add the table

The message shows under the field it is about:

- "This Google Cloud project has no billing, which BigQuery needs before it takes rows.": turn on billing for the project in the Google Cloud console, or choose another project.
- "Google refused the connected account access to this Google Cloud project, dataset or table.": give the Google account a BigQuery role there, such as **BigQuery Data Editor**, or connect with another account.
- "This table can't take Nimbata's rows." followed by the column at fault: the table you chose lacks one of Nimbata's columns, or has it with another type. Choose another table, or let Nimbata create a new one.
- "The dataset already has a table with this name.": choose that table in **Table**, or type another name.
- "This project already sends to this BigQuery table.": use the card that already sends to it, or choose another table.
- "Google Cloud has no such dataset in this project." or, when you create one, "This Google Cloud project already has a dataset with this name.": choose another dataset from the list, or create one with another name.

### The test row fails

- "BigQuery is still preparing this table or its new columns. Try again in a few minutes.": BigQuery takes a few minutes to accept rows in a new table, or in new columns after you add fields. Wait and send the test row again.
- "This Google Cloud project has no billing, which BigQuery needs before it takes rows.": turn on billing (see the warning at the top of this page).
- "BigQuery can't find this table. It may have been deleted or renamed in Google Cloud.": add a new table and choose it in your workflows, or create the table again with the same name.
- "BigQuery has no working Google sign-in to use.": click **Continue with Google**, or **Reconnect**, then try again.

### A table shows Needs attention

When BigQuery refuses a table, its card shows **Needs attention**, and inside it "BigQuery is refusing rows for this table since" a date and time, with what to do. Nimbata emails your organization about it once. The causes:

- **The Google account can no longer write to the table.** In Google Cloud, give it the **BigQuery Data Editor** role on the dataset, or reconnect with an account that has it.
- **BigQuery can't find the table or its dataset.** It may have been deleted or renamed in Google Cloud. Create it again with the same name, or add a new table here and choose it in your workflows.
- **The project has no billing.** Turn on billing for the project in the Google Cloud console.

Nimbata keeps the table's rows and tries again every hour for up to 72 hours, so a fix within that time loses none. The first row that gets through clears the message.

### BigQuery refuses every row

When BigQuery refuses every row sent to a table, usually after a column was removed, retyped or made required in Google Cloud, the card shows **Needs attention** and says that the table's columns no longer match the card's fields. Under it, the message names the column when BigQuery's refusal names one ("BigQuery refused every row over the column tracking_source"), and otherwise only says that the table and the card's fields no longer match. Nimbata emails your organization about it once.

Fix that column in Google Cloud, or add a new table here and choose it in your workflows. Rows BigQuery refuses as invalid are not kept, so fix it soon. The first row that gets through clears the message.

[The alert on a Google BigQuery table card: BigQuery is refusing rows for this table since 2026-10-14 09:42, what to do, and the message naming the column tracking_source]

*The alert says since when BigQuery refuses the rows, what to do and, when BigQuery names it, the column at fault.*

### The page says Disconnected

When Google stops accepting the connection (for example, someone removed Nimbata's access in their Google account), the project disconnects, the page shows **Disconnected.** and Nimbata emails your organization once. Click **Reconnect** and sign in again. Rows that were waiting go out once you reconnect, if they have waited less than 72 hours.

### The connection stops every few hours

Your Google Workspace may have a Google Cloud session control policy that makes people sign in again every few hours, which stops the connection each time. Ask your Workspace administrator to add Nimbata to your trusted apps (in the Admin console, **Security** > **Access and data control** > **API controls**), then, under **Security** > **Access and data control** > **Google Cloud session control**, to tick **Exempt Trusted apps**.

### Rows are not reaching BigQuery

- Check that the workflow is enabled, that its **Google BigQuery** action lists the table, and that the table's kind matches the workflow (a **Call** table in a call workflow).
- Check that the table's **Sending rows** switch is on.
- Check that the call was not **Blocked** and did not fail: such calls are not sent.
- Only calls and form submissions a workflow handles after you set it up are sent. Older ones are not.
- A row that cannot go out because of a passing problem (Google busy, a network fault) is tried again, waiting longer each time. Nimbata gives it up after its tenth try, or 72 hours after it was queued (or after its card was last changed, if that is later). On plans with integration events, a row given up shows there as failed, with the reason.

## Frequently asked questions

### Are calls from before I set up the table sent?

No. Only calls and form submissions that happen once the table is added and switched on, and that a workflow with the Google BigQuery action handles, are sent. There is no backfill.

### Does deleting a call in Nimbata remove its rows from BigQuery?

No. Rows are never removed from BigQuery. Removing a table's card in Nimbata does not delete the table either: Nimbata says the table stays in BigQuery.

### What does BigQuery receive for a call?

Nimbata's columns and the fields you chose, with the same values a webhook gets for those fields. If a table should not hold callers' numbers, leave **Caller ID** out of its fields.
