Connect your Google BigQuery datasets to AstroBee and automatically transform your data warehouse into a queryable business model. AstroBee will discover your tables, understand relationships, and build an ontology that lets you ask questions in plain English.

​
What you’ll need

Before connecting BigQuery, ensure you have: Google Cloud setup:
  • A Google Cloud Platform project with BigQuery access
  • BigQuery API enabled in your GCP project
  • Service account with BigQuery permissions
Service account permissions:
  • BigQuery Data Viewer - to read your data
  • BigQuery Data Editor - to create new entities and edit ontologies
  • BigQuery Metadata Viewer - to discover tables and schemas
  • BigQuery Job User - to run discovery queries
AstroBee needs read-only access to analyze your data structure and build your ontology. We recommend creating a dedicated service account with minimal required permissions.

​
Setting up your service account

1

Create a service account

In Google Cloud Console, go to IAM & Admin > Service Accounts and click “Create Service Account”
2

Grant BigQuery permissions

Add these roles to your service account:
  • BigQuery Data Viewer
  • BigQuery Data Editor
  • BigQuery Metadata Viewer
  • BigQuery Job User
3

Generate credentials

Create a JSON key for your service account and download it securely
4

Note your project ID

You’ll need your Google Cloud project ID for the connection

​
Connecting to BigQuery

1

Create new ontology

Click the dropdown in the top left corner and select ” Create Ontology”
2

Choose BigQuery source and enter connection details

In the modal that appears, go to the “Warehouse” tab and click “Connect” next to BigQuery.
Connect BigQuery Source
Then provide your connection details:
  • Project ID: Your Google Cloud project ID
  • Private key: From your service account JSON
  • Service account email: From your service account JSON
Click “Connect to BigQuery” to proceed
BigQuery Connection Form
Once connected, you’ll see a confirmation message and the option to select datasets.
BigQuery connected
3

Select datasets

Now you can select which datasets to include in your ontology. AstroBee will discover all accessible tables within the selected datasets.
BigQuery Dataset Selection
4

View ontology

After selecting datasets, AstroBee will start building your ontology. This may take a few seconds to minutes depending on your data size.
View ontology
Once complete, you’re all set to view your ontology
Security note: AstroBee encrypts and securely stores your credentials. Your service account key is never stored in plain text.

​
What happens next

Once connected, AstroBee automatically builds your ontology by scanning your BigQuery datasets and using AI to understand your data structure. This process:
  • Discovers your data - Catalogs all accessible tables, columns, data types, and schema information
  • Identifies relationships - Uses AI to detect primary keys, foreign key patterns, and table connections
  • Validates connections - Runs SQL queries to ensure discovered relationships work correctly
  • Creates business entities - Transforms technical tables into meaningful business concepts with natural language names
Your technical schema becomes a queryable business model where you can ask questions like “What’s our customer retention rate?” instead of writing complex SQL.
Processing time: The initial ontology building typically takes 5-15 minutes depending on your data warehouse size. AstroBee will notify you when it’s complete.

​
Supported BigQuery features

AstroBee works with standard BigQuery data types and structures: Data type support: AstroBee supports all standard BigQuery data types including numeric (INTEGER, FLOAT, NUMERIC), text (STRING, BOOLEAN), date/time (TIMESTAMP, DATETIME, DATE, TIME), and binary (BYTES) types. Advanced features:
  • Multiple datasets - AstroBee discovers all accessible datasets in your project
  • Complex queries - Supports JOINs, aggregations, and window functions
  • Large datasets - Uses streaming and pagination for performance
  • Time-based filtering - Automatically detects timestamp columns for efficient queries
Current limitations: AstroBee does not support REPEATED fields, RECORD (struct) types, or GEOGRAPHY and JSON data types.

​
Troubleshooting

​
Coming soon

We’re actively working on additional BigQuery management features:
  • Refresh tables: Update table schemas and refresh data for existing BigQuery connections to capture new columns or structural changes
  • Delete connections: Remove existing BigQuery connections from your workspace
  • Delete source data: Remove specific datasets or tables from your ontology while keeping the connection active

​
Next steps

Once your BigQuery connection is established and your ontology is built:

Explore your ontology

See how AstroBee understood your data relationships and business model

Ask your first question

Start querying your BigQuery data with natural language