Queries

WarmHub provides several query patterns for reading data. Each is optimized for a different access pattern.

Query Types

Query	Use case	CLI	MCP Tool
HEAD	Snapshot of all active entities	wh thing list	warmhub_thing_head
Count	Count matching items without fetching data	wh thing list --count	warmhub_thing_head with count: true
Get	Fetch a specific thing by wref	wh thing view	warmhub_thing_get
Query	Filter by shape, kind, about	wh thing query	warmhub_thing_query
About	Assertions whose about target resolves to a target identity	wh thing about <wref> or wh assertion list --about <wref>	warmhub_thing_about
History	Version history of a thing	wh thing history	warmhub_thing_history
Resolve	Resolve wref to identity	wh thing resolve	warmhub_wref_resolve
Search	Find things by text content	wh thing search	warmhub_thing_search
Get Many	Batch lookup by wrefs	wh thing view [wrefs...]	warmhub_thing_get_many
Refs	Backlinks and cross-references	wh thing refs	warmhub_thing_refs

Use wh thing about <wref> when starting from a thing and asking what assertions directly target it. wh assertion list --about <wref> is the equivalent assertion-domain form when you are already browsing assertions.

Choosing the Right Query

Starting fresh? Use warmhub_thing_head or wh thing list to get a broad overview of the repo’s current state. This is the fastest way to orient.

Counting items? Add --count to wh thing list or wh thing query (CLI), or pass count: true to the MCP tools. Returns { count: N } without transferring item data.

Know what you need? Use warmhub_thing_query or wh thing query with shape/kind/about filters for targeted retrieval.

Looking up one thing? Use warmhub_thing_get or wh thing view with the exact wref.

Need many things at once? Use warmhub_thing_get_many or variadic wh thing view for batch fetch — up to 500 wrefs per call, returning hits plus a list of misses. See Batch Lookup for full semantics.

Searching by content? Use warmhub_thing_search or wh thing search with a text query. Supports full-text, semantic vector, and hybrid search modes.

Tracing history? Use warmhub_thing_history or wh thing history to see all versions.

Collection Resolution

When querying with --about, results only include assertions whose about target resolves to the specified thing identity. They do not include assertions about Pair, Triple, Set, or List collection things that contain the target unless collection resolution is requested on an identity-scoped input. To also surface assertions about collections containing the thing, pass --resolve-collections:

• CLI: --resolve-collections (supported by thing about, thing query, thing history, thing search text mode, assertion list --about)
• MCP: resolveCollections: true (supported by warmhub_thing_query, warmhub_thing_about, warmhub_thing_history, and warmhub_thing_search in text mode only)
• HTTP: ?resolveCollections=true (supported by /query and /about)

See Collection Resolution for details and examples.

For current-state about filters such as thing about, assertion list --about, thing query, and thing search, pinned @vN about queries stay version-exact: resolveCollections does not expand collection members for pinned target versions. For thing history --about, the pinned about wref resolves the target identity; history still matches assertions across versions of that identity, and resolveCollections can also include assertions about collections containing it.

For broad graph discovery, use warmhub_thing_refs or wh thing refs --inbound to find current things that reference a target through wref fields. Use about queries when you specifically need assertion records and about-target filters.

Active vs Retracted

By default, HEAD, query, and about return active entities only. History is different: it always returns all versions, including retractions, but refuses to resolve a retracted shape or about target unless the include-retracted option is set. To allow resolving retracted targets, pass the lifecycle include option where supported. CLI uses --include-retracted; MCP and HTTP use includeRetracted for the same behavior.

• CLI: --include-retracted (supported by shape list, shape view, shape history, thing list, thing view, thing get-many, thing history, thing query, thing search, thing about, assertion list, assertion view, and assertion history)
• MCP: includeRetracted: true (supported by warmhub_thing_get, warmhub_thing_get_many, warmhub_thing_history, warmhub_thing_query, warmhub_thing_about, and warmhub_thing_search)
• HTTP: ?includeRetracted=true (supported by /query and /about)

Check individual command/endpoint docs for availability — not all queries support this flag.

Count Queries

Count queries (--count / count: true) return only the total instead of item data. Filter support varies by interface:

• wh thing list --count / warmhub_thing_head with count: true — supports shape, kind, match
• wh thing query --count / warmhub_thing_query with count: true — adds about and resolveCollections
• HTTP API — no count-only route is mounted; use CLI/MCP count surfaces or page through /head//query

Access Methods

WarmHub queries are available through three interfaces, but support varies by query type:

• CLI: wh <domain> <verb> [args] [--flags] — human-readable output, or --json for structured data
• MCP: warmhub_* tools — typed JSON-RPC tool calls
• HTTP API: GET /api/repos/:org/:repo/<endpoint> — RESTful queries with query parameters