> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/~/revisions/5vNgx1SBLaM9wSz456q7/integrations-and-data-ingestion/how-to-integrate-with/bigquery.md).

# BigQuery

### Overview

Birdie can ingest structured datasets directly from [BigQuery](https://cloud.google.com/bigquery/docs/introduction) using read-only SQL queries. Most customers run Birdie ingestion daily, using a partition column (DATE / TIMESTAMP / DATETIME) to import only new rows and avoid full table scans.

#### Create the Service Account used by Birdie

Birdie connects to BigQuery using a [Google Cloud Service Account](https://docs.cloud.google.com/iam/docs/service-account-overview). This service account is a technical identity used only for read-only access to your data.\
Steps in Google Cloud Console:

1. [Open Google Cloud Console](https://console.cloud.google.com/)
2. Go to IAM & Admin - [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
3. Click “Create service account”
4. Service account name (suggested): birdie
5. Description (optional)
6. Click “Create and continue” (roles will be added in the next section)
7. Finish creating the service account

Note: After creation, wait up to 1 minute before using the service account. IAM propagation can be slightly delayed.

***

#### Grant Read-Only BigQuery Permissions

**Permission to run query jobs (Project level)**\
Role: BigQuery Job User (roles/bigquery.jobUser)

This permission allows Birdie to execute SQL queries. It does NOT grant data access by itself.

How to grant:

* IAM & Admin - IAM
* Select your Project
* Add the service account
* Assign role: [BigQuery Job User](https://docs.cloud.google.com/bigquery/docs/access-control#bigquery.jobUser)

***

**Permission to read data (Dataset level – recommended)**\
Role: BigQuery Data Viewer (roles/bigquery.dataViewer)

This permission allows Birdie to read tables or views.

How to grant:

* Go to BigQuery
* Select the Dataset that Birdie should ingest
* Click “Share dataset”
* Add the service account
* Assign role: [BigQuery Data Viewer](https://cloud.google.com/bigquery/docs/access-control#bigquery.dataViewer)

Note: Grant Data Viewer at the dataset (or table) level instead of the entire project.

***

#### Prepare Your BigQuery Table

Birdie works best when the source table is [partitioned](https://docs.cloud.google.com/bigquery/docs/creating-partitioned-tables) by a column used for incremental ingestion (for example: posted\_at).

Supported partition column types:

* DATE
* TIMESTAMP
* DATETIME

Steps in BigQuery Console:

1. Open [BigQuery](https://console.cloud.google.com/bigquery)
2. Select your Dataset
3. Click “Create table”
4. Source: Empty table
5. Define the schema:
   1. Make sure the schema includes your partition column as DATE, TIMESTAMP, or DATETIME. 
6. Partition and cluster settings:
   1. Partition by field
   2. Select the partition column
   3. Recommended: enable “Require partition filter". This reduces cost and prevents accidental full table scans.
7. Create the table

***

#### Create a Service Account Key (JSON)

Birdie authenticates using a JSON [service account key](https://cloud.google.com/iam/docs/keys-create-delete).\
Steps:

1. Go to IAM & Admin - [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts)
2. Click the service account (birdie)
3. Open the “Keys” tab
4. Click “Add key” - “Create new key”
5. Select JSON
6. Click “Create”\
   The JSON file will be downloaded automatically.

Important:

* This JSON file is what Birdie uses to authenticate

***

Validate Access

You can validate access using Cloud Shell or your local machine.

* Activate the service account using the JSON key

```
gcloud auth activate-service-account --key-file /path/to/birdie.json
```

* Run a simple query

```
bq query --use_legacy_sql=false "SELECT 1 AS ok"
```

* Validate reading your table using a partition filter

```
bq query --use_legacy_sql=false
```

```
"SELECT * FROM <PROJECT_ID>.<DATASET>.<TABLE>
WHERE <PARTITION_COLUMN> >= DATE_SUB(CURRENT_DATE(), INTERVAL 1 DAY) LIMIT 10"
```

If this works, Birdie can query your data successfully.

***

#### Share Connection Details with Birdie

To configure the integration, securely provide Birdie with:

* Project ID
* Dataset name
* Table name (or view name)
* Partition column used for incremental ingestion (DATE / TIMESTAMP / DATETIME)
* Kind of data:
  * Review
  * NPS
  * CSAT
  * Support Ticket
  * Social Media Post
  * Issue
  * Account
* Service account JSON key (credentials file)

[Share it securely](https://onetimesecret.com/en/) with the Birdie team

***

Data Types Supported

Birdie can ingest [structured datasets](https://ask.birdie.ai/article/how-to-integrate-birdie-s3gcs) exposed as BigQuery tables or views, including:

* Conversations and messages (Support Tickets, Issues, Social Media Posts)
* Feedback datasets (review, nps, csat)
* Operational or reference tables (accounts, users, metadata)

Expose one table or view per dataset type.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ask.birdie.ai/~/revisions/5vNgx1SBLaM9wSz456q7/integrations-and-data-ingestion/how-to-integrate-with/bigquery.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.