| 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
-
Parse the target table from the file path, file title, or user input.
-
Read current metadata with:
bq --project_id=<billing-project> show --format=prettyjson <project>:<dataset>.<table>
-
Compare old and new schema.
-
Preserve Human Notes and other user-authored project semantics.
-
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.
