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.
Closed
No activity in this phase yet.
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.