BigQuery Connector

​

Overview

To connect TextQL with Google BigQuery, you will need to set up a service account with appropriate permissions. The service account requires the following roles:

• BigQuery Data Viewer: For accessing and reading data
• BigQuery Job User: For executing queries

​

Creating a Service Account

1. Navigate to the Google Cloud Console to create a service account.
2. Grant the required roles (BigQuery Data Viewer and BigQuery Job User).
3. Create and download the service account key file (JSON format).

​

Creating the Connector in TextQL

Navigate to the TextQL Connectors Page and click Create New Connector. Select BigQuery from the available connectors to open the configuration form. The form requires the following information:

• Connector Name: A descriptive name to identify this specific BigQuery connection in TextQL.
• Project ID: Your Google Cloud project identifier.
• Dataset ID: The specific BigQuery dataset to connect to (optional). When provided, TextQL scopes all schema introspection and connection tests to that dataset only.
• Credentials: The JSON contents of a service account key, or a Workload Identity Federation credential configuration (see below).
• Region Qualifier: The geographic location of your BigQuery resources.

​

Authenticating with Workload Identity Federation

If your organization disables service account key creation (the iam.disableServiceAccountKeyCreation org policy), the connector also accepts a Workload Identity Federation credential configuration ("type": "external_account") in the same Credentials field. No long-lived secret is stored; the TextQL deployment exchanges its own workload identity for short-lived Google Cloud tokens at query time.

1. Ask your TextQL contact for the identity your deployment presents (for dedicated deployments, typically the cluster’s OIDC issuer URL and the token audience).
2. In your Google Cloud project, create a workload identity pool and provider that trusts that issuer.
3. Create a service account with the BigQuery Data Viewer and BigQuery Job User roles, and grant the pool identity roles/iam.workloadIdentityUser on it.
4. Generate the credential configuration with gcloud iam workload-identity-pools create-cred-config, and paste the resulting JSON into the Credentials field.

For security, TextQL validates the configuration before use: token_url must be https://sts.googleapis.com/v1/token, service account impersonation must go through iamcredentials.googleapis.com, and executable credential sources are rejected. File-sourced subject tokens must live under /var/run/secrets/ in the deployment, which requires the token volume to be enabled for your deployment.

​

Google Sign-In (Per-Member OAuth)

Instead of a shared service account, each TextQL member can sign in with their own Google account. Every query then runs as that member against BigQuery, so their own IAM grants, row/column-level policies, and BigQuery audit logs apply — TextQL never holds a credential that can read more than the person asking.

​

Prerequisites

• An OAuth 2.0 client in your Google Cloud project — in APIs & Services → Credentials, create an OAuth client ID of type Web application, and note the Client ID and Client secret.
• Authorized redirect URI — add https://<your-textql-host>/auth/bigquery/callback to the client’s Authorized redirect URIs. The connector form shows the exact URI for your deployment with a copy button.
• Consent screen scopes — the client requests https://www.googleapis.com/auth/bigquery (Google’s read-and-manage BigQuery scope, required to run query jobs — what a member can actually reach is still bounded by their IAM), https://www.googleapis.com/auth/drive.readonly (for Drive-federated external tables), and openid/email/profile. Internal-audience apps need no verification; external-audience apps must have these scopes approved.
• Per-member IAM — each member needs BigQuery Job User on the project and read access to the dataset. Members without those grants get a permission error from BigQuery rather than seeing another member’s data.

​

Connector Fields

Select Google Sign-In under Authentication Method and fill in: Project ID, Dataset ID, and Region Qualifier work exactly as with service account auth. No Credentials JSON is stored.

​

Member Sign-In

Once the connector is saved, each member clicks Connect on the connector (or is prompted the first time they run a query) and signs in with Google. Tokens are encrypted at rest and refreshed automatically; members can re-authenticate at any time from the Connectors page.

​

Testing the Connection

After entering your credentials, click Create to establish the connection. TextQL will validate your service account permissions and create the connector.

• If a Dataset ID is provided, the connection test verifies access to that specific dataset.
• If no Dataset ID is provided, TextQL checks that the service account can list datasets in the project.

If the connection fails, verify your service account key and ensure all required permissions are granted.

​

Next Steps

Once connected, you can use TextQL to query your BigQuery datasets. For optimal performance and security:

• Use a dedicated service account for TextQL connections
• Apply principle of least privilege when assigning roles
• Consider setting up dataset-level access controls
• Monitor query costs through BigQuery’s pricing calculator