Skip to content

Commit d14f256

Browse files
salman1993claude
andcommitted
docs(search): describe the prefix rank window's access path
Separate "does not change the access boundary" from the rank window in the SearchMode::Prefix docs, and note in ARCHITECTURE.md that prefix relevance may read the community-leading primary key backward, which still fences every query to its community. Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: Salman Mohammed <[email protected]>
1 parent 8fc1249 commit d14f256

2 files changed

Lines changed: 14 additions & 7 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -582,12 +582,16 @@ re-authorizes every candidate hit before returning it.
582582
**Key behaviors:**
583583
- `SearchService::new(pool)` wraps a `PgPool`; `search(&SearchQuery)` runs a
584584
parameterized FTS query against the `events.search_tsv` GIN index and returns
585-
`SearchResult` (candidate `SearchHit`s).
585+
`SearchResult` (candidate `SearchHit`s). Prefix-mode relevance (outside
586+
profile search) ranks only the newest 1000 matches, which Postgres may read
587+
from the primary key backward instead of the GIN index.
586588
- `ChannelScope` makes the channel constraint explicit (`Any` /
587589
`ChannelLessOnly` / `Channels` / `ChannelsOrChannelLess`), closing the
588590
ambiguity the old `Option<Vec<Uuid>> + bool` matrix could not express.
589-
- Every query carries `community_id`; the FTS predicate is BitmapAnd-ed with
590-
the community-leading btree filters so a query never crosses tenants.
591+
- Every query carries `community_id`, and every access path leads with it (the
592+
FTS predicate BitmapAnd-ed with community-leading btree filters, or the
593+
`(community_id, created_at, id)` primary key read backward), so a query never
594+
crosses tenants.
591595
- Permission filtering is **caller's responsibility** — `buzz-search` returns
592596
candidate hits; the relay re-authorizes each one (channel membership, `#p`,
593597
owner gates) before delivering it.
@@ -959,7 +963,10 @@ kinds via `CASE WHEN kind IN (1059, 30300, 30622) THEN NULL`, so those rows are
959963
storage-level unsearchable (a `NULL` tsvector never matches `@@`). A GIN index
960964
(`idx_events_search_tsv`) backs the `@@` probe; in multi-community mode the
961965
community-leading btree filters BitmapAnd with the GIN probe so every query is
962-
fenced to its `community_id`.
966+
fenced to its `community_id`. Prefix-mode relevance ranks only the newest 1000
967+
matches; for a common prefix Postgres reads the `(community_id, created_at, id)`
968+
primary key backward and stops there, still fenced by its leading
969+
`community_id`.
963970
964971
---
965972

‎crates/buzz-search/src/query.rs‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -64,9 +64,9 @@ pub enum SearchMode {
6464
/// Intended for bounded typeahead surfaces such as the desktop topbar. The
6565
/// relay still refetches and re-authorizes every hit; this mode changes the
6666
/// candidate tsquery and, for relevance outside profile search, ranks only
67-
/// the newest 1000 matches, not the access boundary. A trailing token that
68-
/// yields a lexeme shorter than three characters returns no hits unless the
69-
/// query is kind:0-only (see `PREFIX_MIN_CHARS`).
67+
/// the newest 1000 matches. It does not change the access boundary. A
68+
/// trailing token that yields a lexeme shorter than three characters
69+
/// returns no hits unless the query is kind:0-only (see `PREFIX_MIN_CHARS`).
7070
Prefix,
7171
}
7272

0 commit comments

Comments
 (0)