Your filter API gains an optional parameter every quarter - how do you decide between one composed builder, named statements, or a search service?

## Decide from traffic, not from the API surface The number of optional filters an endpoint exposes tells you almost nothing. What matters is the **distribution of combinations actually requested**. Record a normalised signature per call - the sorted list of supplied filter tokens plus the sort token - and rank it. Two very different worlds hide behind the same API: - **Concentrated.** Three or four signatures carry the overwhelming majority of calls, and the tail is used a few times a week by internal users. - **Flat.** Hundreds of signatures are each used a little, typically because a UI exposes free-form facets. A concentrated distribution can be served by pinning a few statements. A flat one cannot, and no amount of index work will make it so. ## Three shapes of answer | Approach | Fits when | Principal costs | |---|---|---| | One composed builder | Filters are few and orthogonal; every combination is served acceptably by existing access paths | Unreviewed shapes; worst member unbounded; index coverage per combination is invisible | | Named statements for the head, builder for the tail | A handful of signatures dominate; each wants its own shape and index | Two code paths to keep semantically identical; drift between them is a real defect class | | A dedicated search store | Text or facet filters; no single selective column; the shape family exceeds what indexing can serve | A second copy of the data, its lag, reindexing, and a read-your-writes story to design | A fourth answer is sometimes the right one and is usually forgotten: **restrict the contract**. Replacing a free-form filter API with a small set of named searches - each with its own statement, index and test - removes the combinatorial problem instead of managing it. That is a product conversation, which is precisely why it needs a lead to have it. ## What each one really costs **The composed builder** is cheapest to extend and most expensive to reason about. Its failure mode is not a bug on day one; it is that after eight quarters nobody can say which combination is slow, which index serves which shape, or whether a given combination has ever run. Its bounded form requires a guard - at minimum, one selective filter is mandatory, list filters are length-capped, and page size is clamped. **Pinned statements** buy reviewability for the traffic that matters, and cost you duplication. The two paths must agree not just on rows but on the pager's total, the ordering and the tri-state meaning of every field. Contract tests that run the same request through both paths and compare are the cheapest insurance; without them, drift is discovered by a user. **A separate search store** solves the shape problem by changing the access model, and imports a distributed-systems problem in exchange: the copy is behind by some amount, so a user who has just edited a record may not find it; deletions must propagate or you serve tombstones; a reindex is an operation with a runtime and a rollback. None of that is a reason to avoid it - it is a reason to price it, and to insist the team can state the freshness contract out loud. ## Governance: what one more filter commits you to The recurring failure is that adding a filter looks like a one-line change. Make the true cost visible by requiring, for every new optional filter: 1. **The access path.** Which index or path serves the new combinations, or the explicit statement that the filter is only ever used together with an already-selective one. 2. **The expected selectivity.** A filter that removes 2% of rows is a filter that will never be worth planning for on its own, and knowing that up front changes the design. 3. **The grain declaration.** Whether the filter reaches through a collection and therefore changes the row grain, and which form it uses. 4. **A retirement trigger.** If the signature log shows the filter unused after a quarter, it goes. Removing an unused filter is cheaper than every future decision made in its presence. ## How the decision usually lands Most mature systems end up **hybrid, deliberately**: a builder for the long tail, two or three pinned statements for the dominant signatures, a guard that refuses unbounded requests, and a search store only where the workload is genuinely text- or facet-shaped. The signal to move a signature from the builder to a pinned statement is empirical - it appears in the top few by volume, or its latency distribution is the one users complain about. What separates a good answer here from a plausible one is refusing to make the choice from the API's appearance. The API's appearance is what the last four quarters of feature requests happened to produce; the traffic distribution is what the system is actually being asked to do.