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

# BigQuery

> Connect Google BigQuery to ClarityQ

## Setup

### Connection Options

ClarityQ offers two ways to connect to BigQuery:

1. **Using ClarityQ service account**
2. **Using your own service account**

***

### Option 1: Using ClarityQ Service Account

For quick setup and testing, you can grant access to ClarityQ's managed service account instead of creating your own.

#### Step 1: Grant access to ClarityQ service account

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Navigate to **IAM & Admin** → **IAM**
3. Click **Grant Access**
4. Add the ClarityQ service account email (this will be displayed in the ClarityQ UI):
   ```
   clarityq-[unique-id]@clarityq-platform.iam.gserviceaccount.com
   ```
   **Note**: The exact email address will be shown in the ClarityQ connection interface.
5. Assign the appropriate BigQuery roles:
   * **BigQuery Job User**
   * **BigQuery Data Viewer**
   * **BigQuery Metadata Viewer**
   * **BigQuery Resource Viewer**
   * **Service Usage Consumer**

#### Step 2: Configure connection in ClarityQ

In the ClarityQ interface, fill out the connection form:

**Basic Fields:**

* **Connection Name**: Choose a name for this connection (e.g., "BigQuery via ClarityQ SA")
* **Project ID**: Your Google Cloud project ID

**Service Account Configuration:**
Leave "Use Own Service Account" toggle disabled (default). You'll see a message like:

> To connect Google BigQuery, please grant access to ClarityQ service account:

Click "Generate ClarityQ Service Account" to get the email address, then copy the exact service account email shown (each connection has a unique identifier).

***

### Option 2: Using Your Own Service Account

#### Step 1: Create a service account

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Navigate to **IAM & Admin** → **Service Accounts**
3. Click **Create Service Account**
4. Enter a descriptive name (e.g., `clarityq-service-account`)
5. Add a description for future reference
6. Click **Create and Continue**

#### Step 2: Assign permissions

Assign the appropriate BigQuery roles to your service account:

1. In the role assignment step, assign these roles:
   * **BigQuery Job User**
   * **BigQuery Data Viewer**
   * **BigQuery Metadata Viewer**
   * **BigQuery Resource Viewer**
   * **Service Usage Consumer**
2. Click **Continue** then **Done**

#### Step 3: Generate service account key

1. Select your service account from the list
2. Go to the **Keys** tab
3. Click **Add Key** → **Create New Key**
4. Choose **JSON** format
5. Click **Create**
6. Save the downloaded JSON file securely

#### Step 4: Configure connection in ClarityQ

In the ClarityQ interface, fill out the connection form:

**Basic Fields:**

* **Connection Name**: Choose a name for this connection (e.g., "Production BigQuery")
* **Project ID**: Your Google Cloud project ID

**Service Account Configuration:**
Toggle "Use Own Service Account" to choose your authentication method:

**Own Service Account (toggle enabled):**

* **Service Account Key**: Upload your JSON service account key file (drag & drop or browse)

**Optional: Quota Project Configuration**
Toggle "Use Quota Project" if you want to specify a different project for billing:

* **Quota Project ID**: Project ID to use for billing (if different from main project)

***

## Troubleshooting

### Common connection issues

**BigQuery API not enabled**

* Error: `BigQuery API has not been used in project ... before or it is disabled`
* The BigQuery API must be enabled at the project level — this is separate from IAM permissions
* Go to [Google Cloud Console > APIs & Services](https://console.cloud.google.com/apis/library/bigquery.googleapis.com) and click **Enable** for your project
* Wait a few minutes after enabling, then retry the connection

***

### Service account key structure

The `service_account_key` must contain:

```json theme={null}
{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "key-id",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "service-account@project.iam.gserviceaccount.com",
  "client_id": "123456789",
  "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/..."
}
```