bq-add-table

name	bq-add-table
description	Add a BigQuery table to project-local docs. Use when the user provides a BigQuery table id, source id, project.dataset.table, project:dataset.table, or BigQuery Console URL and wants the table documented under docs/bigquery/tables.

bq-add-table

Add exactly one BigQuery table to the target project's local table catalog.

Inputs

Accept any of these forms:

• project.dataset.table
• project:dataset.table
• Source id copied from BigQuery, for example cwts-leiden.openalex_2025aug.work
• BigQuery Console URL containing !1s<project>!2s<dataset>!3s<table>

Use scripts/parse_bq_resource.py from this plugin when available:

python3 <plugin-root>/scripts/parse_bq_resource.py '<input>'

If parsing fails, ask the user for the exact table id. Do not guess.

Metadata Collection

Read metadata only. Do not sample rows unless the user explicitly asks.

Preferred commands:

bq --project_id=<billing-project> show --format=prettyjson <project>:<dataset>.<table>
bq --project_id=<billing-project> query --nouse_legacy_sql --dry_run \
  'SELECT * FROM `<project>.<dataset>.<table>` LIMIT 1'

The dry-run is for scan-size awareness, not for data sampling.

Output Path

Create or update:

docs/bigquery/tables/<project>/<dataset>/<table>.md

Create parent directories as needed.

When rendering from bq show --format=prettyjson, prefer:

python3 <plugin-root>/scripts/render_table_doc.py --output <doc-path> <metadata-json>

Using --output preserves an existing Human Notes section when the table doc already exists.

Table Document Shape

Use this structure:

# `<project>.<dataset>.<table>`

## Human Notes

- Purpose:
- Source:
- Grain:
- Common filters:
- Join keys:
- Caveats:

## Machine Metadata

- Project: `<project>`
- Dataset: `<dataset>`
- Table: `<table>`
- Type:
- Location:
- Partitioning:
- Clustering:
- Rows:
- Size:
- Last modified:
- Metadata refreshed:

## Schema

| Field | Type | Mode | Description |
| --- | --- | --- | --- |

## Usage Notes

- Run dry-run before table scans.
- Do not record credentials or sampled private data in this file.

Preserve any existing Human Notes when re-running this skill.