influxdata / influxdata/docs-v2
Delete table and data-retention pages don't document that table delete renames instead of removing
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## What to change
Add an explanation of the table-delete rename/tombstone mechanic to two pages:
1. **`content/influxdb3/enterprise/admin/tables/delete.md`** (published at `/influxdb3/enterprise/admin/tables/delete/`): currently states only that the default soft delete "schedules the table for deletion and makes it unavailable for querying." Add a section explaining that the delete renames the table to `-` rather than removing it, and that this renamed entry remains visible in `information_schema.tables` and `SHOW TABLES` output until a hard delete purges it.
2. **`content/influxdb3/enterprise/reference/internals/data-retention.md`** (published at `/influxdb3/enterprise/reference/internals/data-retention/`): currently covers only row-level retention-period expiry (background retention enforcement service, periodic Parquet file cleanup). It never connects that concept back to table deletion. Either add a short cross-reference to the delete-table page's rename behavior, or explicitly note that table deletion is a separate mechanism from retention-period expiry, so readers don't conflate the two.
Also add to the delete-table page's error/response documentation: attempting to delete an already-deleted table returns `409 Conflict`. Currently the page documents only a `404` response for a table that doesn't exist — there's no documented error case for double-deletion.
## Why
Confirmed live against a running InfluxDB3 Enterprise instance during `influxdata/docs-tooling` MCP testbench e2e testing (2026-07-23): a soft-deleted table's renamed tombstone (`e2e_conditional_write_probe-20260723T173021`) remained visible in `information_schema.tables` for a later, unrelated read-only run to see, and re-attempting to drop the tombstone returned `409 attempted to modify resource that was already deleted`.
Neither page currently documents this. As written, a reader would reasonably expect delete-table to behave like a clean, complete removal — the docs describe the destructive/irreversible aspect of deletion clearly ("Deleting a table cannot be undone") but never mention that the table's *name* and *schema metadata* persist under a new name until hard deletion. This is exactly the kind of behavioral gap that caused confusion in this session: without documentation, the natural (wrong) assumption was that the observed tombstoned name indicated a bug in agent behavior or in test-harness reset logic, when it was actually InfluxDB3's own documented-nowhere catalog behavior.
## Impact
- Anyone writing code, scripts, or tests against `DELETE /api/v3/configure/table` that lists or counts tables afterward will see unexpected entries and may misdiagnose them as bugs (in their own code, in a test harness, or in the API itself) rather than recognizing documented, expected behavior.
- Anyone relying on delete-table to remove a table name so it can be immediately recreated with the same name may not realize the old (renamed) entry still occupies catalog space and appears in listings until hard deletion.
- Support and community threads about "why does my deleted table still show up" have no canonical doc page to point to.
## Verification
1. On a running InfluxDB3 Enterprise instance, create a table, write a row, then soft-delete it (default `DELETE /api/v3/configure/table?db=&table=`, no `hard_delete_at`).
2. Run `SELECT table_name FROM information_schema.tables WHERE table_schema = 'iox'` against that database and confirm a renamed entry (`-`) appears.
3. Re-issue the same DELETE request against the tombstoned name and confirm the response is `409 Conflict`.
4. After the docs update: confirm both pages describe this rename/tombstone behavior in plain, declarative language (no jargon requiring the reader to already know IOx internals), and that the delete-table page's response table includes the `409` case alongside the existing `200`/`401`/`404`.
5. Confirm the data-retention page either cross-references the delete-table page's rename behavior or explicitly distinguishes retention-period expiry from table deletion, so a reader landing on either page doesn't conflate the two mechanisms.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with content/influxdb3/enterprise/admin/tables/delete.md and content/influxdb3/enterprise/reference/internals/data-retention.md, reading the existing deletion, response, and retention sections. Document the rename/tombstone behavior, the 409 Conflict case, and the distinction from retention expiry. Verify both pages render correctly and that the response table includes the documented status codes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- sql
- Domain
- databases, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- Half a day
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100