dolthub / dolthub/docs-2

Document Dolt statistics system variables and tidy the stats docs

Open
#80 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
TypeScript
Stars
2
Forks
1
Avg merge
4h 41m
Merged PRs (30d)
40

Description

Follow-up from the source-vs-docs cross-check (#64). The statistics surface is only partially documented, and what exists is scattered.

### Current state

- ✅ The `dolt_statistics` **system table** is documented in [`dolt-system-tables.md`](https://github.com/dolthub/docs-2/blob/main/site/dolt/src/content/reference/sql/version-control/dolt-system-tables.md) (it's the only stats table).
- ✅ Eight `dolt_stats_*` **procedures** (`flush`, `gc`, `info`, `once`, `purge`, `restart`, `stop`, `wait`) are documented in [`dolt-sql-procedures.md`](https://github.com/dolthub/docs-2/blob/main/site/dolt/src/content/reference/sql/version-control/dolt-sql-procedures.md).
- 🟠 Stats **system variables** are only mentioned in passing in [`sql-support/miscellaneous.md`](https://github.com/dolthub/docs-2/blob/main/site/dolt/src/content/reference/sql/sql-support/miscellaneous.md) — no per-variable sections in `dolt-sysvars.md`, and at least one name there is stale.

### Gaps to close

**1. Stats system variables → proper sections in `dolt-sysvars.md`.** These are registered in [`dsess/variables.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dsess/variables.go) / [`sqle/system_variables.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/system_variables.go) but have no entry in `dolt-sysvars.md`:

- `dolt_stats_enabled`
- `dolt_stats_paused`
- `dolt_stats_memory_only`
- `dolt_stats_branches`
- `dolt_stats_job_interval`
- `dolt_stats_gc_enabled`
- `dolt_stats_gc_interval`

Each needs the standard section (description, scope, default, accepted values). A "Statistics variables" subsection in `dolt-sysvars.md` probably makes sense, with the index (`sql-extensions.md`) updated to point at the new anchors instead of the current `miscellaneous.md` ones.

**2. `dolt_stats_timers` procedure** is registered in [`dprocedures/init.go`](https://github.com/dolthub/dolt/blob/main/go/libraries/doltcore/sqle/dprocedures/init.go) but undocumented — add it to `dolt-sql-procedures.md` (or confirm it's internal-only and intentionally omit, as we did with `dolt_storage_format`).

**3. Stale reference**: `miscellaneous.md` mentions `dolt_stats_auto_refresh_enabled` as the "up to 1.50.x" name. Once the variables are documented properly, reconcile/clean up that section so it points at the canonical docs rather than restating settings inline.

### Out of scope / tracked elsewhere

- The doltgres `dolt_stats_*` functions (all 9) are tracked in #65 (deliberately skipped there for now).

Surfaced during the cross-check for #43 (see #64).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.