> ## 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 by signing in with Google (OAuth) or 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 + chat connector lets your Lovable app call the BigQuery API through Lovable’s secure gateway. You can connect by **signing in with your Google account** or with **Workload Identity Federation (WIF)**, so you never paste long-lived service account keys into Lovable.

BigQuery is available as an [app + chat connector](/integrations/app-connectors): one shared connection that works in the chat while you build and in your published apps.

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** of the connected identity, and **what you ask Lovable to build**.

## How BigQuery connections work

* **Authentication**: Connections authenticate in one of two ways. **Connect with Google** signs in with your Google account (OAuth). **Workload Identity Federation** exchanges identity tokens for short-lived service account credentials through Google’s security token service. In both modes, short-lived access tokens are obtained and refreshed through Lovable’s **connector gateway**, and no long-lived JSON keys are stored in your repo.
* **Gateway**: Requests to the BigQuery API are proxied through the gateway. See [Gateway-based connectors](/integrations/app-connectors#gateway-based-connectors) for token handling and **per-project request limits**.
* **Scopes**: Connections use the `https://www.googleapis.com/auth/bigquery` scope. What you can read or run still depends on **IAM and dataset permissions** in Google Cloud: your Google account’s permissions for Connect with Google, or the **service account’s** for Workload Identity Federation.
* **Identity**: With **Connect with Google**, the connection acts as the Google account that authorized it and runs queries in the Google Cloud project you configure. With **Workload Identity Federation**, you configure Google Cloud to trust identity tokens for a **workspace-specific audience** and Lovable impersonates the **service account** you specify.

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

## How to connect BigQuery

Who can create BigQuery connections depends on your plan and workspace settings. See [Who can create connections and clients](/integrations/admin-controls#who-can-create-connections-and-clients).

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

### Choose how to connect

* **Connect with Google** is the fastest way to connect. You sign in with your Google account and pick the Google Cloud project that runs and is billed for your queries. The connection is tied to that Google account, which makes it a good fit for individuals, prototypes, and teams that already work through personal Google accounts. The connection stops working if that account loses access (see [Limitations](#limitations)).
* **Workload Identity Federation** fits production and org-managed data access. The connection is not tied to any individual account: you grant access to a service account through your own Google Cloud IAM, access is auditable, and no long-lived keys are involved. The connection keeps working when people leave the team.

Follow the setup steps below based on how you want to connect BigQuery.

<Tabs>
  <Tab title="Connect with Google">
    Sign in with your Google account and run queries in a Google Cloud project you choose. No Workload Identity Federation setup is required.

    **Prerequisites**

    Before connecting BigQuery, make sure you have:

    * A **Google account** with access to the BigQuery datasets you want to query
    * The **BigQuery Job User** role (`roles/bigquery.jobUser`) on the Google Cloud project that will run your queries
    * Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](/integrations/admin-controls#who-can-create-connections-and-clients))

    **Connect BigQuery in Lovable**

    <Steps>
      <Step title="Open BigQuery in Connectors">
        Go to **Connectors** and select **BigQuery**.
      </Step>

      <Step title="Add a connection">
        Click **Add connection**.
      </Step>

      <Step title="Name the connection">
        In **Display name**, enter a clear name (for example `BigQuery Analytics`).
      </Step>

      <Step title="Choose Connect with Google">
        Under **Authentication**, select **Connect with Google**.
      </Step>

      <Step title="Enter the Google Cloud project ID">
        In **Google Cloud project ID**, enter the project that runs and is billed for your queries. The connected Google account needs the **BigQuery Job User** role on this project.

        The project that runs your queries can be different from the project that stores the data. To read data stored in another project, keep the project that runs your queries in this field and fully qualify table names in your queries, for example `data-project.dataset.table`.
      </Step>

      <Step title="Choose who can use this connection">
        Under **Who can use this connection**, decide who in your workspace can use the connection. You start as the only person with access:

        * **Only you** (default): leave the access list as is; only you can use the connection and its associated data.
        * **Invite specific people**: add workspace members by email; only you and the people you add can use the connection and its associated data.
        * **Invite entire workspace**: click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

        See [Who can use connections and clients](/integrations/admin-controls#who-can-use-connections-and-clients) for more information.
      </Step>

      <Step title="Connect and authorize">
        Click **Connect**. The Google sign-in window opens, so make sure your browser doesn’t block pop-ups. Sign in and approve the requested access.

        The flow requests one scope: **View and manage your data in Google BigQuery** (`https://www.googleapis.com/auth/bigquery`). The scope is an upper bound, not a grant. What the connection can actually do is decided by the IAM roles of the account you sign in with. Grant roles to match what you’re building:

        * **Read-only apps** (dashboards, reporting, data explorers): grant **BigQuery Data Viewer** on your datasets plus **BigQuery Job User** on the project. IAM blocks all writes, so the connection stays read-only even though the scope allows more.
        * **Read-write apps** (data entry, writebacks, table management): additionally grant **BigQuery Data Editor** on the datasets your app should change.

        Lovable requests this scope instead of Google’s read-only scope (`bigquery.readonly`) because the read-only scope doesn’t support the full BigQuery jobs API.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Workload Identity Federation">
    Grant access to a service account through your own Google Cloud IAM. The connection is not tied to any individual account and uses no long-lived keys. In the connection form, this option is labeled **Bring Your Own Key**.

    **Prerequisites**

    Before connecting BigQuery, 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, **BigQuery Data Viewer** plus **BigQuery Job User** for read-only apps, adding **BigQuery Data Editor** on datasets your app should change)
    * Your **Lovable workspace ID** (you will need it for the OIDC **audience** in Google Cloud)
    * Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](/integrations/admin-controls#who-can-create-connections-and-clients))

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

    <Steps>
      <Step title="Create a Workload Identity Pool">
        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).
      </Step>

      <Step title="Add an OIDC provider">
        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).
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>
    </Steps>

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

    <Steps>
      <Step title="Open BigQuery in Connectors">
        Go to **Connectors** and select **BigQuery**.
      </Step>

      <Step title="Add a connection">
        Click **Add connection**.
      </Step>

      <Step title="Name the connection">
        In **Display name**, enter a clear name (for example `BigQuery Production` or `Analytics reporting`).
      </Step>

      <Step title="Choose Bring Your Own Key">
        Under **Authentication**, select **Bring Your Own Key**. This is the Workload Identity Federation option.
      </Step>

      <Step title="Enter the WIF audience">
        In **WIF audience**, paste the **Workload Identity Provider** resource name from Google Cloud (the full `//iam.googleapis.com/projects/.../providers/...` string).
      </Step>

      <Step title="Enter the service account email">
        In **Service account email**, enter the service account to impersonate for BigQuery access (for example `bq-reader@your-project.iam.gserviceaccount.com`).
      </Step>

      <Step title="Choose who can use this connection">
        Under **Who can use this connection**, decide who in your workspace can use the connection. You start as the only person with access. Add specific workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

        See [Who can use connections and clients](/integrations/admin-controls#who-can-use-connections-and-clients) for more information.
      </Step>

      <Step title="Create the connection">
        Complete the flow to **create** or **verify** the connection. Lovable validates the federation setup through the gateway.
      </Step>
    </Steps>
  </Tab>
</Tabs>

When connected, anyone building in a project can ask Lovable in chat to link their project to BigQuery (based on configured connection-level access). Your Lovable apps can then run SQL queries against your datasets 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

* **One identity per connection**: end users of your app do not sign in with their own Google accounts. A **Connect with Google** connection acts as the single Google account that authorized it, and a **Workload Identity Federation** connection acts as the configured service account.
* **Connect with Google connections depend on that Google account**: if the account loses access to the project, or the authorization is revoked on the Google side (for example, from the account’s third-party access settings), the connection stops working until someone reconnects it in Lovable.
* **Gateway limits** apply as described in [Gateway-based connectors](/integrations/app-connectors#gateway-based-connectors).
* **IAM and dataset access** are entirely under your control in GCP; Lovable cannot grant access to tables the connected account or service account is not permitted to read.

## Manage your {connector_0} connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **{connector_0}**, then open the connection.

* **Unlink projects** to remove {connector_0} access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](/integrations/app-connectors#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use {connector_0} stop working until a new connection is added. See [Delete a connection](/integrations/app-connectors#delete-a-connection) for the steps and who can delete.