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

# Setup guide - Matillion Full SaaS Google BigQuery

export const PlatformGuideMetadata = ({deploymentType, cloudPlatform, warehouse}) => {
  const pill = label => <span style={{
    background: '#dcfce7',
    color: '#15803d',
    border: '1px solid #bbf7d0',
    borderRadius: '9999px',
    padding: '3px 12px',
    fontSize: '0.85rem',
    fontWeight: '500',
    whiteSpace: 'nowrap'
  }}>
      {label}
    </span>;
  const rows = [{
    label: 'Deployment type',
    value: deploymentType
  }, {
    label: 'Cloud platform',
    value: cloudPlatform
  }, {
    label: 'Cloud data warehouse',
    value: warehouse
  }];
  return <div data-search-exclude style={{
    background: 'var(--colors-background-light, #f9fafb)',
    border: '1px solid var(--colors-border-default, #e5e7eb)',
    borderRadius: '12px',
    padding: '20px 28px',
    marginBottom: '28px',
    boxShadow: '0 1px 4px rgba(0,0,0,0.10)'
  }}>
      <table style={{
    width: '100%',
    borderCollapse: 'collapse'
  }}>
        <tbody>
          {rows.map(({label, value}, i) => <tr key={i}>
              <td style={{
    fontWeight: '600',
    paddingRight: '32px',
    ...i < rows.length - 1 && ({
      paddingBottom: '14px'
    }),
    whiteSpace: 'nowrap',
    verticalAlign: 'middle',
    width: '180px'
  }}>{label}</td>
              <td style={{
    ...i < rows.length - 1 && ({
      paddingBottom: '14px'
    }),
    verticalAlign: 'middle'
  }}>{pill(value)}</td>
            </tr>)}
        </tbody>
      </table>
    </div>;
};

export const maia = "Maia";

This document describes the necessary steps to follow to set up your first working project in {maia} for the following configuration options:

<PlatformGuideMetadata deploymentType="Matillion Full SaaS" cloudPlatform="Provided by Matillion" warehouse="Google BigQuery" />

{maia} authenticates to Google BigQuery using a Google Cloud service account credential. Because Google BigQuery authentication differs from other warehouses, read [How Google BigQuery authentication differs from other warehouses](#how-google-bigquery-authentication-differs-from-other-warehouses). For Hybrid SaaS deployments, read the [Hybrid SaaS Google BigQuery setup guide](/docs/guides/hybrid-saas-bigquery).

***

## How Google BigQuery authentication differs from other warehouses

For most warehouses, authentication is configured directly on the environment itself. For example, Snowflake environments typically use username/password or key-pair authentication configured as part of the warehouse connection.

Google BigQuery doesn't follow this model. Instead, Google BigQuery uses Google Cloud credentials provided as JSON Google Cloud service account key files. The Google Cloud service account acts as a principal when accessing Google Cloud resources. For more information, read the following Google Cloud documentation:

* [Service accounts as principals](https://docs.cloud.google.com/iam/docs/service-account-overview#service-accounts-identities)
* [Service account credentials](https://docs.cloud.google.com/iam/docs/service-account-creds#key-types)
* [User-managed service account keys](https://docs.cloud.google.com/iam/docs/service-account-creds#user-managed-keys)

Because of this, Google BigQuery environments don't contain warehouse authentication settings directly. To fully configure a Google BigQuery environment, it must have access to a Google Cloud service account credential. For Full SaaS deployments, the credential is supplied as a configured cloud credential on the environment.

### Example Google Cloud service account key

The following is an example of a Google Cloud service account key structure:

```json theme={null}
{
  "type": "service_account",
  "project_id": "example-project",
  "private_key_id": "1234567890abcdef1234567890abcdef12345678",
  "private_key": "-----BEGIN PRIVATE KEY-----\nEXAMPLEKEY\n-----END PRIVATE KEY-----\n",
  "client_email": "matillion-sa@example-project.iam.gserviceaccount.com",
  "client_id": "123456789012345678901",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/matillion-sa%40example-project.iam.gserviceaccount.com"
}
```

***

## Prerequisites

### Google BigQuery requirements

* A [Google Cloud](https://cloud.google.com/) project with the following information:
  * Your [GCP project ID](https://cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects), found on the dashboard in the Google Cloud Console.
  * A Google BigQuery dataset for {maia} to read from and write to.
  * A [Google Cloud service account](https://cloud.google.com/iam/docs/service-account-overview) with an associated [Google Cloud service account key](https://cloud.google.com/iam/docs/service-account-creds#key-types) (JSON).
  * IAM roles assigned to the Google Cloud service account that grant the permissions described in [Permissions](#permissions).

### Connectivity requirements

* Access enabled for the IP addresses listed under the **Full SaaS** section of [Network access and IP Allowlist requirements](/docs/security/network-access-and-ip-allowlist-requirements/#full-saas).

***

## Permissions

The Google Cloud service account must have IAM roles or permissions sufficient for the operations {maia} performs against your data. Typical operations include:

* Create, update, and delete tables and views.
* Query tables and views.
* Retrieve metadata for datasets, tables, and views.
* List projects, datasets, tables, and views.
* Insert or load data into tables.
* Run Google BigQuery jobs.

### Recommended Google BigQuery roles

Depending on your use case, Google recommends assigning a combination of the following roles. At a minimum, grant either `roles/bigquery.jobUser` or `roles/bigquery.user`, as both include the `bigquery.jobs.create` permission required for the service account to interact with BigQuery. For {maia}-specific BigQuery IAM guidance, read [Google Cloud IAM permissions for runner deployment](/docs/guides/gcp-iam-permissions-for-runner#bigquery).

| Role                        | Purpose                                                                           |
| --------------------------- | --------------------------------------------------------------------------------- |
| `roles/bigquery.jobUser`    | Submit and run BigQuery jobs—must be project-level; can't be scoped to a dataset. |
| `roles/bigquery.user`       | Run BigQuery jobs, and query data.                                                |
| `roles/bigquery.dataEditor` | Read and write data—only required if the pipeline writes back to BigQuery.        |
| `roles/bigquery.dataViewer` | Read data from BigQuery datasets and tables.                                      |
| `roles/bigquery.admin`      | Full administrative access to Google BigQuery resources.                          |

<Note>Use the principle of least privilege wherever possible.</Note>

For the full list of Google BigQuery IAM roles and permissions, read [Access control](https://docs.cloud.google.com/bigquery/docs/access-control).

### Google Cloud Storage permissions

Many Google BigQuery workflows use Google Cloud Storage (GCS) as a staging location before loading data into Google BigQuery.

If your pipelines interact with GCS buckets, the Google Cloud service account also requires appropriate Storage IAM permissions. For more information, read [Basic roles](https://docs.cloud.google.com/storage/docs/access-control/iam-roles#basic-roles).

Commonly used roles include:

| Role                          | Purpose                        |
| ----------------------------- | ------------------------------ |
| `roles/storage.objectViewer`  | Read staged files.             |
| `roles/storage.objectCreator` | Upload staged files.           |
| `roles/storage.objectAdmin`   | Full access to bucket objects. |

For more information about IAM permissions, read [Google Cloud IAM permissions for runner deployment](/docs/guides/gcp-iam-permissions-for-runner#bigquery).

***

## Setup steps

1. Register for a [{maia} account](/docs/administration/registration).
2. [Create accounts](/docs/administration/manage-other-users) for users and admins who will be active in {maia}.
3. Create a [project](/docs/guides/bigquery-projects#add-a-new-project), making the following choices:
   * Select **{maia} managed**.
4. Create an [environment](/docs/guides/bigquery-environments), and configure a cloud credential using your Google Cloud service account key.
5. Select [BigQuery defaults](/docs/guides/bigquery-projects#select-bigquery-defaults-2) for your environment, such as the default GCP project and dataset.
6. Create a Git [branch](/docs/guides/branches) in which to begin pipeline work.
7. Create your first [pipeline](/docs/guides/pipelines).