doc comment

Cargo.lock

@@ -5414,6 +5414,7 @@ dependencies = [
  "bytes",
  "censor",
  "chrono",
+ "chumsky",
  "clap 4.5.48",
  "clickhouse",
  "color-eyre",

Cargo.toml

@@ -56,6 +56,7 @@ bytemuck = "1.24.0"
 bytes = "1.10.1"
 censor = "0.3.0"
 chardetng = "0.1.17"
+chumsky = "0.9.3"
 chrono = "0.4.42"
 cidre = { version = "0.15.0", default-features = false, features = [
   "macos_15_0"

apps/labrinth/src/search/backend/typesense/mod.rs

@@ -103,11 +103,18 @@
 //! is faster than two. It's even faster if you search for more facets like
 //! category, game version, loader, and environment.
 //!
-//! Filters are parsed into a backend-independent AST before they reach this
+//! ### Filter AST
-//! module. Its normalization pass compacts Cartesian products such as many
+//!
-//! game versions combined with many loaders into `IN` predicates. The
+//! When a caller provides a search filter, we first parse it into a
-//! Typesense filter planner then puts maximal version-only expressions into a
+//! search-backend-independent AST; then normalize the AST to compact it down
-//! single join, avoiding repeated joins and deeply expanded boolean trees.
+//! to make it easier for Typesense to manage; check that it's not too big;
+//! and finally submit it to Typesense. Parsing into our own AST first has
+//! the following benefits:
+//! - we can make our search filter syntax search-backend-independent
+//! - we can normalize the AST to compact down e.g. Cartesian products into `IN`
+//!   predicates, to avoid repeated joins and deep boolean trees
+//! - we can check that the filter isn't too complex before submitting to
+//!   Typesense
 //!
 //! ### Whole-field tokenization
 //!