How to create, ship, and measure feature flags with BigQuery data

Feature flags control who receives new behavior. BigQuery tells you what happened after they did.

Those jobs should remain separate. A browser, API, mobile app, or edge service needs fast deterministic evaluation with defined offline behavior. BigQuery is an analytical engine: it is ideal for joining exposure to product, revenue, reliability, and retention facts, but it should not receive a query for every customer request.

The resulting architecture has a feature flag control plane, local or nearby SDK evaluation, an exposure-event pipeline, and BigQuery models for outcomes. When a rollout is randomized and measured with a predeclared plan, the same path supports A/B testing.

Create a flag with an operating contract

Before adding targeting rules, record the flag's purpose, owner, type, environments, default value, intended end state, and removal date.

Release flags should normally be temporary. Operational flags need an emergency owner and conservative fallback. Entitlement flags may be long-lived and need tighter product governance. Experiment flags need stable randomization and exposure tracking.

GrowthBook's feature flag product supports typed flags, targeting, percentage rollouts, approvals, and experiments. The feature flag best-practices guide explains why naming, ownership, incremental rollout, and cleanup belong in the initial design.

Evaluate close to the application

SDKs should cache feature definitions and evaluate using context available at decision time. Test cold start, network loss, invalid definitions, stale data, and recovery. A fallback must be appropriate to the feature rather than one global “false” value.

GrowthBook's SDK documentation describes local evaluation across application environments. The vendor-neutral OpenFeature specification can reduce provider-specific application code through a common API and provider model.

Log an exposure that analysis can trust

An evaluation is not automatically an exposure. Log when the result can first change what the unit experiences. Control and treatment must use the same logical boundary.

Send these fields through the existing event pipeline:

{
  "event_name": "feature_exposure",
  "feature_key": "new-checkout",
  "experiment_id": "checkout-layout-v2",
  "variation_id": "treatment",
  "subject_id": "user_123",
  "exposed_at": "2026-09-09T18:42:11Z",
  "environment": "production",
  "definition_revision": "rev_47"
}

Use placeholders in documentation and avoid putting personal attributes in the event unless the analysis contract requires and permits them. Keep experiment assignment, exposure, and outcomes independently inspectable.

GrowthBook's tracking callback provides an application hook for recording experiment exposure. Preserve the exact randomization ID so BigQuery can join and aggregate outcomes at the same unit.

Choose an ingestion path and freshness target

Batch loads may be sufficient for next-day experiment review. Operational guardrails may need minute-level events. BigQuery's Storage Write API supports streaming ingestion, but teams still need idempotency, schema, retry, and late-data policies.

Do not promise “real time” based only on ingestion. Transformations, metric windows, and dashboard refreshes also affect freshness.

Scale flags with clear ownership

Establish lifecycle, rollout, and cleanup rules before feature flags spread across teams and services.

Read the Scaling Guide

Model canonical flag exposure in BigQuery

Keep the append-only raw event, then create a narrow view or incremental table with one valid first exposure per subject.

CREATE OR REPLACE VIEW `analytics.flag_exposures` AS
SELECT
  feature_key,
  experiment_id,
  variation_id,
  subject_id,
  exposed_at,
  environment,
  definition_revision
FROM `raw.feature_exposure_events`
WHERE environment = 'production'
  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)
QUALIFY ROW_NUMBER() OVER (
  PARTITION BY feature_key, experiment_id, subject_id
  ORDER BY exposed_at
) = 1;

Build another test that finds subjects exposed to multiple variations. Do not let the canonical view hide assignment instability.

Create reusable facts for outcomes. GrowthBook fact tables can support metrics across experiments while keeping revenue, activation, and retention semantics under data-team governance.

Partition and cluster based on recurring filters

Partition large exposure and outcome models by event date. BigQuery's partitioned-table documentation explains how qualifying predicates enable partition pruning. Cluster by common selective fields—such as experiment, feature, or subject—only when query plans and bytes scanned show a benefit.

Ship a controlled rollout

Progress through stages appropriate to risk:

1. internal or test accounts;
2. a named pilot cohort;
3. 1–5% stable traffic;
4. a measured experiment or broader ramp;
5. 100% with a monitoring window;
6. code and flag cleanup.

At every stage, define the owner, expected duration, rollback signal, and monitoring view. Evaluation errors and application reliability need operational telemetry; BigQuery supplies deeper business outcomes.

For a percentage rollout, verify that hashing is deterministic and the attribute is stable. Changing from anonymous ID to logged-in user ID mid-session can move a person between experiences.

Measure the flag with BigQuery metrics

Not every rollout is an experiment. For causal inference, assignment needs to be randomized, concurrent, and stable. Define population, unit, primary metric, guardrails, minimum meaningful effect, attribution window, and stopping rule before reading results.

GrowthBook's feature flag experiments attach experiment behavior to a flag. Its warehouse-native architecture lets analysis query BigQuery models.

A simplified 7-day conversion aggregation is:

WITH enrolled AS (
  SELECT subject_id, variation_id, exposed_at
  FROM `analytics.flag_exposures`
  WHERE experiment_id = @experiment_id
    AND DATE(exposed_at) BETWEEN @start_date AND @end_date
),
unit_metric AS (
  SELECT
    e.variation_id,
    e.subject_id,
    COUNTIF(
      o.completed_at >= e.exposed_at
      AND o.completed_at < TIMESTAMP_ADD(e.exposed_at, INTERVAL 7 DAY)
    ) > 0 AS converted
  FROM enrolled e
  LEFT JOIN `analytics.order_facts` o
    ON o.user_id = e.subject_id
  GROUP BY e.variation_id, e.subject_id
)
SELECT variation_id, COUNT(*) AS units,
       COUNTIF(converted) AS conversions,
       AVG(CAST(converted AS INT64)) AS conversion_rate
FROM unit_metric
GROUP BY variation_id;

Retain non-converters, enforce a mature observation window, and parameterize inputs. Production analysis also needs uncertainty estimates and consistent handling of ratios, outliers, repeated monitoring, and multiple metrics. GrowthBook's experiment metrics and statistics engine standardize that layer.

Validate assignment and data quality

Before reading lift, check:

• expected versus observed allocation;
• subjects exposed to multiple variations;
• null or changing IDs;
• exposure and outcomes outside the phase;
• exposure-to-metric join rates by arm;
• pre-treatment metrics and invariant dimensions;
• ingestion and transformation freshness.

GrowthBook's sample ratio mismatch documentation explains the allocation check. An SRM can arise from targeting, logging, filtering, or identity problems; investigate rather than adjusting around it.

Run an A/A phase when the flag-to-BigQuery path is new. It validates the integrated pipeline under real traffic but does not replace treatment-specific rendering and event QA.

Control BigQuery access and cost

Create a dedicated service account with permission to create query jobs in the execution project and read approved tables or authorized views. Google's query permissions guide documents the job and data access required. Avoid project-wide editor roles.

Use explicit columns, date filters, unit-level pre-aggregation, and reusable fact models. Before deployment, use a BigQuery dry run to validate SQL and estimate processed bytes. Google's cost guidance also covers quotas and cost controls.

Label jobs by application, environment, and workload. Monitor bytes, slot time, errors, and repeated query shapes. Reddit Engineering's account of optimizing BigQuery slot use is a reminder that experimentation shares finite compute with ingestion, ETL, and analytics even in a managed warehouse.

Close the lifecycle with evidence

When the rollout reaches its decision, record the variation definitions, dates, metric versions, data cutoff, result, action, and code-removal reference. A 100% rollout is not cleanup: remove the dead branch and tests, verify the permanent path, then archive the flag.

The architecture stays understandable when runtime and measurement remain separate. SDKs make safe deterministic decisions. BigQuery preserves exposures and business outcomes. Warehouse-native analysis turns them into evidence that can be reproduced after the dashboard is gone.

Reconcile flag state with warehouse evidence

Create a small operational report for every rollout phase. It should compare the control-plane allocation with first exposures observed in BigQuery, broken down by variation, environment, SDK version, platform, and time. This catches a flag configured at 10% while an old client, stale cache, or targeting rule produces a different effective population.

Keep evaluation and exposure separate in the schema. An SDK may evaluate the same flag many times during a session, but analysis normally needs the first qualifying exposure for a stable unit. Preserve raw evaluations for debugging, then publish a canonical first-exposure model with an explicit crossover policy.

Verify the negative path. Users who never reach the feature should not enter the experiment merely because they were eligible at login. Users who reach the feature and take no outcome action must remain in the metric denominator. These two rules protect both treatment relevance and zero outcomes.

Build phase boundaries into the evidence. A flag can move from internal targeting to 5%, 25%, an experiment, and full rollout. Store the configuration version and allocation active at exposure time so an analyst can reconstruct each phase. Do not overwrite the history with the flag's current value.

Test failure behavior across both systems

At runtime, disconnect a development SDK from the control plane and verify the documented cached or fallback value. Confirm that evaluation does not block the request and that the application exposes a useful diagnostic without logging sensitive targeting context.

In BigQuery, delay one ingestion path, duplicate a small test batch, and revoke a POC view grant. The analysis layer should mark data stale or fail explicitly. It should not silently switch to a partial table or compare groups with different source cutoffs.

Finally, rotate the service account key or workload identity and review job history. The flag provider and warehouse reader have different privileges and different blast radii; test and audit them independently. A reliable program can keep serving a safe value during a control-plane problem and can withhold an experiment decision during a measurement problem.

Define privacy and identity boundaries

Targeting context should contain only attributes needed for the decision. Do not send a full customer profile to a flag service or write it into every exposure row. Prefer stable pseudonymous unit IDs and join approved business attributes inside BigQuery under existing governance.

Document how anonymous and authenticated identities connect. If a visitor is randomized before signup and later purchases under an account ID, the mapping must preserve original assignment without merging two independently randomized people. Use effective timestamps and test household or shared-device behavior where it matters.

Consent and regional rules can create missing events that vary by platform or geography. Treat them as eligibility or measurement constraints defined before analysis. Compare missingness by arm and region; do not assume a large warehouse table implies complete observation.

Make the metric layer reusable

Create unit-level facts for recurring outcomes rather than letting each experiment join raw GA4, billing, and application events differently. Each fact needs a unit, event time, value, source freshness, owner, and tests. Define whether zero means no event, a measured zero, or missing data.

For count and revenue metrics, document caps, refunds, currency conversion, and repeated events. For ratios, retain numerator and denominator components at the randomized-unit grain. For retention, exclude immature units or compare equal follow-up.

Version definitions and decide whether old experiments recompute. A corrected metric can improve future decisions while still preserving the exact evidence used for an earlier one. Store the original query identity, cutoff, and result beside any restatement.

Use a staged acceptance checklist

Before internal rollout, verify SDK initialization, typed defaults, environment keys, targeting attributes, and exposure payloads. Before percentage rollout, reconcile expected and observed allocation and confirm operational guardrails. Before an experiment, freeze the hypothesis, primary metric, unit, eligibility, duration, and analysis method.

Before full rollout, review practical effect, uncertainty, data health, latency, errors, cost, and segment risks. After full rollout, monitor the permanent path, remove the losing branch and temporary tests, verify the simplified deployment, and archive the flag. Each gate has a different purpose; passing an early runtime check does not substitute for causal evidence later.

Assign an owner to every gate and a source of truth for its evidence. Store the final flag version, BigQuery cutoff, metric versions, result, approver, and cleanup reference together. If a gate fails, preserve the failure and corrective change rather than replacing it with the next configuration. That history makes incident review and future experiments materially easier.

Measure every BigQuery rollout

Combine local feature evaluation with transparent warehouse metrics for safer releases and trustworthy experiments.

Start Building Free