For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sign inTry it free
DocsGuidesSDKsIntegrationsAPI docsTutorialsFlagship blog
DocsGuidesSDKsIntegrationsAPI docsTutorialsFlagship blog
  • Get started
    • Overview
    • Onboarding
    • Get started
    • Launch Insights
    • LaunchDarkly architecture
    • LaunchDarkly vocabulary
  • AgentControl
    • AgentControl
    • Manage AgentControl
  • Feature flags
    • Create flags
    • Target with flags
    • Flag templates
    • Manage flags
    • Code references
    • Contexts
    • Segments
  • Releases
    • Releasing features with LaunchDarkly
    • Release policies
    • Percentage rollouts
    • Progressive rollouts
    • Guarded rollouts
    • Feature monitoring
    • Release pipelines
    • Engineering insights
    • Release management tools
    • Applications and app versions
    • Change history
    • Restoring previous flag versions
  • Observability
    • Observability
    • Session replay
    • Error monitoring
    • Logs
    • Traces
    • Observability metrics
    • Product analytics events
    • LLM observability
    • Alerts
    • Dashboards
    • Service map
    • Vega for auto-remediation
    • Observability MCP server
    • Search specification
    • Observability settings
    • Observability integrations
  • Experimentation
    • Experimentation
    • Experiment metric types
    • Experiment configuration
    • Managing experiments
    • Analyzing experiments
    • Multi-armed bandits
    • Holdouts
  • Metrics and events
    • Metrics in LaunchDarkly
    • Creating metrics
    • Metric groups
    • Events
    • Autogenerated metrics
  • Warehouse native
    • Warehouse native metrics
    • Setting up external warehouses
      • BigQuery native Experimentation
      • Databricks native Experimentation
      • Redshift native Experimentation
      • Snowflake native Experimentation
      • Warehouse health checks
    • Creating experiments using warehouse native metrics
  • Infrastructure
    • Connect apps and services to LaunchDarkly
    • LaunchDarkly in China and Pakistan
    • LaunchDarkly in the European Union (EU)
    • LaunchDarkly in federal environments
    • Public IP list
  • Your account
    • Projects
    • Views
    • Environments
    • Tags
    • Teams
    • Members
    • Roles
    • Account security
    • Feature previews
    • Billing and usage
    • Changelog
Sign inTry it free
LogoLogo
On this page
  • Overview
  • Prerequisites
  • Step 1: Gather your BigQuery project information
  • Step 2: Configure the LaunchDarkly integration
  • Step 3: Set up Google Cloud resources
  • Option A: Run the setup script
  • Option B: Set up manually in the Google Cloud Console
  • Create the service account
  • Create the results dataset
  • Grant the BigQuery Job User role at the GCP project level
  • Grant dataset-level permissions
  • Grant read access for metrics
  • Create and download the JSON key
  • Step 4: Add your service account key
  • Step 5: Verify the connection
  • Next steps
Warehouse nativeSetting up external warehouses

BigQuery native Experimentation

Was this page helpful?
Previous

Databricks native Experimentation

Next
Built with
Contact us for help with configuring BigQuery native Experimentation

If you have both Data Export and Experimentation enabled for your LaunchDarkly account, you should have access to BigQuery native Experimentation. If you do not have access or need help getting started, contact your LaunchDarkly representative or start a Support ticket.

Overview

This topic explains how to set up the BigQuery native Experimentation integration. BigQuery native Experimentation enables you to run experiments in LaunchDarkly using data directly from your Google Cloud BigQuery data warehouse. This lets LaunchDarkly experiments read and analyze your metrics data stored in BigQuery, without requiring you to send event data through LaunchDarkly’s SDKs.

Prerequisites

Before setting up BigQuery native Experimentation, ensure that you have:

  • The BigQuery Data Export integration set up in LaunchDarkly for your selected project and environment.
  • A Google Cloud Platform (GCP) project with BigQuery enabled.
  • Permission to create service accounts, datasets, and IAM bindings in your GCP project.
  • Access to Google Cloud Shell, or the gcloud CLI and bq CLI installed locally.
  • A LaunchDarkly role of Owner or Admin, or a custom role that allows the following actions:
    • add and edit integrations
    • add destinations
    • add metric data sources
  • Metric event data in your BigQuery project that you want to use for Experimentation.

Step 1: Gather your BigQuery project information

To begin, collect the following information about your Google Cloud project:

  • GCP project ID: Available in the GCP Console, under the top project dropdown, labeled Project ID. This is the Google Cloud project that holds your BigQuery resources. Legacy domain-scoped project IDs are also supported.
  • Dataset location: Available in BigQuery under your dataset labeled Dataset info. This is the BigQuery region where your datasets are located, for example US, us-central1, or asia-south1. All datasets must be in the same location. You cannot change this after saving.
  • Results dataset ID: A name for the new dataset where LaunchDarkly will write computed experiment results. Use only letters, numbers, and underscores, for example ld_experimentation_results. The setup script will create this dataset for you.
  • Data Export dataset ID: Available in BigQuery under your Data Export destination dataset. This is the dataset where your BigQuery Data Export destination writes evaluation events. This is the same dataset you configured in Data Export, for example ld_data_export.
  • Metrics dataset ID (optional): Available in BigQuery under your metrics dataset. This is the dataset containing your metric events table. If you omit this, the Google Cloud service account will have the BigQuery Data Viewer IAM role on your GCP project, rather than only on the metrics dataset. You cannot change this after saving.

Step 2: Configure the LaunchDarkly integration

Now, you will configure the BigQuery native Experimentation integration in LaunchDarkly. This integration is a second LaunchDarkly integration that looks similar to the BigQuery Data Export integration, but requires a separate setup process.

To set up the integration:

  1. Navigate to the Integrations page.
  2. Search for and select BigQuery Native Experimentation.
  3. Click Add integration. The configuration panel appears.

The BigQuery native Experimentation configuration panel in LaunchDarkly.

The BigQuery native Experimentation configuration panel in LaunchDarkly.
  1. Enter an integration Name.
  2. Select the LaunchDarkly Project and environment for this integration. Only environments with a BigQuery Data Export destination are available.
  3. Enter your GCP project ID.
  4. Select your Dataset location.
  5. Enter your Results dataset ID.
  6. Enter your Data Export dataset ID. This is the same dataset you configured when setting up BigQuery Data Export.
  7. (Optional) Enter your Metrics dataset ID.
  8. Click Generate setup script. LaunchDarkly generates a Google Cloud setup script. Copy and save this script for use in the next step.

Keep the configuration screen open, as you will return to it in a later step.

Step 3: Set up Google Cloud resources

LaunchDarkly needs a GCP service account with permissions to take actions in your GCP project. You can either run the setup script you generated in the last section, or complete the steps manually in the Google Cloud Console.

Option A: Run the setup script

Run the script using one of the following methods:

  • Google Cloud Shell (no local install needed): Open the Cloud Shell editor terminal and paste the script from step 11 in the previous section.
  • Local terminal: If you have gcloud and bq installed locally, paste and run the script in your terminal.

After the script completes, run cat ld-experimentation-key.json to print the JSON key file contents, then copy them to use in Step 4.

Option B: Set up manually in the Google Cloud Console

If you prefer to use the Google Cloud Console UI instead of the script, expand the section below.

Expand Manual setup in the Google Cloud Console

Create the service account

  1. In the Google Cloud Console, navigate to IAM & Admin > Service Accounts.
  2. Click Create service account.

The "Create service account" option in BigQuery.

The "Create service account" option in BigQuery.
  1. Enter a name that meets GCP naming requirements. For example, launchdarkly-experimentation.
  2. Click Done. Do not grant any roles at this step.

Create the results dataset

  1. In the Google Cloud Console, navigate to BigQuery.
  2. Select your project and click Create dataset.

The "Create dataset" screen in BigQuery.

The "Create dataset" screen in BigQuery.
  1. Enter your results dataset ID.
  2. Select the same location as your other datasets.
  3. Click Create dataset.

Grant the BigQuery Job User role at the GCP project level

  1. Navigate to IAM & Admin > IAM.
  2. Click Grant Access.

The "Grant access" option in BigQuery.

The "Grant access" option in BigQuery.
  1. Enter the full service account email, for example YOUR_SA_NAME@YOUR_PROJECT_ID.iam.gserviceaccount.com.
  2. Select the role BigQuery Job User.

The "BigQuery Job User" role.

The "BigQuery Job User" role.
  1. Click Save.

Grant dataset-level permissions

Grant the service account BigQuery Data Editor on the results dataset:

  1. In BigQuery, select the results dataset.
  2. Click Share > Manage permissions > Add Principal.
  3. Enter the service account email, select BigQuery Data Editor, and click Save.

Grant the service account BigQuery Data Viewer on the export dataset:

  1. In BigQuery, select the export dataset.
  2. Click Share > Manage permissions > Add Principal.

The "Manage permissions" option in BigQuery.

The "Manage permissions" option in BigQuery.
  1. Enter the service account email, select BigQuery Data Viewer, and click Save.

The "BigQuery Data Viewer" role.

The "BigQuery Data Viewer" role.

Grant read access for metrics

If you specified a metrics dataset:

  1. In BigQuery, select the metrics dataset.
  2. Click Share > Manage permissions > Add Principal.
  3. Enter the service account email, select BigQuery Data Viewer, and click Save.

If you did not specify a metrics dataset:

  1. Navigate to IAM & Admin > IAM.
  2. Click Grant Access.
  3. Enter the service account email, select BigQuery Data Viewer at the GCP project level, and click Save.

Create and download the JSON key

  1. Navigate to IAM & Admin > Service Accounts.
  2. Select your service account.
  3. Click the Keys tab > Add Key > Create new key.

The "Add key" menu in BigQuery.

The "Add key" menu in BigQuery.
  1. Select JSON and click Create. The browser downloads a key file.

Step 4: Add your service account key

After completing the setup process:

  1. Return to the LaunchDarkly configuration screen.
  2. Paste the full contents of the JSON key file you downloaded from Google Cloud into the Service account key (JSON) field.
  3. After reading the Integration Terms and Conditions, check the I have read and agree to the Integration Terms and Conditions checkbox.
  4. Click Save configuration.

Step 5: Verify the connection

Finally, verify the connection. On the integration configuration page, check the “Connection status” indicator. A green Healthy status confirms LaunchDarkly can connect to your BigQuery project and has the correct permissions.

If the connection is not healthy, verify that:

  • You completed all setup steps without errors.
  • The dataset location you entered matches the region your datasets are actually in.
  • The Data Export destination and the BigQuery native Experimentation integration are configured for the same LaunchDarkly environment.

Next steps

After your integration is connected, complete the following steps to start running experiments:

  1. Create a metric data source: point LaunchDarkly at your metric events table so it can read conversion and numeric event data.
  2. Create metrics: define what you want to measure using your BigQuery data.
  3. Create an experiment: when setting up your experiment, select Warehouse native (BigQuery) as the data source.

To learn how to analyze your results, read Analyzing experiments.

The results page for a warehouse native experiment displays the date and time the results were last updated from BigQuery. The initial load of experiment results can take up to 60 minutes to appear, and further results updates appear within 15–30 minutes.