> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.
# Connect to BigQuery
Sigma supports secure connections to BigQuery.
This document explains how to connect your organization to a BigQuery warehouse.
For information about Sigma feature compatibility with BigQuery connections, see [Region, warehouse, and feature support](/docs/region-warehouse-and-feature-support).
## Requirements
* You must be assigned the Admin account type or an account type with the **Manage connections** feature permission enabled. See [Create and manage account types](/docs/account-type-and-license-overview).
* You must have permission to create a service account on your Google Cloud Project. See Create service accounts in the Google Cloud documentation.
You must also determine what permissions to grant to the service account that you plan to use to connect to BigQuery. Avoid granting excessive permissions. For example, the account does not require BigQuery Connection Admin-level access.
## Create a BigQuery service account
Before you connect to Sigma, you must visit the Google Cloud Platform (GCP) console to create a service account for your BigQuery organization and generate a JSON private key for the service account.
* For instructions on creating a service account, see Create service accounts in the Google Cloud IAM documentation.
* For instructions on creating a JSON private key for the service account, see Create and delete service account keys in the Google Cloud IAM documentation.
A GCP service account is a type of Google account that can securely communicate over Google APIs on your behalf. The service account performs operations on behalf of Sigma in your BigQuery organization.
### Account permissions and roles
When creating your service account, you must grant it specific access permissions called roles.
To run BigQuery with Sigma, grant your service account the following roles:
* BigQuery Data Viewer
* BigQuery Job User
* BigQuery Data Editor (Required if you plan to [enable write access](/docs/set-up-write-access) on your connection.)
For more details about roles in BigQuery, see IAM roles and permissions index in the Google Cloud documentation.
## Considerations when connecting Sigma to BigQuery
When you connect Sigma to BigQuery, choose the most relevant authentication method for your use case:
Authenticate using a service account JSON key. The connection uses a service account that queries BigQuery on behalf of all Sigma users.
Recommended when your users don't need individual BigQuery access controls applied in Sigma, or when you want a simpler setup.
Authenticate to BigQuery using OAuth with a configuration specific to this connection. Users authenticate individually to BigQuery through Google Cloud Workforce Identity Federation, regardless of how they sign in to Sigma.
Recommended when Sigma users have Google Cloud accounts and you want their BigQuery permissions to apply in Sigma. Required if you use multiple identity providers or want to connect to multiple data platforms using OAuth.
## Create a connection in Sigma
1. In Sigma, open **Administration** > **Connections**.
2. Click **Create Connection**.
3. In the **Connection details**, specify the following:
| | |
| -------- | ----------------------------------------------------------------------------------------- |
| **Name** | Enter a **Name** for the new connection. Sigma displays this name in the connection list. |
| **Type** | Select **BigQuery**. |
4. Under **Billing project ID**, enter your GCP `Project ID`. You can find the project ID in the 'Project Info' section on your GCP console dashboard. See View and update projects in the Google Cloud documentation.
Grant the service account the "BigQuery Data Viewer" role for the project's datasets. See Control access to resources with IAM: Grant access to a dataset in the BigQuery documentation.
5. Select your desired **Authentication** method for your BigQuery connection.
* If you want to use **Basic Auth**, continue to the next step.
* If you want to use **OAuth**, see [Connect to BigQuery with OAuth (Beta)](/docs/connect-to-bigquery-oauth).
6. Under **Service account**, paste the JSON key you created when setting up your service account. The key is located in the `.json` file that was downloaded to your computer when you created the service account.
7. \[Optional] Under **Additional project IDs**, you can add additional BigQuery project IDs to the same connection. Separate multiple IDs with a comma. For example, `project-id-001, project-id-002`
The service account must be granted the BigQuery Data Viewer role for each project's datasets. For more details, see Control access to resources with IAM: Grant access to a dataset in the Google Cloud documentation.
8. Under **Connection Features**, specify the following:
-
Connection timeout
-
The time before timeout (or cancellation), in seconds, that Sigma waits for the query to return results.
-
Default is 120, or 2 minutes.
-
Maximum is 600, or 10 minutes.
-
Use friendly names
-
This toggle makes column names from the data source more readable.
-
For example, a database column ORDER_NUMBER or OrderNumber appears as Order Number.
-
On by default.
9. (Optional) Enable [write access](/docs/set-up-write-access) for the connection. Write access is required to use input tables, upload CSV data, materialization, store usage data for Sigma Assistant, and more. If you enable write access, the service account must be granted the **BigQuery Data Editor** role.
When you designate a schema as the write access destination, Sigma reserves it for internal write-back objects and doesn’t expose it as a data source in the connection explorer (data catalog). To avoid restricting user access to analytical data, use a dedicated write-back database or schema that doesn’t store data used for analysis and reports.
BigQuery requires all data referenced in a query to be stored in the same location. For example, if you configure a write-back destination in a specific region (like **us-west2**), but your workbook queries a multi-region location (like **US**), the query will fail. Sigma recommends querying specific regions. As an alternative, you can choose to use BigQuery's Global Queries feature.
1. Turn on the **Enable write access** toggle.
2. For **Write project**, enter the name of the project where Sigma must store write-back data.
3. For **Write dataset**, enter the dataset where Sigma must store write-back data.
10. After completing the form, click **Create**.
## Confirm your connection
After you have created your connection, you can confirm that your data is accessible by visiting the **Connections** section in the left hand navigation panel of Sigma Home.
1. Go to Sigma Home.
2. From the left hand navigation panel, select the new warehouse connection.
3. Explore your connection’s datasets and tables, confirming the connection was successful. See [Review and manage your data catalog](/docs/manage-data-catalog).
## Related resources
* [Set up write access](/docs/set-up-write-access)
* [Data permissions](/docs/data-permissions)