Skip to main content
The BigQuery integration ingests billable events for usage metering directly from a table in your Google Cloud project: Alguna exports the table on a schedule, stages it in a Cloud Storage bucket you own, and turns each row into a usage event with the same shape as one sent to POST /events. Use it when usage already lands in your warehouse and you would rather not build an event pipeline. Access is granted through service-account impersonation, so no credentials are shared. Usage sources are described together in How Alguna works; the sibling connector is ClickHouse.

​
Pre-requisites

This guide assumes that you have an existing dataset and table in your Google Cloud project, and the relevant permissions to create a service account in your Google Cloud project.

​
Overview

​
Permissions

Alguna leverages Service Account Impersonation as a means to allow you to give access to resources in your Google Cloud project without sharing your own credentials. This is done as follows:
  1. Create a service account in your Google Cloud project with the necessary permissions.
  2. Give Alguna’s service account the necessary permissions to impersonate the service account in your project.

​
Process

Data is retrieved from your BigQuery dataset in a two stage process:
  1. Alguna starts a BigQuery EXPORT DATA job to export and compress data to a Google Cloud Storage bucket for temporary staging.
  2. Alguna fetches the data from the Google Cloud Storage bucket and ingests it as events.

​
Setup Resources

This guide shows the setup steps in the GCP console, but you can also do this via IaC.

​
Create a Service Account

  1. In the Google Cloud Console for your project, navigate to IAM & Admin > Service Accounts.
  2. Click on the Create Service Account button.
  3. Give your service account a name, ID and description. Google Cloud Create service account form with the service account name, ID and description filled in
  4. Grant the service account the Role BigQuery Job User. Google Cloud service account access step with the BigQuery Job User role selected
  5. Make a note of the email address of the service account, as you will need this later. It will be in the format:

​
Create a Cloud Storage bucket

Fetching data from BigQuery requires a Google Cloud Storage bucket to temporarily compress and store the data before it is ingested into Alguna.
  1. In the Google Cloud Console for your project, navigate to Cloud Storage > Buckets.
  2. Click on the Create button.
  3. Give your bucket a name, and select a single region for the bucket. This must be the same region as your BigQuery dataset.
  4. Set the Storage class to Standard.
  5. Check Enforce public access prevention on this bucket and set the Access control to Uniform.
  6. Keep the default settings for Data Protection and click Create. Google Cloud Storage Create a bucket summary: single region, Standard storage class, public access prevention on, uniform access control

​
Setup Permissions

Using the email address of the service account you created earlier, grant the following permissions:

​
Project

Grant the service account the BigQuery Job User role on the project, if you didn’t already do this when creating the service account. This allows the user to submit the EXPORT DATA job to BigQuery.

​
Cloud Storage

  1. On the bucket you created earlier, navigate to the Permissions tab and click Grant Access.
  2. Enter the principal email address of the service account you created earlier.
  3. Select the role Storage Object Admin.
  4. Click Save. Google Cloud Storage bucket Permissions tab with the Grant Access action

​
BigQuery

  1. In the Google Cloud Console for your project, navigate to BigQuery.
  2. Click on the menu next to the table you want to export and select Share > Manage Permissions.
  3. Click Add Principal.
  4. Enter the principal email address of the service account you created earlier.
  5. Select the role BigQuery Data Viewer.
  6. Click Save. Google Cloud Grant access dialog for the events table with the service account as principal and the BigQuery Data Viewer role

​
Grant Alguna Access

  1. In the Google Cloud Console for your project, navigate to IAM & Admin > Service Accounts.
  2. Click on the email address of the service account you created earlier.
  3. Navigate to the Permissions tab.
  4. Select View By Principals > Grant Access.
  5. Enter the Alguna service account email address:
  6. Select the role Service Account Token Creator.
  7. Click Save. Google Cloud Grant access dialog for the service account granting Alguna's data-sync account the Service Account Token Creator role

​
Share Setup Information

Once that’s done, you can share the following information with Alguna:
  • The email address of the service account you created.
  • The name and region of the Google Cloud Storage bucket you created.
  • The id of the BigQuery dataset and table you want to export in the format <projectID>.<datasetID>.<tableID>.
  • Your table schema, including which columns hold the customer account (an Alguna ID or alias), the event name, the timestamp, and a unique event ID for deduplication — the same fields an event sent to the API carries.