[API] Add multi-value test to POST /query and machine/metric filters to /tests

Change the /query endpoint from GET to POST with a JSON body to
eliminate URL length limits when querying many tests with long names.
The test field accepts a list for disjunction queries. Unknown test
names are silently skipped. The schema uses marshmallow's unknown=RAISE
to reject unknown fields (returning 422 instead of the previous 400).

Add optional machine= and metric= query parameters to GET /tests so
clients can discover which tests have actual data for a given machine
and/or metric combination, joining through Sample -> Run with DISTINCT.

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

Author: ldionne

docs/design/v5-api.md

@@ -50,6 +50,7 @@ Tests
 GET    /tests                        — List (cursor-paginated, filterable)
 GET    /tests/{test_name}            — Detail
 Read-only. Tests are created implicitly via run submission.
+Filters: name_contains=, name_prefix=, machine= (only tests with data for this machine), metric= (only tests with non-NULL values for this metric).
 
 Samples
 
@@ -106,12 +107,12 @@ Creating a field change requires: machine (name), test (name), metric (name), ol
 
 Time Series
 
-GET    /query
-  Query params: machine={name}&test={name}&metric={name}&order={order}
-                &after_order={order}&before_order={order}
-                &after_time={iso8601}&before_time={iso8601}&sort={fields}&limit={n}&cursor={c}
-The metric parameter is required; all other query parameters are optional.
-The order parameter filters for an exact order match and cannot be combined with after_order/before_order.
+POST   /query
+  Body (JSON): {metric, machine, test, order, after_order, before_order,
+                after_time, before_time, sort, limit, cursor}
+The metric field is required; all other fields are optional.
+The test field accepts a list of names for disjunction queries.
+The order field filters for an exact order match and cannot be combined with after_order/before_order.
 Returns cursor-paginated time-series data for graphing. Uses field names (not indices) to be self-documenting.
 
 Schema and Fields

docs/design/v5-ui.md

@@ -181,11 +181,11 @@ The primary performance-over-time visualization. Replaces v4's graph page. This
 - **Zoom preservation during progressive loading**: If the user zooms into the chart while data is still loading, the zoom is preserved across incremental updates. The x-axis range is always preserved (it was established by the scaffold or by user zoom). The y-axis range is preserved only when the user has explicitly zoomed; otherwise, it auto-ranges to accommodate new data as it arrives. Double-clicking the chart resets the zoom to the full range as usual.
 - **Legend table**: Below the chart, a table lists traces sorted alphabetically by name (not in a scrollable container — the table is part of the page flow, like the Compare page's table). A message line above the table rows always shows a matching count (e.g., "42 of 150 tests matching"); when the 20-cap is active, the cap warning replaces it. Each row represents one trace (`{test name} - {machine name}`), with a colored marker symbol character (●, ▲, ■, etc. in the trace's color) identifying both the test (by color) and the machine (by shape). The test filter matches on test name only — matching test names show all their machine variants; non-matching names are hidden entirely. Tests that are inactive (manually hidden or beyond the 20-cap) are grayed out in place. Clicking a row toggles the test's visibility on the chart. Double-clicking a row is a shortcut for hiding all other visible tests (equivalent to single-clicking every other test one by one) — it populates `manuallyHidden` with all visible tests except the double-clicked one. Double-clicking the same test again when it is the only visible test restores all tests. Subsequent single-clicks work naturally against the `manuallyHidden` set. Plotly's built-in legend is disabled; the table replaces it. Bidirectional hover highlighting: hovering a table row highlights the corresponding chart trace by emphasizing the entire trace line (thicker line, full opacity) while dimming all other traces via `Plotly.restyle()`; hovering a chart trace highlights the table row.
 - **Active state and 20-cap**: A trace is active (plotted) when its test name matches the text filter and it has not been manually hidden by clicking its row. A default 20-test cap auto-activates the first 20 alphabetical trace names when there is no text filter and no manual toggles. As soon as the user types a filter or manually toggles any row, the cap is permanently disabled for the rest of the page session. Colors are assigned by alphabetical index of all **test names** (not trace names) using a fixed palette, ensuring the same test on different machines shares the same color.
-- **Baselines**: Users can overlay one or more baselines as horizontal dashed lines on the chart. Each baseline is a (suite, machine, order) tuple, allowing cross-suite comparisons. The selector is an expandable panel with cascading dropdowns: Suite (populated from `data-testsuites`) → Machine (populated from the selected suite's machines endpoint) → Order (populated from the selected machine's orders). Added baselines appear as removable chips labeled `{suite}/{machine}/{order} ({tag})`. Baseline data is fetched from the baseline's suite via `GET /api/v5/{suite}/query?machine=...&metric=...&order=...`. Each baseline renders as a horizontal dashed line per test trace, spanning the full chart width, in a distinct color per baseline. The baseline's Y value for each test is computed using the same run aggregation function as the main trace (e.g., median of all runs at that order), so the dashed line aligns exactly with the trace point at that order. Hovering a dashed line shows a tooltip with: the baseline suite, machine, order value, tag (if set), test name, and metric value. Baselines are encoded in the URL query string for shareability (e.g., `&baseline=nts::machine1::abc123&baseline=other_suite::machine2::def456`). Baseline data is fetched asynchronously after the first render, so it does not block initial chart display.
+- **Baselines**: Users can overlay one or more baselines as horizontal dashed lines on the chart. Each baseline is a (suite, machine, order) tuple, allowing cross-suite comparisons. The selector is an expandable panel with cascading dropdowns: Suite (populated from `data-testsuites`) → Machine (populated from the selected suite's machines endpoint) → Order (populated from the selected machine's orders). Added baselines appear as removable chips labeled `{suite}/{machine}/{order} ({tag})`. Baseline data is fetched from the baseline's suite via `POST /api/v5/{suite}/query` with `{machine, metric, order, test}` in the JSON body. Each baseline renders as a horizontal dashed line per test trace, spanning the full chart width, in a distinct color per baseline. The baseline's Y value for each test is computed using the same run aggregation function as the main trace (e.g., median of all runs at that order), so the dashed line aligns exactly with the trace point at that order. Hovering a dashed line shows a tooltip with: the baseline suite, machine, order value, tag (if set), test name, and metric value. Baselines are encoded in the URL query string for shareability (e.g., `&baseline=nts::machine1::abc123&baseline=other_suite::machine2::def456`). Baseline data is fetched asynchronously after the first render, so it does not block initial chart display.
 - **Concurrent background fetches**: Each machine×metric fetch uses its own AbortController, so navigating away or removing a machine cancels its in-flight requests cleanly without affecting other machines' fetches.
 - **Hover** a data point: tooltip showing test name, machine name, order value, aggregated metric value, run count. Hover distance is reduced (`hoverdistance: 5`, less sticky tooltips) so the tooltip only appears when the cursor is close to a data point. When hovering over an aggregated point that represents multiple runs, the individual pre-aggregation values are shown as a scatter of markers at the same x-position, in the same trace color but faded (opacity 0.3). This scatter is computed lazily via a callback and displayed as a temporary Plotly trace that is added on hover and removed on unhover.
 - **"No data to plot" annotation**: When no traces match the current filter/settings, the chart displays a Plotly annotation overlay ("No data to plot") centered on the chart area, preserving the x-axis scaffold so the user can see the order range.
-- API: `GET query?machine=...&metric=...&sort=-order&limit=10000` (one fetch pipeline per machine, newest-first with cursor pagination — returns data for all tests, filtered client-side), `GET machines/{name}/runs?sort=order` (x-axis scaffold, per machine), `GET orders` (tags for baseline suggestions), `GET machines` (machine combobox), `GET test-suites/{ts}` (fields/metrics)
+- API: `POST query` with JSON body `{machine, metric, test, sort, limit, cursor}` (one fetch pipeline per machine, targeted to discovered tests via multi-value `test`), `GET tests?machine=...&metric=...&name_contains=...` (test name discovery), `GET machines/{name}/runs?sort=order` (x-axis scaffold, per machine), `GET orders` (tags for baseline suggestions), `GET machines` (machine combobox), `GET test-suites/{ts}` (fields/metrics)
 - **URL state**: `?suite={ts}&machine={name}&machine={name2}&metric={name}&test_filter={text}&run_agg={fn}&sample_agg={fn}&baseline={suite}::{machine}::{order}&baseline={suite2}::{machine2}::{order2}` — the `machine` parameter is repeated for each selected machine; the `baseline` parameter is repeated for each baseline.
 - **Links out**: Compare
 

docs/v5-api-implementation-plan.md

@@ -436,7 +436,10 @@ GET    /api/v5/{ts}/tests/{test_name}      — Detail
 **Key design decisions:**
 - Read-only. Tests created implicitly via run submission.
 - Use `<path:test_name>` converter for test names with slashes
-- Filter: `name_contains=`, `name_prefix=`
+- Filter: `name_contains=`, `name_prefix=`, `machine=`, `metric=`
+- `machine=` and `metric=` join through Sample → Run to return only tests
+  that have actual data for the given machine and/or metric. The query uses
+  `DISTINCT` to deduplicate.
 - Escape `%` and `_` in user-supplied LIKE patterns to prevent pattern injection
 - Auth: read only.
 
@@ -567,14 +570,20 @@ DELETE /api/v5/{ts}/field-changes/{uuid}/ignore    — Un-ignore
 
 **Endpoint:**
 ```
-GET /api/v5/{ts}/series?machine={name}&test={name}&field={name}&after={order}&before={order}&limit={n}
+POST /api/v5/{ts}/query
+Body (JSON): {metric, machine, test, order, after_order, before_order,
+              after_time, before_time, sort, limit, cursor}
 ```
 
 **Key design decisions:**
-- `machine`, `test`, `field` are all REQUIRED (by name, not ID)
+- Uses POST with a JSON body (not GET with query params) to avoid URL length
+  limits when querying many tests with long names.
+- `metric` is REQUIRED (by name, not ID). All other fields are optional.
+- `test` is a list of test names for disjunction queries.
+  Unknown test names are silently skipped (no 404).
 - Field name → Sample column resolution via `ts.sample_fields` name→column mapping
 - Core query: `SELECT field.column, order.*, run.* FROM Sample JOIN Run JOIN Order
-  WHERE machine_id=X AND test_id=Y AND field IS NOT NULL`
+  WHERE machine_id=X AND test_id IN (...) AND field IS NOT NULL`
 - Filter out failing tests if the field has a status_field
 - Order filtering: `order` for exact match (=), `after_order`/`before_order` for
   exclusive range (>/< on Order.id). `order` cannot be combined with range params.

lnt/server/api/v5/endpoints/query.py

@@ -1,13 +1,12 @@
 """Query endpoint for the v5 API.
 
-GET /api/v5/{ts}/query?metric={name}&machine={name}&test={name}
-                      &order={order}
-                      &after_order={order}&before_order={order}
-                      &after_time={iso8601}&before_time={iso8601}
-                      &sort={fields}&limit={n}&cursor={c}
-
-Returns cursor-paginated data points. The metric parameter is required;
-all other filter parameters are optional.
+POST /api/v5/{ts}/query
+  Body (JSON): {metric, machine, test, order, after_order, before_order,
+                after_time, before_time, sort, limit, cursor}
+
+Returns cursor-paginated data points. The metric field is required;
+all other fields are optional. The test field accepts a list of names
+for disjunction queries.
 """
 
 import base64
@@ -20,7 +19,7 @@
 from lnt.testing import PASS
 
 from ..auth import require_scope
-from ..errors import abort_with_error, reject_unknown_params
+from ..errors import abort_with_error
 from ..helpers import parse_datetime, resolve_metric
 from ..pagination import make_paginated_response
 from ..schemas.query import QueryEndpointQuerySchema, QueryResponseSchema
@@ -36,13 +35,6 @@
 _DEFAULT_LIMIT = 100
 _MAX_LIMIT = 10000
 
-# Valid query parameter names for the /query endpoint.
-_VALID_QUERY_PARAMS = {
-    'machine', 'test', 'metric', 'order',
-    'after_order', 'before_order', 'after_time', 'before_time',
-    'sort', 'limit', 'cursor',
-}
-
 # Allowed sort field names and the columns they map to.
 # The actual column references are resolved at query time since the
 # model classes are dynamic per test suite.
@@ -248,11 +240,13 @@ def _resolve_order(session, ts, order_value):
     return order, None
 
 
-def _query_for_field(session, ts, sample_field, machine, test,
+def _query_for_field(session, ts, sample_field, machine, test_ids,
                      sort_spec, cursor_values, order, after_order,
                      before_order, after_time, before_time, limit):
     """Build and execute a query for a single sample field.
 
+    *test_ids* is a list of test IDs to filter by, or None for no filter.
+
     Returns a list of dicts ready for serialization, plus a boolean
     indicating whether there are more results.
     """
@@ -279,8 +273,11 @@ def _query_for_field(session, ts, sample_field, machine, test,
     # Apply optional filters.
     if machine is not None:
         q = q.filter(ts.Run.machine_id == machine.id)
-    if test is not None:
-        q = q.filter(ts.Sample.test_id == test.id)
+    if test_ids is not None:
+        if len(test_ids) == 1:
+            q = q.filter(ts.Sample.test_id == test_ids[0])
+        else:
+            q = q.filter(ts.Sample.test_id.in_(test_ids))
 
     # Apply exact order filter.
     if order is not None:
@@ -347,28 +344,23 @@ class QueryView(MethodView):
     """Query data points."""
 
     @require_scope('read')
-    @blp.arguments(QueryEndpointQuerySchema, location="query")
+    @blp.arguments(QueryEndpointQuerySchema, location="json")
     @blp.response(200, QueryResponseSchema)
-    def get(self, query_args, testsuite):
+    def post(self, query_args, testsuite):
         """Query data points.
 
-        Returns cursor-paginated data points. The metric parameter is
-        required; all other filter parameters are optional -- omit any
-        to get data across all values of that dimension.
+        Returns cursor-paginated data points. The metric field is
+        required; all other fields are optional -- omit any to get
+        data across all values of that dimension.
         """
-        # Reject unknown query parameters early so that typos like
-        # ``machine_name=`` or ``metric_name=`` don't silently return
-        # unfiltered data.
-        reject_unknown_params(_VALID_QUERY_PARAMS)
-
         ts = g.ts
         session = g.db_session
 
         # ------------------------------------------------------------------
         # Parse filter parameters
         # ------------------------------------------------------------------
         machine_name = query_args.get('machine')
-        test_name = query_args.get('test')
+        test_names = query_args.get('test')
         field_name = query_args['metric']
 
         # Resolve entities when provided.
@@ -378,11 +370,19 @@ def get(self, query_args, testsuite):
             if err:
                 abort_with_error(status, err)
 
-        test = None
-        if test_name:
-            test, err = _resolve_test(session, ts, test_name)
-            if err:
-                abort_with_error(404, err)
+        test_ids = None
+        if test_names:
+            test_ids = []
+            for tn in test_names:
+                test, err = _resolve_test(session, ts, tn)
+                if err:
+                    # Silently skip unknown test names — return no data
+                    # for them rather than 404-ing the entire request.
+                    continue
+                test_ids.append(test.id)
+            if not test_ids:
+                # All requested tests are unknown — return empty response.
+                return jsonify(make_paginated_response([], None))
 
         field = resolve_metric(ts, field_name)
 
@@ -461,7 +461,7 @@ def get(self, query_args, testsuite):
         # Execute query
         # ------------------------------------------------------------------
         items, has_next = _query_for_field(
-            session, ts, field, machine, test,
+            session, ts, field, machine, test_ids,
             sort_spec, cursor_values, order, after_order, before_order,
             after_time, before_time, limit)
 

lnt/server/api/v5/endpoints/tests.py

@@ -11,7 +11,7 @@
 from ..auth import require_scope
 from ..errors import reject_unknown_params
 from ..etag import add_etag_to_response
-from ..helpers import escape_like, lookup_test
+from ..helpers import escape_like, lookup_machine, lookup_test, resolve_metric
 from ..pagination import (
     cursor_paginate,
     make_paginated_response,
@@ -44,12 +44,31 @@ class TestList(MethodView):
     @blp.response(200, PaginatedTestResponseSchema)
     def get(self, query_args, testsuite):
         """List tests (cursor-paginated, filterable)."""
-        reject_unknown_params({'name_contains', 'name_prefix', 'cursor', 'limit'})
+        reject_unknown_params({
+            'name_contains', 'name_prefix', 'machine', 'metric',
+            'cursor', 'limit',
+        })
         ts = g.ts
         session = g.db_session
 
         query = session.query(ts.Test)
 
+        # Machine / metric filters require joining through Sample
+        # (and additionally through Run when machine= is specified).
+        machine_name = query_args.get('machine')
+        metric_name = query_args.get('metric')
+        if machine_name or metric_name:
+            query = query.join(ts.Sample, ts.Sample.test_id == ts.Test.id)
+        if machine_name:
+            machine = lookup_machine(session, ts, machine_name)
+            query = query.join(ts.Run).filter(
+                ts.Run.machine_id == machine.id)
+        if metric_name:
+            field = resolve_metric(ts, metric_name)
+            query = query.filter(field.column.isnot(None))
+        if machine_name or metric_name:
+            query = query.distinct()
+
         # Apply filters
         name_contains = query_args.get('name_contains')
         if name_contains:

lnt/server/api/v5/schemas/query.py

@@ -3,7 +3,7 @@
 import marshmallow as ma
 
 from . import BaseSchema
-from .common import BaseQuerySchema, CursorSchema
+from .common import CursorSchema
 
 
 class QueryDataPointSchema(BaseSchema):
@@ -44,7 +44,7 @@ class QueryDataPointSchema(BaseSchema):
 
 
 class QueryResponseSchema(BaseSchema):
-    """Response schema for GET /api/v5/{ts}/query."""
+    """Response schema for POST /api/v5/{ts}/query."""
     items = ma.fields.List(
         ma.fields.Nested(QueryDataPointSchema),
         required=True,
@@ -54,18 +54,26 @@ class QueryResponseSchema(BaseSchema):
 
 
 # ---------------------------------------------------------------------------
-# Query parameter schemas
+# Request body schema
 # ---------------------------------------------------------------------------
 
-class QueryEndpointQuerySchema(BaseQuerySchema):
-    """Query parameters for GET /query."""
+class QueryEndpointQuerySchema(BaseSchema):
+    """JSON body for POST /query."""
+
+    class Meta:
+        ordered = True
+        unknown = ma.RAISE
+
     machine = ma.fields.String(
         load_default=None,
         metadata={'description': 'Filter by machine name'},
     )
-    test = ma.fields.String(
+    test = ma.fields.List(
+        ma.fields.String(),
         load_default=None,
-        metadata={'description': 'Filter by test name'},
+        metadata={
+            'description': 'Filter by test name(s) (disjunction).',
+        },
     )
     metric = ma.fields.String(
         required=True,