create_pg_super_document

```markdown
# PostgreSQL Super Document: `pg_stat_progress_vacuum`

## Symbol Definition
**File:** `src/backend/commands/vacuum.c`
**Type:** System View
**Definition:** A system view that reports progress of VACUUM operations in PostgreSQL. It is populated during VACUUM execution and provides real-time metrics about the operation's progress.

## Purpose & Usage Context
`pg_stat_progress_vacuum` is used to monitor long-running VACUUM operations, which can block table access during execution. Database administrators use this view to:
- Identify stalled VACUUM operations
- Estimate time remaining for VACUUM jobs
- Diagnose performance issues during maintenance

The view is automatically updated during VACUUM execution and is visible to all users with read access to system catalogs.

## Related Symbols
- `VacuumStmt` (parser definition)
- `vacuum()` (main vacuum function)
- `pg_stat_progress_base` (base view for progress tracking)
- `pg_class` (for table OIDs referenced in the view)

## Usage Examples

### Basic Monitoring Query
```sql
SELECT pid, datname, relid::regclass AS table_name,
       phase, heap_blks_total, heap_blks_scanned,
       heap_blks_vacuumed, index_vacuum_count
FROM pg_stat_progress_vacuum
WHERE relid = 'public.orders'::regclass;
```

### Identifying Stalled Operations
```sql
SELECT pid, datname, relid::regclass AS table_name,
       now() - query_start AS duration,
       phase, heap_blks_total, heap_blks_scanned
FROM pg_stat_progress_vacuum
WHERE now() - query_start > interval '5 minutes'
ORDER BY duration DESC;
```

### Performance Considerations
- The view adds minimal overhead to VACUUM operations
- Frequent queries against this view during active VACUUM may slightly impact performance
- For large tables, consider querying this view every 30-60 seconds rather than continuously

## Common Pitfalls
1. **Misinterpreting phases**: The `phase` column has multiple states (e.g., 'scanning heap', 'vacuuming heap'). Ensure you understand what each phase represents.
2. **Assuming completion**: The view shows progress, not completion. A VACUUM may appear to be making progress but still take hours to complete.
3. **Blocking queries**: While the view itself doesn't block, long-running queries against it during VACUUM may compound performance issues.

## Performance Impact
- **CPU:** Negligible (view is read-only)
- **Memory:** Minimal (data is cached in shared memory)
- **I/O:** None (data is already in memory)

## See Also
- [PostgreSQL VACUUM Documentation](https://www.postgresql.org/docs/current/sql-vacuum.html)
- `pg_stat_progress_base` (for other progress tracking views)
- `pg_stat_activity` (for active VACUUM processes)
```