golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(12-01): report the search engine's found count and field weights

Browse Source 
- optional beachcomber.PageSearcher returns a page of candidate ids plus
  the engine's found count; beachcomber.SearchPage falls back to
  SearchIDs for engines without it, so Engine is unchanged
- Query.QueryByWeights is sent to Typesense as query_by_weights; a
  mismatched weight list or a page above typesense.MaxPerPage (250) is
  refused before any request
This commit is contained in:
Jakub Zych
2026-10-02 11:37:01 +02:00
parent e06e0cc8bf
commit 3ae49bb6f4
7 changed files with 253 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/services/search.md
View File

@@ -131,6 +131,10 @@ An empty result is an empty list, never an error.
> [!WARNING]
> Never return rows, or even counts, straight from search IDs. A stale index would otherwise show a draft, a deleted record or another user's data.
A paginated endpoint also needs to know how many documents matched. An engine that can tell implements the optional `beachcomber.PageSearcher` interface; call it through `beachcomber.SearchPage`, which returns a `beachcomber.SearchResult` with the page of `IDs` and `Found`, the number of documents the engine matched. For an engine without `PageSearcher` the helper calls `SearchIDs` and sets `Found` to the number of IDs returned, so code written against it works with every engine. `Found` is a candidate count like the IDs: it includes stale and foreign documents. Use it to decide how many IDs to fetch, then recount the total in SQL with the same conditions as the rows, as Laravel Scout does when a query callback is set.
`beachcomber.Query.QueryByWeights` ranks the fields of `QueryBy`, one weight per field in the same order, as Scout's `query_by_weights` option does.
## Typesense
The Typesense engine follows the Scout Typesense wire contract, so indexes built by a WinterCMS application can be searched by the port:
@@ -180,4 +184,4 @@ fmt.Println(typesense.New(typesense.Config{}).Configured())
// false
```
Each request times out after `search.typesense.connection_timeout_seconds` (2 seconds by default). A failed answer is a `typesense.StatusError` with the method, path and status, never the answer body.
The Typesense engine implements `beachcomber.PageSearcher` on the same request, adding the answer's `found` count, and sends `query_by_weights` when the query has weights. A page is at most `typesense.MaxPerPage` (250) documents, Typesense's own limit: a larger `PerPage` is an error, so fetch more IDs page by page. Each request times out after `search.typesense.connection_timeout_seconds` (2 seconds by default). A failed answer is a `typesense.StatusError` with the method, path and status, never the answer body.