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 head	warmhub_thing_head
Count	Count matching items without fetching data	wh thing head --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 about a thing	wh assertion list	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	—	warmhub_thing_get_many
Refs	Backlinks and cross-references	wh thing refs	warmhub_thing_refs

Choosing the Right Query

Starting fresh? Use warmhub_thing_head or wh thing head 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 head or wh thing query (CLI), or pass count: true to the MCP tools. Returns { count: N } without transferring item data. Also available via GET /count in the HTTP API.

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.

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 that directly target the specified thing. To also surface assertions about collections (Pair, Triple, Set, List) containing the thing, pass --resolve-collections:

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

See Collection Resolution for details and examples.

Active vs Inactive

By default, HEAD, query, and about return active entities only. History is different: it always returns all versions (including deactivations), but refuses to resolve a deactivated shape or about target unless includeInactive is set. To allow resolving deactivated targets, pass includeInactive where supported:

• CLI: --include-inactive (supported by thing history, thing query, assertion list)
• MCP: includeInactive: true (supported by warmhub_thing_history, warmhub_thing_query, warmhub_thing_about)
• HTTP: ?includeInactive=true (supported by /history, /query, /about)

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

Count Queries

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

• wh thing head --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
• GET /count — supports all filters: shape, kind, match, about, includeInactive, resolveCollections

Workspace-scoped counts are not yet supported on any interface.

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