# GCP BigQuery TopSQL Query Support

## Background

GCP Dedicated cluster `10123293495242577103` can query Slow Query through
BigQuery, but logical and physical TopSQL queries fail before user SQL runs.
The current BigQuery table manager creates every source as a Delta Lake table;
TopSQL is Hive-partitioned Parquet data and requires a different external-table
definition.

## Goal

Make Data Proxy TopSQL queries work for any GCP cluster with a configured
TopSQL source. Keep the existing logical schema (`timestamps` and
`topsql_cpu_time_ms`) and preserve the current Premium-only Statements data
boundary.

## Implementation

- Create TopSQL physical tables as Parquet Hive-partitioned external tables,
  with explicit schemas and component-specific GCS roots.
- Create the logical `topsql_<cluster>` BigQuery view after its TiDB, TiKV,
  SQL-meta and plan-meta dependencies are ready.
- Reconcile a pre-existing Clinic-owned wrong Delta external table or physical
  table safely before creating the correct object. Do not touch unrelated
  BigQuery objects or GCS data.
- Keep Delta Lake auto-detection and schema refresh for Slow Query and
  Statements only.
- Add unit coverage for TopSQL table specs, dependency ordering, cache and
  concurrent creation, legacy-object replacement, and non-TopSQL regression.

## Verification and release

- Run focused engine, service and handler tests plus `git diff --check`.
- In staging, verify a GCP Dedicated cluster returns 200 for logical and
  physical TopSQL queries using `timestamps` and `topsql_cpu_time_ms`; unknown
  aliases remain a 400 unknown-field response.
- Required deployment is only `clinic-data-service` / `clinic/data-service`,
  first in staging and then prod-cloud after explicit production approval.
- Statements, O11Y data production, app-delivery configuration, Kong and other
  Clinic images are excluded.