BigQuery

Connect BigQuery tables that hold business or application metrics, such as daily active users, transactions, or warehouse query counts. Costory maps them to cloud billing data so you can track cost per user, split shared infrastructure, or build custom KPIs in Explorer and dashboards.

Manual setup
Terraform

Share the BigQuery dataset with the Costory service account:
- costory-<org-slug>@costory-production.iam.gserviceaccount.com
- Grant BigQuery Data Viewer and BigQuery Metadata Viewer on the dataset. These are the same roles used for GCP billing export.
In Costory, go to Metrics > Import new metrics datasource > BigQuery.
Enter the GCP project ID where you shared the dataset.
Select the tables Costory discovers in that project.
Configure each metric: table, date column, value column, aggregation, gap filling, and optional group-by.

Costory scans the project for tables that contain at least one numeric column and one date column. After the connection syncs, pick the integration in the metric selector when editing a dashboard widget or building a query in Explorer.

This connector imports usage metrics from your BigQuery tables. To import GCP billing data, use GCP Billing Setup. To export Costory dashboard data to your own BigQuery project, see BigQuery Data Exports.

Example table schema

Your table needs a date column and at least one numeric metric column. Optional string columns work as group-by dimensions.

CREATE TABLE `my-project.analytics.daily_active_users` (
  usage_date DATE,
  product STRING,
  active_users INT64
);

Common metrics to import:

Product analytics: daily or monthly active users, sessions, sign-ups
Business KPIs: revenue, orders, customers, emails sent
Application usage: API calls, background jobs, feature usage counts
Data platform activity: query counts, bytes processed, or slot hours per team or project

Table requirements

Requirement	Details
Region	Tables must be in the same region as your Costory workspace. Costory uses EU by default and US for US-based organizations. Multi-region locations (`EU`, `US`) work. Single-region datasets (for example `europe-west1`) are not supported because BigQuery can only query tables in the exact same location. Replicate data to `EU` or `US` with BigQuery data replication if needed.
Numeric column	At least one numeric column, such as `FLOAT64`, `NUMERIC`, or `BIGNUMERIC`.
Date column	At least one date or timestamp column: `DATE`, `DATETIME`, or `TIMESTAMP`.

Metric configuration

Configure metrics from a dashboard widget or in Explorer. In the metric selector, choose your BigQuery integration, then set:

Field	Description
Table name	The BigQuery table to read.
Date column	Column used for the time series. If Costory finds multiple date columns, it defaults to the first one.
Numeric column	Column with the metric value. Defaults to the first numeric column when several are available.
Aggregation	How values are rolled up: Sum, Avg, or Agg.
Gap filling	How missing dates are filled: 0 (zero), Forward (carry the last value), or Linear (interpolate).
Group by	Optional dimension column to split the metric (for example team, product, or environment).

Save a metric for Virtual Dimensions

To use a BigQuery metric in a or shared cost allocation rule, save it as a named metric first:

Go to Metrics > Create Metric.
Name the metric.
Select the BigQuery table, date column, numeric column, aggregation, gap filling, and group-by.
Save the metric, then reference it when you configure the virtual dimension rule.

See Unit Economics for formula examples, or BigQuery cost visibility with dbt for attributing warehouse spend by model or team.

Costory caches BigQuery table schemas for performance. After you add a table or change columns, open Metrics, find your BigQuery integration, click ⋯, then Refresh catalog so the new schema appears.

Troubleshooting

Issue	What to check
Table does not appear	Confirm the dataset is shared with the Costory service account, the table has both a date and numeric column, and the dataset region matches your Costory workspace. Then run Refresh catalog.
Wrong date or value column selected	Open the metric configuration and pick the correct columns manually. Costory defaults to the first matching column it finds.
Dataset is in a single region	Replicate the dataset to `EU` or `US` with BigQuery data replication. Costory cannot query tables in locations such as `europe-west1` directly.

Unit Economics

Combine BigQuery metrics with cloud cost in Explorer formulas.

Shared Cost Allocation

Split shared infrastructure costs using BigQuery usage metrics.

Usage Metrics

Browse all supported usage metric sources.

BigQuery and dbt visibility

Attribute BigQuery spend by dbt model, package, or team.

Get Started

Setup

Understand

Tag & Allocate

Share

Teams

Technical Documentation

Glossary

Example table schema

Table requirements

Metric configuration

Save a metric for Virtual Dimensions

Troubleshooting

Unit Economics

Shared Cost Allocation

Usage Metrics

BigQuery and dbt visibility

​Example table schema

​Table requirements

​Metric configuration

​Save a metric for Virtual Dimensions

​Troubleshooting

​Related pages

Unit Economics

Shared Cost Allocation

Usage Metrics

BigQuery and dbt visibility

Example table schema

Table requirements

Metric configuration

Save a metric for Virtual Dimensions

Troubleshooting

Related pages