> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovable.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your app to BigQuery

> Connect Google BigQuery to your Lovable app using Workload Identity Federation. Run SQL, explore datasets and schemas, and build analytics features without storing long-lived GCP keys in your project.

export const connector_0 = "BigQuery"

[Google BigQuery](https://cloud.google.com/bigquery) is a serverless data warehouse for analytics at scale. The **BigQuery** app connector lets your Lovable app call the BigQuery API through Lovable’s secure gateway, using **Workload Identity Federation (WIF)** so you do not paste long-lived service account keys into Lovable.

With BigQuery connected, your app can:

* Query datasets and tables using **standard SQL**
* Explore **schema metadata** (projects, datasets, tables, columns)
* Run **parameterized queries** with cost guardrails in mind
* Read from **views** and **materialized views**

BigQuery fits when your data already lives in GCP, or when you want warehouse-scale analytics, reporting, and dashboards backed by SQL.

## Common use cases and example apps

| Example app                     | Example prompt                                                                                                       | Description                                                                                                                                                       |
| :------------------------------ | :------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Executive metrics dashboard** | *Build a dashboard that shows weekly revenue and signups from your BigQuery `marts` tables, with filters by region.* | **Turn warehouse tables into charts in your app.** <br />The app runs SQL against BigQuery and renders KPIs and trends for stakeholders.                          |
| **Internal reporting tool**     | *Build an internal app where your team can run approved SQL reports against dataset `analytics` and export CSV.*     | **Self-serve reporting on curated datasets.** <br />The app submits parameterized queries and returns result sets without giving users direct GCP console access. |
| **Dataset explorer**            | *Build a tool that lists datasets and tables I can access and shows column types and row counts.*                    | **Browse what’s in the warehouse.** <br />The app uses metadata APIs and lightweight queries to describe tables and schemas.                                      |
| **Customer health view**        | *Join your CRM export in BigQuery with product usage and show a health score per account.*                           | **Combine modeled data for operational workflows.** <br />The app queries pre-joined or curated tables your data team maintains in BigQuery.                      |
| **Scheduled insight page**      | *Build a page that shows yesterday’s funnel metrics from BigQuery materialized views.*                               | **Surface daily or hourly aggregates.** <br />The app reads from views or summary tables that your pipelines refresh on a schedule.                               |
| **Data validation UI**          | *Build a small app that runs row counts and null checks on key columns after your pipeline runs.*                    | **Lightweight quality checks on top of SQL.** <br />The app runs targeted queries to confirm expectations after loads complete.                                   |

Exact behavior depends on **your datasets**, **IAM permissions** on the service account, and **what you ask Lovable to build**.

## How BigQuery connections work

* **Authentication**: The connector uses **Workload Identity Federation** with Google’s security token service. Short-lived access tokens are obtained and refreshed through Lovable’s **connector gateway**—not long-lived JSON keys stored in your repo.
* **Gateway**: Requests to the BigQuery API are proxied through the gateway. See [Gateway-based connectors](/integrations/introduction#gateway-based-connectors) for token handling and **per-project request limits**.
* **Scopes**: The connection is created with BigQuery access scopes (including `https://www.googleapis.com/auth/bigquery` by default). What you can read or run still depends on **IAM and dataset permissions** on the **service account** you configure.
* **Workspace binding**: You configure Google Cloud to trust identity tokens for a **workspace-specific audience** (see below). Use the **Workload Identity Provider** resource string and **service account email** in Lovable when creating the connection.

<Note>
  BigQuery **query and storage costs** are billed by **Google Cloud** to your GCP billing account, based on bytes processed, slots, and related usage—not by Lovable.
</Note>

## How to connect BigQuery

Workspace **admins** and **owners** can create BigQuery connections.

When a connection is created, it can be **linked to projects** like other app connectors so deployed apps use it where allowed.

### Prerequisites

Before connecting in Lovable, make sure you have:

* A **Google Cloud project** with the **BigQuery API** enabled and the datasets you want to query
* Permission to configure **IAM** and **Workload Identity Federation** in that project (or a dedicated admin project for identity pools)
* A **Google Cloud service account** that has the BigQuery roles your use case needs (for example, running queries and reading tables in specific datasets)
* Your **Lovable workspace ID** (you will need it for the OIDC **audience** in Google Cloud)
* **Lovable workspace admin or owner** role

### Step 1: Configure Workload Identity Federation in Google Cloud

You need a **Workload Identity Pool** and an **OIDC provider** that trusts **Google-issued ID tokens** whose audience is Lovable’s connector gateway for **your workspace**.

1. In the [Google Cloud console](https://console.cloud.google.com/), open **IAM & Admin → Workload Identity Federation** and create a **Workload Identity Pool** (or use an existing one).
2. Add an **OIDC provider** to the pool with:
   * **Issuer URL**: `https://accounts.google.com`
   * **Allowed audiences**: `https://connector-gateway.lovable.dev/workspaces/<WORKSPACE_ID>` — replace `<WORKSPACE_ID>` with your **Lovable workspace ID** (the same value Lovable uses for your workspace in URLs and settings).
3. **Allow the pool to impersonate your BigQuery service account**: Grant `roles/iam.workloadIdentityUser` (or the appropriate role for your organization’s policy) so principals from this pool can impersonate the service account that will call BigQuery. Follow Google’s documentation for binding **workload identity pool principals** to a service account.
4. Copy the **Workload Identity Provider resource name**. It looks like:\
   `//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID`\
   This string is the **WIF audience** value Lovable expects.

For detailed steps and IAM conditions, see Google Cloud documentation on [Workload Identity Federation](https://cloud.google.com/iam/docs/workload-identity-federation) and configuring **OIDC** providers.

### Step 2: Connect BigQuery in Lovable

1. Open **Connectors** → **App connectors** and select **BigQuery**.
2. Click **Add connection**.
3. In **Display name**, enter a clear name (for example `BigQuery Production` or `Analytics read-only`).
4. In **WIF audience**, paste the **Workload Identity Provider** resource name from Google Cloud (the full `//iam.googleapis.com/projects/.../providers/...` string).
5. In **Service account email**, enter the service account to impersonate for BigQuery access (for example `bq-reader@your-project.iam.gserviceaccount.com`).
6. Complete the flow to **create** or **verify** the connection. Lovable validates the federation setup through the gateway.

When connected, projects that are allowed to use this connection can run BigQuery operations through the connector while you build and after you publish.

### Cost and safety practices

BigQuery charges for **data scanned** by queries (and other usage). When implementing features in chat, prefer patterns that:

* Use **`maximumBytesBilled`** (or equivalent) on query jobs so large scans fail **before** running when they would exceed your limit.
* Filter **partitioned** tables on the partition column, avoid `SELECT *` during exploration, and use **`LIMIT`** while iterating.
* Use **INFORMATION\_SCHEMA** and metadata APIs to discover schemas and partitions before heavy scans.

See [BigQuery pricing](https://cloud.google.com/bigquery/pricing) and [best practices for controlling costs](https://cloud.google.com/bigquery/docs/best-practices-costs) in Google’s documentation.

## Limitations

* **Per-user Google login** is not what this connector provides: you configure **one** federated identity and service account per connection for the workspace (not each end user’s Google account).
* **Gateway limits** apply as described in [Gateway-based connectors](/integrations/introduction#gateway-based-connectors).
* **IAM and dataset access** are entirely under your control in GCP; Lovable cannot grant access to tables your service account is not permitted to read.

## How to unlink projects from a {connector_0} connection

Editors and above can remove specific projects from a connection without deleting the connection entirely. The connection will remain available for other projects.

To unlink projects:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to manage.
  </Step>

  <Step title="Select projects">
    Under **Linked projects**, check the projects you want to unlink.
  </Step>

  <Step title="Confirm">
    Click **Unlink projects** and confirm.
  </Step>
</Steps>

When unlinked, those projects will no longer have access to {connector_0} through this connection. If a project needs {connector_0} again, you can link it to any available connection.

## How to delete a {connector_0} connection

Workspace admins and owners can delete {connector_0} connections.

<Warning>
  Deleting a connection is permanent and cannot be undone. It will remove the credentials from all linked projects, and any apps using this connection will stop working until a new connection is added.
</Warning>

Before deleting, review the **Linked projects** section to see which projects are currently using the connection.

To delete a connection:

<Steps>
  <Step title="Open Connectors">
    Open **Connectors**, then go to **App connectors**, and select **{connector_0}**.
  </Step>

  <Step title="Open the connection">
    Open the connection you want to remove.
  </Step>

  <Step title="Review linked projects">
    Review the **Linked projects** section.
  </Step>

  <Step title="Delete">
    Under **Delete this connection**, click **Delete** and confirm.
  </Step>
</Steps>