4051077cff
- API.md: document `similar_to`/`region`/`unavailable_shards` on /feed and /search, the new POST /vector_search k-NN probe, and the cluster-node-only routes (/cluster/*, /sharded/*, /hardnegs) - CHANGELOG.md: M12 entries — multi-vector preference + ANN candidate-gen, idle-readiness + TLS scale-up (m12p5/p6), sharded ingestion (m12p4) - ROADMAP.md: mark M11 + M12 COMPLETE; restate the v1.0 bar (30-day-green nightly calendar + Ref-A/k3s throughput re-runs) - prometheus-alerts.yaml: add ship-stall, quorum-lag, divergence-quarantine, reseed-pending, and snapshot-pin-force-drop cluster alerts - check-docs.sh: self-updating milestone-status freshness guard derived from ROADMAP's latest COMPLETE milestone - refresh specs (00-14), ai-lookup, guides, and runbooks to M0-M12
68 lines
1.6 KiB
Markdown
68 lines
1.6 KiB
Markdown
# Query Language
|
|
|
|
**Last Updated:** 2026-02-19
|
|
**Confidence:** High
|
|
|
|
## Summary
|
|
|
|
The query interface is a single operation that encapsulates candidate retrieval, filtering, ranking, and diversity enforcement. Three primary operations: RETRIEVE (feed/browse), SEARCH (text+semantic), and SIGNAL (engagement write-back).
|
|
|
|
**Key Facts:**
|
|
- One query replaces what currently requires 6 systems
|
|
- RETRIEVE: feed generation, browse, related content
|
|
- SEARCH: keyword + semantic + hybrid retrieval
|
|
- SIGNAL: engagement event write-back (closes the feedback loop in the same transaction)
|
|
- All queries accept: FOR USER, USING PROFILE, FILTER, DIVERSITY, LIMIT
|
|
- RETRIEVE also accepts SIMILAR TO (`similar_to` — a seed item for "more like this") and an optional `ef_search` ANN-recall/latency override
|
|
- Filters are composable — any combination is valid
|
|
|
|
**File Pointer:** `VISION.md:47-57`
|
|
|
|
## Query Shapes
|
|
|
|
**Feed retrieval:**
|
|
```
|
|
RETRIEVE items
|
|
FOR USER @user_id
|
|
CONTEXT feed
|
|
USING PROFILE for_you
|
|
FILTER unseen, unblocked, format:video
|
|
DIVERSITY max_per_creator:2, format_mix:true
|
|
LIMIT 50
|
|
```
|
|
|
|
**Search:**
|
|
```
|
|
SEARCH items
|
|
QUERY "rust tutorial beginner"
|
|
VECTOR query_vector
|
|
FOR USER @user_id
|
|
USING PROFILE search
|
|
DIVERSITY max_per_creator:2
|
|
LIMIT 20
|
|
```
|
|
|
|
**Signal write:**
|
|
```
|
|
SIGNAL like
|
|
item: @item_id
|
|
user: @user_id
|
|
timestamp: now()
|
|
```
|
|
|
|
**Related content:**
|
|
```
|
|
RETRIEVE items
|
|
SIMILAR TO @item_id
|
|
FOR USER @user_id
|
|
USING PROFILE related
|
|
FILTER unseen
|
|
EF_SEARCH 128 # optional: tune ANN recall vs. latency per query
|
|
LIMIT 10
|
|
```
|
|
|
|
## Related Topics
|
|
- [Ranking Profiles](../services/ranking-profiles.md)
|
|
- [Filters](./filters.md)
|
|
- [Sort Modes](./sort-modes.md)
|