> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckbrain.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Search & Facets

> Four-facet retrieval: who, where, when, source — plus ranking modes

The query surface is **four universal facets** that map to SQL predicates, an ambient view layer, and one escape hatch. Calling agents compose flags; the CLI never parses natural language into args.

| Facet      | Flags                    | Example                                                   |
| ---------- | ------------------------ | --------------------------------------------------------- |
| **WHO**    | `--person`, `--from`     | `--person devon` *(ships with the entity spine)*          |
| **WHERE**  | `--in <container>`       | `--in admin-cindy` — channel, chat, thread, meeting, repo |
| **WHEN**   | `--since --until --on`   | `--since 30d`, `--on 2026-07-01` (ISO or `Nd/Nw/Nm/Ny`)   |
| **SOURCE** | `--source app[:account]` | `--source slack:autono`, `--source markdown`              |

**Ranking modes:** `--mode bm25` (default — Okapi BM25 over title+text), `--mode vec` (local-embedding similarity), `--mode hybrid` (RRF fusion of both, k=60). The default only changes when the eval harness proves a mode wins.

**Escape hatch:** `--where "<raw SQL>"` over the docs columns — source-specific fields stay in the VARIANT payload, reachable by SQL instead of new flags.

**View (ambient, set by workspace config):** `--instance` (which brain), `--class` (classification ceiling), `--observer` (whose assertions).

```bash theme={null}
duckbrain search "payroll" --source slack:autono --in admin-cindy --since 30d
duckbrain context "onboarding" --source slack:beyond --budget 3000 --mode hybrid
```


## Related topics

- [search](/commands/search.md)
- [For Agents](/agents.md)
- [DuckBrain](/index.md)
- [context](/commands/context.md)
- [index](/commands/index.md)