BigQuery

Query BigQuery tables live as external metrics in Advanced Explorer. Grant dataset-level access to the Costory service account, validate the project, then pick a table, date field, and value column. Costory does not copy table data. On Add integration, the GCP tile lists Any BigQuery table and Cloud Monitoring metrics. This page is BigQuery Metric. For live GCP infrastructure metrics, see GCP Cloud Monitoring.

See BigQuery integration and cost allocation in action

Connect GCP BigQuery page with dataset access steps and project ID field — Connect GCP BigQuery: grant dataset access on the left, Connection details on the right

Manual setup
Terraform

Open the GCP tile

Go to Integrations, click + Add integration, then under External metric choose GCP. The connect URL is /integration/new/gcp/bigquery.

Grant dataset access

Copy the Costory service account from the connect screen. Open the BigQuery dataset you want Costory to read, share it with that account, and grant BigQuery Data Viewer and BigQuery Metadata Viewer on the whole dataset, not on individual tables. Project-level access is not required.These are the same roles used for GCP billing export.

Enter connection details

Set Connection name and GCP project ID. Click Validate, then Save connection.

This connector queries 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.

An EU organization can use a US dataset if it has an EU replica. Analytics Hub linked datasets in the project are included. Share the linked dataset, not the publisher dataset.

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 query:

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 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. An EU organization can use a US dataset if it has an EU replica.
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`.

Query after you connect

Queries run live. Costory does not copy table data.

Open Advanced Explorer

Click Explore your data, then switch Classic to Advanced. Classic greys out non-cost metrics.

Add the BigQuery metric

Click + Add Metric. Use the integrations chip, then pick BigQuery. Helper text describes it as a live external usage metric.

Advanced Explorer metric picker open on Cost, with integrations listing Tsuga and BigQuery — Metric picker chips: cost, usage, metric, budget, and integrations

Choose a table and columns

Pick a table from the picker, then set Date field, Value column, Aggregate (SUM), Gap fill (FORWARD FILL, ZERO, or LINEAR), and optional Group by.

Select metric dropdown listing BigQuery tables such as demo_raw.artifact_registry and demo_raw.aws_ec2 — BigQuery table picker after you select the BigQuery integration

Fix an empty chart

If the chart is empty, pick a different table and change Period. Options include Custom dates, Trailing 7 / 30 / 45 / 90 Days, MTD, QTD, YTD, Last Week, Last Month, Last 3 / 6 / 12 months, and Last Invoice Month.

Advanced Explorer Period menu listing Custom dates, trailing ranges, MTD, QTD, YTD, and Last Invoice Month — Period dropdown with Trailing 45 Days selected

In the demo workspace, demo_raw.artifact_* tables stayed empty at every range. demo_raw.raw_v2 with Trailing 90 Days rendered using date billing_period_end, value billed_cost, SUM, and FORWARD FILL.

Advanced Explorer bar chart of Externalmetric from BigQuery demo_raw.raw_v2 over Trailing 90 Days — External metric chart for demo_raw.raw_v2 with billed_cost SUM and FORWARD FILL

Add cost or a formula

Optionally click + Add Metric for Cost, then + Add Formula such as b / a.

Metric configuration

Field	Description
Table	The BigQuery table to read.
Date field	Column used for the time series.
Value column	Column with the metric value.
Aggregate	How values are rolled up. Use SUM unless you have a reason to pick another aggregate.
Gap fill	How missing dates are filled: FORWARD FILL, ZERO, or LINEAR.
Group by	Optional dimension column to split the metric (for example team, product, or environment).

Use the series in a or shared cost allocation rule after you can query it in Explorer.See Unit Economics for formula examples, or BigQuery cost visibility with dbt for attributing warehouse spend by model or team.

Troubleshooting

Issue	What to check
Table does not appear	Confirm the dataset is shared with the Costory service account on the whole dataset, the table has both a date and numeric column, and the dataset region matches your Costory workspace (or has an EU replica for an EU org). For Analytics Hub, share the linked dataset, not the publisher dataset.
Chart is empty	Pick a different table and change Period. In the demo workspace, `demo_raw.artifact_` stayed empty. `demo_raw.raw_v2` with Trailing 90 Days* rendered.
Wrong date or value column selected	Open the metric configuration and pick the correct columns.
Dataset is in a single region	Replicate the dataset to `EU` or `US` with BigQuery data replication.

GCP Cloud Monitoring

Query live GCP metrics on the same GCP tile.

Unit Economics

Combine BigQuery metrics with cloud cost in Explorer formulas.

Shared Cost Allocation

Split shared infrastructure costs using BigQuery usage metrics.

Metrics Correlation

Browse all supported external 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

Query after you connect

Metric configuration

Troubleshooting

GCP Cloud Monitoring

Unit Economics

Shared Cost Allocation

Metrics Correlation

BigQuery and dbt visibility

​Example table schema

​Table requirements

​Query after you connect

​Metric configuration

​Troubleshooting

​Related pages

GCP Cloud Monitoring

Unit Economics

Shared Cost Allocation

Metrics Correlation

BigQuery and dbt visibility

Example table schema

Table requirements

Query after you connect

Metric configuration

Troubleshooting

Related pages