Skip to main content

​
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
  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
  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)

​
Service account key structure

The service_account_key must contain: 
{
  "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/..."
}