Filtering and Lookup

Beyond HEAD snapshots, WarmHub provides targeted query functions for specific lookups, filtered searches, history, and batch operations.

Get by Wref

Fetch a specific thing by its wref:

wh thing view Location/cave
wh thing view Location/cave --version 3

{
  "name": "warmhub_thing_get",
  "arguments": { "wref": "Location/cave", "version": 3 }
}

GET /api/repos/myorg/myrepo/things/Location%2Fcave?version=3

Returns the thing’s name, wref, shape, kind, version, active state, data, and (for assertions) about reference.

Query by Filters

General-purpose query with combinable filters:

# By shape
wh thing query --shape Location

# By kind
wh thing query --kind assertion

# By about target (assertions about a specific thing)
wh thing query --about Location/cave

# Combined filters
wh thing query --shape Belief --about Location/cave --limit 20

# Resolve through collections — include assertions about collections containing the target
wh thing query --about Location/cave --resolve-collections
wh thing query --shape Belief --about Location/cave --resolve-collections

# With glob pattern (match applies to full wrefs: Shape/name)
wh thing query --shape Location --match "Location/dungeon/*"

# Count matching items (no pagination, returns { count: N })
wh thing query --shape Location --count
wh thing query --kind assertion --about Location/cave --count

{
  "name": "warmhub_thing_query",
  "arguments": {
    "shape": "Belief",
    "about": "Location/cave",
    "kind": "assertion",
    "match": "Belief/dungeon/*",
    "includeInactive": false,
    "limit": 50
  }
}

Count via MCP:

{
  "name": "warmhub_thing_query",
  "arguments": {
    "shape": "Belief",
    "about": "Location/cave",
    "count": true
  }
}

GET /api/repos/myorg/myrepo/query?shape=Belief&about=Location%2Fcave&kind=assertion&match=Belief%2Fdungeon%2F*&limit=50

Count via HTTP:

GET /api/repos/myorg/myrepo/count?shape=Belief&about=Location%2Fcave

All filter parameters are optional. Combine them to narrow results.

About Queries

Get all assertions about a specific thing:

wh assertion list Location/cave
wh assertion list --about Location/cave --shape Belief
wh assertion list Location/cave --match "Belief/*"

# Include assertions about collections containing the target
wh assertion list Location/cave --resolve-collections

Collection Resolution

By default, --about only returns assertions that directly target the specified thing. To also include assertions about collections (Pair, Triple, Set, List) that contain the thing, add --resolve-collections:

wh assertion list Location/cave --resolve-collections
wh thing query --about Location/cave --resolve-collections
wh thing history --about Location/cave --resolve-collections
wh thing search "safe" --about Location/cave --resolve-collections

Collection resolution looks up current (HEAD) collection memberships. It is not supported with --mode vector or --mode hybrid search.

Search pagination caveat: when combining search with --about or --resolve-collections, pages may be sparse — a page may contain fewer items than limit, or even zero items, while nextCursor is still non-null. Keep paginating until nextCursor is absent to collect all results.

The --depth flag retrieves nested assertions (assertions about assertions):

wh assertion list Location/cave --depth 2

{
  "name": "warmhub_thing_about",
  "arguments": {
    "wref": "Location/cave",
    "shape": "Belief",
    "match": "Belief/*",
    "includeInactive": false,
    "depth": 2
  }
}

The response includes a target object (the thing being queried) and an assertions array. With depth > 1, each assertion may include a children array.

Version History

See all versions of a thing:

wh thing history Location/cave
wh thing history Location/cave --limit 10

Query history by shape or about filters (without a specific wref):

wh thing history --shape Belief --limit 20
wh thing history --about Location/cave --limit 5

# Include assertions about collections containing the target
wh thing history --about Location/cave --resolve-collections

{
  "name": "warmhub_thing_history",
  "arguments": {
    "wref": "Location/cave",
    "limit": 10
  }
}

At least one of wref, shape, or about is required. Each version entry includes: version number, operation (add/revise), commit author, timestamp, and commit message.

Wref Resolution

Resolve a wref to its canonical identity without fetching full data:

wh thing resolve Location/cave

{
  "name": "warmhub_wref_resolve",
  "arguments": { "wref": "Location/cave" }
}

Returns: wref, version, kind, and active state.

Batch Lookup

Fetch many things by wref in a single call (MCP only):

{
  "name": "warmhub_thing_get_many",
  "arguments": {
    "wrefs": ["Location/cave", "Location/forest", "Player/alice"],
    "version": 1
  }
}

Missing wrefs are returned in a missing array rather than causing an error. The optional version parameter pins all lookups to a specific version.

Search

Search things by text content. Three modes are available:

text (default) — full-text search against thing names, shape names, and data fields. Supports pagination.
vector — semantic similarity search using embeddings. No pagination; does not support --about filter.
hybrid — runs text and vector searches in parallel, merges results with reciprocal rank fusion. No pagination.

# Full-text search (default mode)
wh thing search "safe location" --shape Belief

# Semantic similarity search
wh thing search "places that are dangerous" --mode vector

# Hybrid search — combines text and vector results
wh thing search "policy" --mode hybrid --limit 10

# Filter by about target (text mode only)
wh thing search "safe" --about Location/cave

# Resolve through collections (text mode only)
wh thing search "safe" --about Location/cave --resolve-collections

# Paginate through text results
# NOTE: when using --about or --resolve-collections, pages may be sparse —
# a page may return fewer items than --limit (or even zero) while nextCursor
# is still present. Paginate until nextCursor is absent to collect all results.
wh thing search "policy" --limit 50 --cursor <token>

# Fetch all pages automatically (text mode only)
wh thing search "policy" --all

{
  "name": "warmhub_thing_search",
  "arguments": {
    "query": "safe location",
    "shape": "Belief",
    "mode": "hybrid",
    "limit": 10
  }
}

Search is available via the CLI, SDK (client.thing.search()), and MCP (warmhub_thing_search) but is not currently exposed as an HTTP endpoint.

Reactive Mode

Most CLI queries support --live for real-time updates:

wh thing query --shape Location --live
wh thing history Location/cave --live
wh assertion list Location/cave --live

This opens a WebSocket connection and re-renders whenever the underlying data changes.