bq-refresh-table

name	bq-refresh-table
description	Refresh an existing BigQuery table doc under docs/bigquery/tables while preserving human notes. Use when schemas, partitioning, clustering, row counts, sizes, or last modified metadata may have changed.

bq-refresh-table

Refresh machine-generated metadata for a documented BigQuery table.

Scope

Only update files under:

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

Do not rewrite project SQL, extraction scripts, notebooks, or unrelated docs.

Process

1. Parse the target table from the file path, file title, or user input.

2. Read current metadata with:

   bq --project_id=<billing-project> show --format=prettyjson <project>:<dataset>.<table>
   

3. Compare old and new schema.

4. Preserve Human Notes and other user-authored project semantics.

5. Update Machine Metadata, Schema, and refresh timestamp.

Use scripts/render_table_doc.py from this plugin when it helps render the machine section from bq show --format=prettyjson. Write through --output so the existing Human Notes section is preserved:

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

Change Reporting

After refreshing, summarize:

• Added fields.
• Removed fields.
• Type or mode changes.
• Partitioning or clustering changes.
• Size or row-count changes when available.

If a field was removed or its type changed, call that out explicitly. Silent schema drift is the bug this skill exists to prevent.