Birdie + BigQuery Integration

Overview
Birdie can ingest structured datasets directly from BigQuery 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.

Birdie connects to BigQuery using a Google Cloud Service Account. 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

2. Go to IAM & Admin - Service Accounts

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.

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

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

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

Birdie works best when the source table is partitioned 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
2. Select your Dataset
3. Click “Create table”
4. Source: Empty table
5. Define the schema:
• Make sure the schema includes your partition column as DATE, TIMESTAMP, or DATETIME. 
6. Partition and cluster settings:
• Partition by field
• Select the partition column
• Recommended: enable “Require partition filter". This reduces cost and prevents accidental full table scans.
7. Create the table

Birdie authenticates using a JSON service account key.
Steps:

1. Go to IAM & Admin - Service Accounts

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

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

• Activate the service account using the JSON key

• Run a simple query

• Validate reading your table using a partition filter

If this works, Birdie can query your data successfully.

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 with the Birdie team

Birdie can ingest structured datasets 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.