BigQuery primer

BigQuery is a fully-managed analytics warehouse with serverless execution and standard ANSI SQL. Meridian treats it as a first-class data source: you can route any model behind model: meridian/sql at a BigQuery dataset, stream rows back as structured tool output, and keep the warehouse credential server-side. This primer covers the three checkpoints every integration needs before going to production.

1. Service account auth

Create a service account scoped to a single dataset, grant itroles/bigquery.dataViewerand roles/bigquery.jobUser, and store the JSON key as a Meridian secret. Never embed credentials in agent prompts — the gateway substitutes them at request time.

2. Warehouse-aware SQL

BigQuery charges by bytes scanned. Always project explicit columns, partition on _PARTITIONDATE, and prefer APPROX_COUNT_DISTINCTover exact COUNT(DISTINCT ...) on cardinality > 10M.

SELECT
  user_id,
  APPROX_COUNT_DISTINCT(session_id) AS sessions
FROM `project.analytics.events`
WHERE _PARTITIONDATE
  BETWEEN DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
      AND CURRENT_DATE()
GROUP BY user_id
ORDER BY sessions DESC
LIMIT 100;

3. Streaming results

For result sets above 10MB, Meridian opens a Storage Read API stream and pages rows back as Arrow batches. The agent receives a cursor it can fetch incrementally instead of a single blob — cheaper, lower latency, and safe under the 32K token reply cap.