Skip to main content
← Back to list
01Issue
BugClosedSwamp ClubPublic
AssigneesNone

Relationships

#3049 Docs: data query reference lists a --limit default of 100 and omits --single

Opened by stack72 · 10/5/2026

The manual's data reference (content/manual/reference/data.md) is out of date for swamp data query.

What is wrong

  1. --limit default. Two option tables, under ### swamp data query [predicate] and under ## Querying > ### Command, say --limit defaults to 100. The CLI has no default limit: the help text reads "Maximum results (unlimited when omitted)".
  2. --single is missing from both option tables. It was added in swamp-club#2961 and is in the current release. The help text is "Require exactly one match; with --json, print the match (or its --select value) on its own instead of a results list". It conflicts with --limit, and it errors with QUERY_NO_MATCH or QUERY_MULTIPLE_MATCHES when anything other than one record matches.
  3. What limited means. "Query Result Structure" and "Numeric Comparison" say limited is true when results were truncated by --limit. It is actually true whenever the page is full, that is, when the number of results equals the limit, even if no more records match. Since swamp-club#2985, a limited page counts only live records: catalog rows whose backing file is missing no longer use up a slot. --limit 0 returns no results with limited: true.

Suggested content

  • In both option tables, change the --limit row to say "Maximum results (unlimited when omitted)".
  • Add a --single row to both option tables, with a short --single --json example that shows the bare record or the selected value.
  • Reword the limited description to: "true when the number of results reached --limit; more records may match".
02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

10/6/2026, 8:23:08 AM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

system commented 10/5/2026, 10:18:03 PM

Classified automatically when this issue was filed.

  • Type: Bug

If you feel this classification is incorrect, add a ripple to tell us so.

stack72 commented 10/6/2026, 8:23:08 AM

Shipped in https://github.com/swamp-club/swamp-club/pull/1294: both --limit rows in reference/data.md read unlimited when omitted, --single is in both option tables with a --single --json example, and limited is reworded to true when the number of results reached --limit (more records may match), covering live-records-only paging and --limit 0.

Sign in to post a ripple.