Summary

Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups

Review Request #15052 — Created May 13, 2026 and updated May 15, 2026, 3:38 p.m.

Information

Owner

dan.casares

Repository

Review Board

Branch

release-8.x

Bugs

Depends On

15051

Blocks

15054, 15053

Reviewers

Groups

reviewboard

People

Description

Adds the core faceted search engine, the reviewboard/search/facets/ package,
along with benchmark tooling for performance validation.

Key components:
- DisjointFacetEngine (aggregations.py) builds and executes a single
Elasticsearch msearch body per request containing: a paginated results
query, one aggregation sub-query per faceted=True FilterSpec (each
excluding its own filter clause so bucket counts remain accurate when the
filter is active — the disjoint property), and one option-count query per
compound filter choice.
- FilterSpec / FilterBuilder (schema.py, builder.py) provide a
declarative schema for filter dimensions and translate active filter values
into Elasticsearch bool.filter clauses. Compound filters (ship-it, issues,
reviews, file attachments) use custom build_fn callables.
- FacetCache (cache.py) caches aggregation results per group, query, and
filter state for the lifetime of a request.
- FacetedSearchEngine (engine.py) orchestrates searches across
ReviewRequestSearchGroup, UserSearchGroup, and ReviewGroupSearchGroup.
For the active group it runs a full search with aggregations; for inactive
groups it runs a count-only query so sidebar tab totals are accurate.
- ReviewRequestSearchGroup additionally handles the Contents filter, which
restricts the text query to specific ES fields and optionally runs a parallel
query against comment indexes to surface review requests with matching
comments.
- Also adds populate_bench_data management command and bench_manager.py for
populating and benchmarking persistent datasets at 1k, 10k, 100k, and 1M
scale across Postgres, MySQL, and MariaDB.

Testing Done

Verified that DisjointFacetEngine builds the correct msearch body structure,
enforces the disjoint property on aggregation sub-queries, and produces exactly
one msearch call per search regardless of how many filters are active. Verified
that FilterBuilder generates correct Elasticsearch clauses for each filter
type and that the permission filter is always injected. Verified that
FacetedSearchEngine routes full searches to the active group and count-only
queries to inactive groups.

Performance benchmarks were run at 10k, 100k, and 1M review requests on
Postgres, MySQL, and MariaDB. A 6-filter faceted search against a 1M-document
index completes in 4.7ms with latency remaining flat across all scales. Full
results are in the attached benchmark report.

Commits

Summary	ID	Author
Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	9d6264ed7f45b8ba2d3f6c134eee21960a005a21	DanielCasaresIglesias

Issues

Description	From	Last Updated
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
'django.core.management.base.CommandError' imported but unused Column: 1 Error code: F401	reviewbot	May 15, 2026, 3:22 p.m.
missing whitespace after ':' Column: 23 Error code: E231	reviewbot	May 15, 2026, 3:22 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before keyword Column: 35 Error code: E272	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before keyword Column: 33 Error code: E272	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before keyword Column: 34 Error code: E272	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before keyword Column: 33 Error code: E272	reviewbot	May 15, 2026, 3:22 p.m.
multiple statements on one line (def) Column: 5 Error code: E704	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before keyword Column: 34 Error code: E272	reviewbot	May 15, 2026, 3:22 p.m.
line too long (83 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
f-string is missing placeholders Column: 32 Error code: F541	reviewbot	May 15, 2026, 3:22 p.m.
f-string is missing placeholders Column: 14 Error code: F541	reviewbot	May 15, 2026, 3:22 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:22 p.m.
f-string is missing placeholders Column: 10 Error code: F541	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before operator Column: 27 Error code: E221	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before operator Column: 28 Error code: E221	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before operator Column: 26 Error code: E221	reviewbot	May 15, 2026, 3:22 p.m.
multiple spaces before operator Column: 28 Error code: E221	reviewbot	May 15, 2026, 3:22 p.m.
f-string is missing placeholders Column: 13 Error code: F541	reviewbot	May 15, 2026, 3:22 p.m.
no newline at end of file Column: 32 Error code: W292	reviewbot	May 15, 2026, 3:22 p.m.
'time' imported but unused Column: 1 Error code: F401	reviewbot	May 15, 2026, 3:22 p.m.
expected 1 blank line, found 0 Column: 5 Error code: E301	reviewbot	May 15, 2026, 3:34 p.m.
expected 1 blank line, found 0 Column: 5 Error code: E301	reviewbot	May 15, 2026, 3:34 p.m.
expected 1 blank line, found 0 Column: 5 Error code: E301	reviewbot	May 15, 2026, 3:34 p.m.
expected 1 blank line, found 0 Column: 5 Error code: E301	reviewbot	May 15, 2026, 3:34 p.m.
expected 1 blank line, found 0 Column: 5 Error code: E301	reviewbot	May 15, 2026, 3:34 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
f-string is missing placeholders Column: 16 Error code: F541	reviewbot	May 15, 2026, 3:34 p.m.
'datetime.timezone' imported but unused Column: 1 Error code: F401	reviewbot	May 15, 2026, 3:34 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
continuation line over-indented for visual indent Column: 47 Error code: E127	reviewbot	May 15, 2026, 3:34 p.m.
continuation line over-indented for visual indent Column: 47 Error code: E127	reviewbot	May 15, 2026, 3:34 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (82 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
'django.db.models' imported but unused Column: 1 Error code: F401	reviewbot	May 15, 2026, 3:34 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (82 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
'reviewboard.search.facets.cache.FacetCache' imported but unused Column: 1 Error code: F401	reviewbot	May 15, 2026, 3:34 p.m.
line too long (83 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
line too long (82 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:34 p.m.
blank line contains whitespace Column: 1 Error code: W293	reviewbot	May 15, 2026, 3:38 p.m.
blank line contains whitespace Column: 1 Error code: W293	reviewbot	May 15, 2026, 3:38 p.m.
blank line contains whitespace Column: 1 Error code: W293	reviewbot	May 15, 2026, 3:38 p.m.
blank line contains whitespace Column: 1 Error code: W293	reviewbot	May 15, 2026, 3:38 p.m.
blank line contains whitespace Column: 1 Error code: W293	reviewbot	May 15, 2026, 3:38 p.m.
line too long (81 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:38 p.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	May 15, 2026, 3:38 p.m.

flake8 failed.

JSHint passed.

flake8

```
Warning: Showing 30 of 49 failures.
```
reviewboard/management/commands/populate_bench_data.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/management/commands/populate_bench_data.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/management/commands/populate_bench_data.py (Diff revision 1)
The issue has been dropped. Show all issues
```
'django.core.management.base.CommandError' imported but unused

Column: 1
Error code: F401
```
reviewboard/management/commands/populate_bench_data.py (Diff revision 1)
The issue has been dropped. Show all issues
```
missing whitespace after ':'

Column: 23
Error code: E231
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before keyword

Column: 35
Error code: E272
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before keyword

Column: 33
Error code: E272
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before keyword

Column: 34
Error code: E272
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before keyword

Column: 33
Error code: E272
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple statements on one line (def)

Column: 5
Error code: E704
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before keyword

Column: 34
Error code: E272
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (83 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
f-string is missing placeholders

Column: 32
Error code: F541
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
f-string is missing placeholders

Column: 14
Error code: F541
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
f-string is missing placeholders

Column: 10
Error code: F541
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before operator

Column: 27
Error code: E221
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before operator

Column: 28
Error code: E221
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before operator

Column: 26
Error code: E221
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
multiple spaces before operator

Column: 28
Error code: E221
```
reviewboard/scripts/bench_manager.py (Diff revision 1)
The issue has been dropped. Show all issues
```
f-string is missing placeholders

Column: 13
Error code: F541
```
reviewboard/search/facets/groups/users.py (Diff revision 1)
The issue has been dropped. Show all issues
```
no newline at end of file

Column: 32
Error code: W292
```
reviewboard/search/tests/bench_logging.py (Diff revision 1)
The issue has been dropped. Show all issues
```
'time' imported but unused

Column: 1
Error code: F401
```

Commits:

	Summary	ID	Author
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	5374b963609df18752e686d913433b2e1f1d8505	DanielCasaresIglesias
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	442abf12ff7610466b2e5f13584e7eaff19619cf	DanielCasaresIglesias

Diff:

Revision 2 (+16382 -2)

Show changes

	setup.cfg
	reviewboard/management/__init__.py
	reviewboard/management/commands/__init__.py
	reviewboard/management/commands/populate_bench_data.py
	reviewboard/scripts/__init__.py
	reviewboard/scripts/bench_manager.py
	reviewboard/search/facets/__init__.py
	reviewboard/search/facets/aggregations.py
	19 more

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

reviewboard/scripts/bench_manager.py (Diff revision 2)
The issue has been dropped. Show all issues
```
expected 1 blank line, found 0

Column: 5
Error code: E301
```
reviewboard/scripts/bench_manager.py (Diff revision 2)
The issue has been dropped. Show all issues
```
expected 1 blank line, found 0

Column: 5
Error code: E301
```
reviewboard/scripts/bench_manager.py (Diff revision 2)
The issue has been dropped. Show all issues
```
expected 1 blank line, found 0

Column: 5
Error code: E301
```
reviewboard/scripts/bench_manager.py (Diff revision 2)
The issue has been dropped. Show all issues
```
expected 1 blank line, found 0

Column: 5
Error code: E301
```
reviewboard/scripts/bench_manager.py (Diff revision 2)
The issue has been dropped. Show all issues
```
expected 1 blank line, found 0

Column: 5
Error code: E301
```
reviewboard/search/tests/bench_logging.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/bench_logging.py (Diff revision 2)
The issue has been dropped. Show all issues
```
f-string is missing placeholders

Column: 16
Error code: F541
```
reviewboard/search/tests/test_faceted_aggregations.py (Diff revision 2)
The issue has been dropped. Show all issues
```
'datetime.timezone' imported but unused

Column: 1
Error code: F401
```
reviewboard/search/tests/test_faceted_aggregations.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_aggregations.py (Diff revision 2)
The issue has been dropped. Show all issues
```
continuation line over-indented for visual indent

Column: 47
Error code: E127
```
reviewboard/search/tests/test_faceted_aggregations.py (Diff revision 2)
The issue has been dropped. Show all issues
```
continuation line over-indented for visual indent

Column: 47
Error code: E127
```
reviewboard/search/tests/test_faceted_aggregations.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_benchmarks.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (82 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_benchmarks.py (Diff revision 2)
The issue has been dropped. Show all issues
```
'django.db.models' imported but unused

Column: 1
Error code: F401
```
reviewboard/search/tests/test_faceted_benchmarks.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_benchmarks.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (82 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_benchmarks.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 2)
The issue has been dropped. Show all issues
```
'reviewboard.search.facets.cache.FacetCache' imported but unused

Column: 1
Error code: F401
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (83 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 2)
The issue has been dropped. Show all issues
```
line too long (82 > 79 characters)

Column: 80
Error code: E501
```

Commits:

	Summary	ID	Author
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	442abf12ff7610466b2e5f13584e7eaff19619cf	DanielCasaresIglesias
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	f889b02773719e8e15e86308f86bffe086c342c8	DanielCasaresIglesias

Diff:

Revision 3 (+16394 -2)

Show changes

	setup.cfg
	reviewboard/management/__init__.py
	reviewboard/management/commands/__init__.py
	reviewboard/management/commands/populate_bench_data.py
	reviewboard/scripts/__init__.py
	reviewboard/scripts/bench_manager.py
	reviewboard/search/facets/__init__.py
	reviewboard/search/facets/aggregations.py
	19 more

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

reviewboard/scripts/bench_manager.py (Diff revision 3)
The issue has been dropped. Show all issues
```
blank line contains whitespace

Column: 1
Error code: W293
```
reviewboard/scripts/bench_manager.py (Diff revision 3)
The issue has been dropped. Show all issues
```
blank line contains whitespace

Column: 1
Error code: W293
```
reviewboard/scripts/bench_manager.py (Diff revision 3)
The issue has been dropped. Show all issues
```
blank line contains whitespace

Column: 1
Error code: W293
```
reviewboard/scripts/bench_manager.py (Diff revision 3)
The issue has been dropped. Show all issues
```
blank line contains whitespace

Column: 1
Error code: W293
```
reviewboard/scripts/bench_manager.py (Diff revision 3)
The issue has been dropped. Show all issues
```
blank line contains whitespace

Column: 1
Error code: W293
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 3)
The issue has been dropped. Show all issues
```
line too long (81 > 79 characters)

Column: 80
Error code: E501
```
reviewboard/search/tests/test_faceted_engine.py (Diff revision 3)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```

Commits:

	Summary	ID	Author
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	f889b02773719e8e15e86308f86bffe086c342c8	DanielCasaresIglesias
	Search: Add DisjointFacetEngine, FilterBuilder, FacetCache, and search groups	9d6264ed7f45b8ba2d3f6c134eee21960a005a21	DanielCasaresIglesias

Diff:

Revision 4 (+16394 -2)

Show changes

	setup.cfg
	reviewboard/management/__init__.py
	reviewboard/management/commands/__init__.py
	reviewboard/management/commands/populate_bench_data.py
	reviewboard/scripts/__init__.py
	reviewboard/scripts/bench_manager.py
	reviewboard/search/facets/__init__.py
	reviewboard/search/facets/aggregations.py
	19 more

Checks run (2 succeeded)

flake8 passed.

JSHint passed.