BigQuery

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.

Create the Service Account used by Birdie

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.

---

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

---

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.

---

Prepare Your BigQuery Table

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:

   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. 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

---

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

---

Data Types Supported

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.