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 }
}

The HTTP API does not currently mount a single-wref thing lookup route. Use the CLI, SDK, or MCP surfaces for direct wref lookups.

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

Within data, fields typed as wref rehydrate on read: same-repo refs return their local form (e.g. Loc/cave@v1); cross-repo refs return their canonical form (e.g. wh:org/repo/Loc/cave@v1). When a cross-repo wref points at a thing in a soft-deleted source repo, the field is returned as null — the hidden repo’s identity is suppressed rather than leaked through the read surface. The same suppression applies to assertion aboutWref and other ref fields surfaced by /head, /about, and SDK reads.

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/*",
    "includeRetracted": false,
    "limit": 50
  }
}

Count via MCP:

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

The HTTP example below uses the public warmhub-data/congress-trading repo so you can copy-paste it directly; the CLI and MCP blocks above use generic Location/Belief names that you’d swap for your repo’s own shapes.

GET /api/repos/warmhub-data/congress-trading/query?shape=StockTrade&kind=thing&match=StockTrade%2F2024%2F20025368%2F*&limit=25

Anonymous callers reading public repos are capped at limit=25 per page; authenticated callers can request up to limit=500. See Anonymous Pagination Caps.

All filter parameters are optional. Combine them to narrow results. The HTTP API does not currently mount a count-only route; use CLI/MCP count surfaces for count-only reads.

About Queries

Get all assertions about a specific thing:

wh thing about Location/cave
wh thing about Location/cave --shape Belief
wh thing about Location/cave --match "Belief/*"

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

wh assertion list --about Location/cave remains available when you are already working in the assertion domain.

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 thing about Location/cave --resolve-collections
wh assertion list --about 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 child assertions about the returned assertions:

wh thing about Location/cave --depth 2

{
  "name": "warmhub_thing_about",
  "arguments": {
    "wref": "Location/cave",
    "shape": "Belief",
    "match": "Belief/*",
    "includeRetracted": 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, operation (add/revise/retract), active, createdAt, and committerWref — the committer’s local or canonical wref when the originating commit recorded one, omitted otherwise.

Cross-repo visibility

Cross-repo wref lookups require effective repo:read permission on the target repo. Public repos are readable by anyone. For private repos, callers without that access see an error — except cross-repo search and batch lookup, which fold unreadable results into { items: [] } or missing[] entries to keep search and batch streaming-friendly.

See Getting Access for the precise rules.

Wref Resolution

Resolve a wref to its canonical identity (and, on CLI/SDK, the resolved version’s data):

wh thing resolve Location/cave

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

CLI wh thing resolve and SDK client.thing.resolve(...) return the same payload as thing.get. The default CLI render shows identity columns only; pass --json for the full payload.
MCP warmhub_wref_resolve returns only name, kind, active, version, and shapeName. Pair with warmhub_thing_get to fetch data.

Batch Lookup

Fetch up to 500 things by wref in a single call. On the CLI, wh thing view is variadic — pass multiple wrefs or use --file to trigger batch mode. Also available via the TypeScript SDK (client.thing.getMany) and MCP — all three enforce the same 500-wref cap and version-qualify missing entries the same way.

The CLI examples below use a couple of wref conventions: Shape/name reads HEAD, Shape/name@v3 pins to version 3, and --file=- is the standard Unix marker for “read newline-delimited input from stdin.”

# CLI — wrefs come from positional args, --file <path>, or piped stdin (any combination)
wh thing view Location/cave Location/forest Player/alice
cat wrefs.txt | wh thing view                         # one wref per line, piped stdin
wh thing view --file wrefs.txt --version 1            # newline-delimited file, pin all to @v1
wh thing view --file=- < wrefs.txt --format jsonl     # one JSON line per *deduped* requested wref

// SDK
const result = await client.thing.getMany(
  'acme', 'world',
  ['Location/cave', 'Location/forest', 'Player/alice'],
  1, // optional fallback version for unpinned wrefs
  { includeRetracted: true }, // optional — return retract versions when reading a historical version (otherwise retract versions are excluded)
)
// result: { requested, items, missing }

// MCP equivalent
{
  "name": "warmhub_thing_get_many",
  "arguments": {
    "orgName": "acme",
    "repoName": "world",
    "wrefs": ["Location/cave", "Location/forest", "Player/alice"],
    "version": 1
  }
}

Shared across CLI, SDK, and MCP:

All three surfaces return { requested, items, missing }:
- requested is a number — the count of input wrefs the call processed. The CLI unions positional + --file + stdin inputs and dedupes before the round-trip; the SDK and MCP forward the wrefs array as-is, so duplicates count toward the 500-wref cap and produce duplicate items/missing entries.
- items[] carries the resolved entities — same fields as a single-thing read.
- missing[] is string[] — wrefs that don’t exist or that the caller can’t read, returned instead of throwing.
Missing entries are version-qualified when a top-level version / --version was supplied and the wref didn’t already carry a version modifier (@vN or @HEAD). Per-wref pins always survive intact (no double-pinning).
All three enforce a 500-wref cap per call.

CLI-only:

--version implies --include-retracted, so retract versions can be retrieved by their pinned id (mirrors wh thing view --version). Pass --include-retracted explicitly when you want retract versions without a fallback --version.
--format jsonl emits one row per deduped requested wref, in input order. (Inputs from positionals + --file + stdin are unioned and deduped before the round-trip, so a wref supplied twice produces one row.) Use it for shell pipelines where you want to filter or fan out the result. Use --json instead when you want the full {requested, items, missing} envelope as a single object.

Each row is {requested, found, wref, ...}. requested is the input wref preserved verbatim (so canonical/cross-repo inputs are still identifiable on the consumer side), wref is the local form for hits or the version-qualified form for misses, and found is the boolean.
--live is rejected (batch reads are one-shot — use wh thing view <wref> --live for per-thing polling).

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 thing about Location/cave --live

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

Hit a problem or have a question? Get in touch.