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

Relationships

#2973 Docs: document data query --single and fix the stale --limit default in reference/data.md

Opened by hammz · 10/2/2026

What changed

swamp-club#2961 adds --single to swamp data query. It requires exactly one match and, with --json, prints that record (or its --select value) as a bare object instead of the {predicate, results, total, limited} envelope. Zero matches fail with code QUERY_NO_MATCH and several with QUERY_MULTIPLE_MATCHES, exit code 1. --single conflicts with --limit and needs a predicate. Local --json errors from data query now carry a code field, as --server errors already did.

Pages to update

content/manual/reference/data.md:

  • The swamp data query CLI section (flag table near the --select and --limit rows) and the Querying section flag table: add --single with the behavior above.
  • Add an example: swamp data query 'modelName == "scanner" && name == "state"' --single --json
  • Note for scripts migrating from data get --json: the single object is the query record (payload in content, provenance fields such as workflowRunId and stepName), and it lacks ownerDefinition, garbageCollection, checksum, contentPath and contentEncoding.
  • Both flag tables say --limit defaults to 100. The CLI is unlimited when --limit is omitted, so fix the default in both places.

Suggested content

The swamp skill's data reference (.claude/skills/swamp/references/data/reference.md in the swamp repo) has the wording used for this change and can be adapted.

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

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

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

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

Shipped in https://github.com/swamp-club/swamp-club/pull/1294: reference/data.md documents --single in both option tables and a new Single Match section (bare record, --select value, QUERY_NO_MATCH / QUERY_MULTIPLE_MATCHES, conflict with --limit, the data get --json migration note, code on --json errors), and both --limit defaults now read unlimited when omitted. One correction: the query record does carry garbageCollection; only ownerDefinition, checksum, contentPath and contentEncoding are missing.

Sign in to post a ripple.