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."
license: "MIT"
---

# bq-refresh-table

Refresh machine-generated metadata for a documented BigQuery table.

## Scope

Only update files under:

```text
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:

   ```bash
   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:

```bash
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.