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

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/connect-data/setup/bigquery",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Connecting Google BigQuery to Omni

> Learn how to create a service account, generate a private key, and connect your Google BigQuery project to Omni.

export const BaseAccess = () => {
  return <span>
      <ParamField path="Base Access" required>
        Select the <a href="/administration/users/permissions">minimum level of access</a> users should have to models in the connection.
      </ParamField>
    </span>;
};

export const AlwaysScopeViewNames = () => {
  return <span>
      <ParamField path="Always Scope View Names" default="enabled">
        When enabled, Omni will prefix generated view names with schema and catalog, e.g. <code>my_catalog_public__orders</code> instead of <code>orders</code>. Defaults to enabled. See <a href="/connect-data/view-name-generation">View name generation</a> for more information.
      </ParamField>
    </span>;
};

export const AllowUserSpecificTimezones = () => {
  return <span>
      <ParamField path="Allow User-Specific Timezones">
        When enabled, users can override the connection timezone with their own when querying.
      </ParamField>
    </span>;
};

export const QueryTimezone = () => {
  return <span>
      <ParamField path="Query Timezone" required>
        The timezone to use for Omni queries. If a timezone is specified, data will be converted from the <strong>Database Timezone</strong> to the selected timezone.
      </ParamField>
    </span>;
};

export const DatabaseTimezone = () => {
  return <span>
      <ParamField path="Database Timezone" required>
        The timezone used by the database.
      </ParamField>
    </span>;
};

export const TableUploads = ({label = "Schema for Table Uploads", term = "schema"}) => {
  return <span>
      <ParamField path={label}>
        The name of the {term} to use for table (CSV) uploads. If left blank, you can upload tables but they won't be pushed to the database or be available for use in joins.
      </ParamField>
    </span>;
};

export const Offloaded = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Offloaded ${term}`}>
        A comma-separated list of {lower} to include in the connection, which will only load on demand. This setting is good for large {lower} or dbt dev {lower}.
      </ParamField>
    </span>;
};

export const IncludeOther = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Include Other ${term}`}>
        A comma-separated list of other {lower} to include in the connection.
      </ParamField>
    </span>;
};

export const Include = ({term = "Schemas"}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Include ${term}`}>
        A comma-separated list of {lower} to include in the connection.
      </ParamField>
    </span>;
};

export const Default = ({term = "Schema", required = true, defaultValue}) => {
  const lower = term.toLowerCase();
  return <span>
      <ParamField path={`Default ${term}`} required={required} default={defaultValue}>
        The default {lower} for the connection.
      </ParamField>
    </span>;
};

export const DisplayName = () => {
  return <span>
      <ParamField path="Display Name" required>
        A user-friendly name for the connection, which will be used throughout Omni.
      </ParamField>
    </span>;
};

## Requirements

To follow the steps in this guide, you'll need:

* **Organization Admin permissions in Omni**
* **Google Cloud admin permissions**, which are required to create a [service account](https://cloud.google.com/iam/docs/service-accounts) and [private key](https://cloud.google.com/storage/docs/authentication#generating-a-private-key).
* **The following details about the default dataset in your BigQuery project:**

  * The **name** of the default dataset
  * Its **data location**
  * Its **timezone** <br /><br />

  <Accordion title="Need help locating the dataset?">
    1. Navigate to your BigQuery console.
    2. Select the project your dataset resides in. Use the top middle drop-down menu to toggle between projects.
    3. Select a dataset and the info will appear in the **Dataset info** menu. In this example:

       * The dataset **name** is `products`
       * The **Data location** is `US`
       * The **timezone** is `UTC-7`, as indicated in the **Last modified** field

    <img src="https://mintcdn.com/omni-e7402367/XZwrvFN-b2pRXANo/connect-data/images/bigquery-dataset-details.png?fit=max&auto=format&n=XZwrvFN-b2pRXANo&q=85&s=5afe02cb135e73538b14ed856087a619" alt="BigQuery dataset info" width="1004" height="832" data-path="connect-data/images/bigquery-dataset-details.png" />
  </Accordion>

## Setup

<Steps>
  <Step title="Create a BigQuery service account & grant project access" titleSize="h3">
    1. Open the credentials page in the [Google Cloud Platform API Manager](https://console.cloud.google.com/apis/credentials) and, if necessary, select your project.
    2. Click **Create credentials**, located near the top center of the page, then **Service account**.
    3. In the **Service account details** section:
       1. Enter a name and description for the new service account, such as `Omni BigQuery`.
       2. Click **Create and continue**.
    4. In the **Grant this service account access to project** section, grant the service account access to the following [BigQuery roles](https://cloud.google.com/bigquery/access-control#curated_roles_comparison_matrix):

       * BigQuery Job User
       * BigQuery Data Viewer

           <img src="https://mintcdn.com/omni-e7402367/XZwrvFN-b2pRXANo/connect-data/images/bigquery-service-roles.png?fit=max&auto=format&n=XZwrvFN-b2pRXANo&q=85&s=2d6236ada1e4ca4499d41efde2b0b03c" alt="Service account roles" width="796" height="662" data-path="connect-data/images/bigquery-service-roles.png" />
    5. After adding both roles, click **Done**. You'll be redirected to the **Credentials** page.
  </Step>

  <Step title="Create a service account private key" titleSize="h3">
    1. In the **Service Accounts** section, click the service account you just created in step 1.
    2. On the service account details page, click the **Keys** tab near the top of the page.
    3. Click **Add Key > Create new key**.
    4. When prompted, select **JSON** as the key type and then click **Create**:
           <img src="https://mintcdn.com/omni-e7402367/XZwrvFN-b2pRXANo/connect-data/images/bigquery-key-type.png?fit=max&auto=format&n=XZwrvFN-b2pRXANo&q=85&s=2879f81c1a0d100e0bc1370bcb5607b5" alt="Key type prompt" width="504" height="347" data-path="connect-data/images/bigquery-key-type.png" />
    5. The JSON key will be saved to your computer. **After noting where the key was downloaded**, click **Close**.
           <img src="https://mintcdn.com/omni-e7402367/XZwrvFN-b2pRXANo/connect-data/images/bigquery-key-confirmation.png?fit=max&auto=format&n=XZwrvFN-b2pRXANo&q=85&s=05a5bf53f4b3fc83c79420dea7150077" alt="Key confirmation" width="504" height="160" data-path="connect-data/images/bigquery-key-confirmation.png" />
  </Step>

  <Step title="Set up a table upload dataset" titleSize="h3">
    <Callout icon="hand-point-up" color="#ff4179">
      **This step is optional.** However, we recommend completing it as part of the initial set up or you won't be able to use uploaded files like CSVs in joins.
    </Callout>

    In this step, you'll create a dedicated dataset to use for [table uploads](/analyze-explore/data-input-csvs). Before you create the dataset, note that:

    * This dataset can't be used for other modeled tables
    * This dataset must be in the same region as other projects and schemas in the connection, or you may encounter cross-region errors

    To create a dataset for table uploads:

    1. Navigate to your BigQuery project.

    2. Create the dataset.

    3. After the dataset is created, open it so that its details display.

    4. Click **Sharing > Permissions**, located next to the **Copy** option near the top right corner of the page.

    5. In the dialog that displays, click **Add principal**.

    6. Fill in the fields as follows:

       * **New principals** - Add the service account you created in step 1
       * **Role** - Add the **BigQuery Data Editor** role

           <img src="https://mintcdn.com/omni-e7402367/XZwrvFN-b2pRXANo/connect-data/images/bigquery-dataset-sharing.png?fit=max&auto=format&n=XZwrvFN-b2pRXANo&q=85&s=8b8a5ce0929a7a904db440cec038b260" alt="BigQuery dataset sharing" width="502" height="441" data-path="connect-data/images/bigquery-dataset-sharing.png" />

    7. Click **Save**.
  </Step>

  <Step title="Create the connection in Omni" titleSize="h3">
    1. In Omni, click **Settings > Connections**.

    2. Click the **BigQuery** option.

    3. On the connection setup page, fill in the connection details:

           <DisplayName />

           <Default term="Dataset" />

           <IncludeOther term="Projects" />

           <Include term="Datasets" />

           <Offloaded term="Datasets" />

           <TableUploads label="Dataset for CSV Upload" term="dataset" />

           <ParamField path="Service Account JSON" required>
             The JSON private key you created in step 2.
           </ParamField>

           <ParamField path="Region" required>
             The region the dataset resides in. Refer to the [Requirements](#requirements) section if you need help finding this information.
           </ParamField>

           <DatabaseTimezone />

           <QueryTimezone />

           <AllowUserSpecificTimezones />

           <ParamField path="Max Billing Bytes" default="1TB">
             The maximum bytes billed for queries run on this connection.
           </ParamField>

           <BaseAccess />

    4. When finished, click **Create connection**.
  </Step>
</Steps>

## What's next?

Now that your database is set up, you can:

* Use the Omni Agent's [quickstart skill](/modeling/topics/quickstart) to create your first topic from business questions
* Configure user permissions, [schema refreshes](/modeling/develop/schema-refreshes), [environments](/connect-data/dynamic-environments) and [timezone settings](/connect-data/timezones)
* Learn how Omni [generates the model](/modeling/develop/model-generation) associated with the connection