Table & column-usage tools

Two tools for understanding how tables and columns are used over a time window: one breaks down per-column usage (the primary signal for choosing cluster keys and finding dead columns), the other lists tables with their usage and storage metrics.

Both tools default to the last 30 days, resolve the window locally, and echo it back as effective_processing_time_start / effective_processing_time_end — pass those bounds back when paginating. Pass an explicit ISO-8601 processing_time_start / processing_time_end to override.

All sample responses below use synthetic data.

table_column_usage

Reports how individual columns are used by queries over a time window — the primary signal for cluster-key choice. Default mode aggregates per-column usage (which columns appear in WHERE / JOIN / GROUP BY / etc. and how often); pass unused: true to list columns no query touched. Filter usage_types (any of WHERE, SELECT, LEFT_JOIN, RIGHT_JOIN, INNER_JOIN, FULL_JOIN, GROUPBY, ORDERBY, AGGREGATE) and group_by (USAGE_TYPE, default, or COLUMN_NAME). table_fqn is optional — omit it to scan all tables.

Sample call

"Over the last month, which columns of analytics.orders_fact are filtered or grouped on most?"

Sample response — usage

{
  "data": [
    { "table_fqn": "analytics_db.analytics.orders_fact", "column_name": "order_date", "usage_type": "WHERE", "usage_expression": "", "usage_operator": ">=", "usage_value": "", "sum_count": 1842 },
    { "table_fqn": "analytics_db.analytics.orders_fact", "column_name": "region", "usage_type": "GROUPBY", "usage_expression": "", "usage_operator": "", "usage_value": "", "sum_count": 970 }
  ],
  "next_page_token": "",
  "effective_processing_time_start": "2026-04-29T00:00:00+00:00",
  "effective_processing_time_end": "2026-05-29T00:00:00+00:00"
}

Sample response — unused: true

{
  "data": [
    { "table_fqn": "analytics_db.analytics.orders_fact", "column_name": "legacy_flag", "data_type": "BOOLEAN" }
  ],
  "next_page_token": "",
  "effective_processing_time_start": "2026-04-29T00:00:00+00:00",
  "effective_processing_time_end": "2026-05-29T00:00:00+00:00"
}

table_usage

Lists tables with their storage and usage metrics — the storage-overview view. Each row carries fqn, table_type, row_count, query_count, size_byte, column_count, and unused_column_count. Optionally filter by catalog / schema / table (substring) and usage (USED / UNUSED); sort by ROW_COUNT (default), SIZE, or QUERY_COUNT.

Sample call

"What are the largest tables in the analytics schema, and how many have unused columns?"

Sample response

{
  "data": [
    {
      "fqn": "analytics_db.analytics.orders_fact",
      "table_type": "TABLE",
      "row_count": 1400000000,
      "query_count": 1842,
      "has_schema_data": true,
      "size_byte": 3100000000000,
      "column_count": 24,
      "unused_column_count": 3
    }
  ],
  "next_page_token": "",
  "effective_processing_time_start": "2026-04-29T00:00:00+00:00",
  "effective_processing_time_end": "2026-05-29T00:00:00+00:00"
}

Next: Built-in Prompts →