[lewisjared]

Moves the backend onto climate-ref's results readers and the climate_ref.query package, so every filter states which version, retraction and latest-execution scope it reads.

This builds against climate-ref 0.20.0 from PyPI, which ships the query package (Climate-REF/climate-ref#1011) and the reader fixes in Climate-REF/climate-ref#1018. The fixture database is migrated to match. With 0.20.0, scalar value pages with outlier detection take about 590 ms against 230 ms before at a tenth of production scale, because detection now runs in SQL.

Breaking API changes, with the frontend and generated client updated to match:

• mip_era accepts only CMIP6 or CMIP7, so a lowercase, unknown or empty value is now a 422. On the diagnostics, executions and values routes, an era now keeps the groups that draw on that era or on no model data (such as observation-only groups), from the source types climate-ref records per group, instead of the execution's datasets. /models/ and /models/{source_id} still pick the era from the latest execution's datasets.
• Diagnostics and /executions/statistics report groups (total, successful, failed, running, not started, dirty) in place of the separate count fields. groups_by_mip_era, with a groups object per era, replaces execution_groups_by_mip_era.
• Diagnostics no longer report the per-attempt execution_count and successful_execution_count.
• Group counts, diagnostic /values, the value flags and /executions/ now leave out retracted executions. On main, diagnostic /values and the group counts included them.
• /diagnostics/{provider}/{diagnostic}/execution_groups lists only the promoted version, and now fills total_count.
• /executions/{group}/values now returns the values of a group from a superseded diagnostic version, instead of nothing. The execution page now enables its value tabs from the group's own values, so these groups can open them.
• source_id filters and /datasets/{id}/executions look at each group's latest execution only, where before any execution in the group matched. The value flags are the exception: with_values still matches source_id against every execution. This only differs when a retry changes a group's model, which its selectors normally prevent.
• Resource usage on the dashboard and diagnostic pages covers only the promoted version of each diagnostic. Retracted executions still count.
• /executions/ returns a 422 for an unknown failure_reason (before an empty list) and for a negative limit or offset.
• /datasets/ is now ordered by slug.
• Removes /diagnostics/facets and /diagnostics/{provider}/{diagnostic}/executions, which the frontend never called.

make perf-compare BASE=origin/feat/query-perf (#145, before it merged) at a tenth of production scale showed every endpoint the same or faster. For example diagnostics.values.scalar went from 3283 ms to 256 ms, executions.statistics from 512 ms to 22 ms and diagnostics.list from 221 ms to 44 ms. This can't run against main yet, because main's climate-ref 0.19 has no synthetic database generator. A head-only run after the rebase gives similar numbers (295 ms, 19 ms and 34 ms). The group counts read every row of execution_group, which the perf suite now allows on the three pages that count every group. That lookup finds each group's latest execution with a sorted subquery per group, which is worth improving upstream.

Adds /diagnostics/{provider}/{diagnostic}/values/facets and /executions/{group}/values/facets, which return the facets /values returns for the same filters. The values tables now fetch facets once per filter and pages with with_facets=false, so a series page drops from 63 ms to 14 ms. The explorer filter controls used to fetch facets through /values?limit=1, which ran outlier detection over every value, and now use the facets endpoint (85 ms against 269 ms). /values still returns facets by default.

The commits in the middle of the branch were written against unreleased climate-ref builds, so only the tip type-checks and passes the tests against 0.20.0.

Summary by CodeRabbit

• New Features

  • Added separate metric-value facet endpoints for diagnostics and executions. Values requests can skip facet loading with with_facets=false.
  • Execution statistics and diagnostic summaries now show group totals by status, with breakdowns by MIP era.
  • Added filters for MIP era, source model and execution failure reason. Era results can include groups without model data.
  • Value tabs are now available based on whether the selected execution group has values.

• Improvements

  • Diagnostic, execution and metric-value endpoints are faster, with facets loaded separately from paged values.
  • Results apply updated rules for retracted executions and promoted diagnostic versions.

• Breaking Changes

  • Removed the diagnostic executions list and global facets endpoints. Dataset ordering, execution statistics and filter validation have changed.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 51 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: bd591af1-4e50-44af-be42-4d85ec68c4a9

Commits

Reviewing files that changed from the base of the PR and between aad8206 and 1755cb2.

Files ignored due to path filters: 2

• backend/tests/test-data/tests.integration.test_cmip7_aft/test_solve_cmip7_aft/db/climate_ref.db is excluded by !**/*.db
• backend/uv.lock is excluded by !**/*.lock

Files selected for processing: 60

• backend/pyproject.toml
• backend/src/ref_backend/api/routes/datasets.py
• backend/src/ref_backend/api/routes/diagnostics.py
• backend/src/ref_backend/api/routes/executions.py
• backend/src/ref_backend/api/routes/models.py
• backend/src/ref_backend/api/routes/results.py
• backend/src/ref_backend/core/execution_groups.py
• backend/src/ref_backend/core/filter_utils.py
• backend/src/ref_backend/core/metric_values.py
• backend/src/ref_backend/core/mip_eras.py
• backend/src/ref_backend/core/model_ensemble.py
• backend/src/ref_backend/core/model_runs.py
• backend/src/ref_backend/core/reader_values.py
• backend/src/ref_backend/core/resource_usage.py
• backend/src/ref_backend/models/__init__.py
• backend/src/ref_backend/models/common.py
• backend/src/ref_backend/models/datasets.py
• backend/src/ref_backend/models/diagnostics.py
• backend/src/ref_backend/models/executions.py
• backend/src/ref_backend/models/values.py
• backend/src/ref_backend/testing.py
• backend/tests/conftest.py
• backend/tests/perf/test_endpoints.py
• backend/tests/test_api/test_routes/test_datasets.py
• backend/tests/test_api/test_routes/test_diagnostics.py
• backend/tests/test_api/test_routes/test_executions.py
• backend/tests/test_api/test_routes/test_mip_era_params.py
• backend/tests/test_core/conftest.py
• backend/tests/test_core/test_filter_utils.py
• backend/tests/test_core/test_metric_values.py
• backend/tests/test_core/test_mip_era_edges.py
• backend/tests/test_core/test_model_ensemble_retries.py
• backend/tests/test_core/test_model_runs.py
• backend/tests/test_core/test_resource_usage.py
• changelog/147.breaking.md
• changelog/147.feature.md
• changelog/147.improvement.md
• frontend/src/client/@tanstack/react-query.gen.ts
• frontend/src/client/index.ts
• frontend/src/client/sdk.gen.ts
• frontend/src/client/types.gen.ts
• frontend/src/components/dashboard/executionStats.test.tsx
• frontend/src/components/dashboard/executionStats.tsx
• frontend/src/components/datasets/diagnosticSummaryTable.tsx
• frontend/src/components/diagnostics/diagnosticCard.tsx
• frontend/src/components/execution/values/valuesPanel.test.tsx
• frontend/src/components/execution/values/valuesPanel.tsx
• frontend/src/components/explorer/chartValues.test.ts
• frontend/src/components/explorer/chartValues.ts
• frontend/src/components/explorer/content/filterControls.tsx
• frontend/src/components/explorer/content/useExplorerMetricValues.ts
• frontend/src/hooks/useDiagnosticMetricValues.ts
• frontend/src/hooks/useExecutionMetricValues.ts
• frontend/src/hooks/useMetricValues.test.ts
• frontend/src/hooks/useMetricValues.ts
• frontend/src/lib/failures.test.ts
• frontend/src/lib/failures.ts
• frontend/src/lib/resourceUsageCsv.test.ts
• frontend/src/routes/_app/diagnostics.$providerSlug.$diagnosticSlug/route.tsx
• frontend/src/routes/_app/executions.$groupId/route.tsx

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 506e410c-3ba3-46d0-b73d-bafa325b643a

Commits

Reviewing files that changed from the base of the PR and between 7988232 and aad8206.

Files ignored due to path filters: 2

• backend/tests/test-data/tests.integration.test_cmip7_aft/test_solve_cmip7_aft/db/climate_ref.db is excluded by !**/*.db
• backend/uv.lock is excluded by !**/*.lock

Files selected for processing: 10

• backend/src/ref_backend/api/routes/diagnostics.py
• backend/src/ref_backend/api/routes/executions.py
• backend/src/ref_backend/core/mip_eras.py
• backend/src/ref_backend/core/model_ensemble.py
• backend/src/ref_backend/core/model_runs.py
• backend/tests/test_api/test_routes/test_mip_era_params.py
• backend/tests/test_core/test_model_ensemble_retries.py
• backend/tests/test_core/test_model_runs.py
• changelog/147.breaking.md
• frontend/src/routes/_app/executions.$groupId/route.tsx

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

The API now uses shared reader and query helpers for diagnostic summaries, execution groups, resource usage, and metric values. It adds filtered facet endpoints, formalises MIP-era and group-count types, and updates generated clients and frontend queries to use these contracts.

Changes: API query and statistics updates

Layer / File(s)	Summary
Diagnostic and execution statistics backend/src/ref_backend/models/*, backend/src/ref_backend/core/resource_usage.py, backend/src/ref_backend/api/routes/diagnostics.py, backend/src/ref_backend/api/routes/executions.py	Statistics use nested group counts. Diagnostic summaries and resource usage use reader and query helpers with explicit filters for superseded and retracted executions.
Dataset and execution-group routes backend/src/ref_backend/core/execution_groups.py, backend/src/ref_backend/api/routes/datasets.py, backend/src/ref_backend/api/routes/executions.py, backend/src/ref_backend/api/routes/diagnostics.py	Routes use a shared execution-group loader. Dataset lists use the reader, and execution-group routes apply route-specific filters, ordering, and pagination.
MIP-era filtering backend/src/ref_backend/core/mip_eras.py, backend/src/ref_backend/core/model_runs.py, backend/src/ref_backend/core/model_ensemble.py, backend/src/ref_backend/api/routes/models.py, backend/src/ref_backend/models/datasets.py	MIP-era values are typed as CMIP6 or CMIP7. Shared helpers map eras to source types and support era filtering across diagnostic, execution, and model queries.
Metric-value facets backend/src/ref_backend/api/routes/diagnostics.py, backend/src/ref_backend/api/routes/executions.py, backend/src/ref_backend/core/reader_values.py, backend/src/ref_backend/models/values.py	Diagnostic and execution value routes add facet endpoints and a with_facets option. Shared filters support value and facet requests, and reader helpers retrieve facets without loading values.
Generated client and frontend updates frontend/src/client/*, frontend/src/hooks/*, frontend/src/components/explorer/*, frontend/src/components/dashboard/*	The client exposes the new facet operations and updated response types. Frontend hooks fetch facets separately from values and use the value response as a fallback if a facet request fails. Components read group counts from the nested response shape.

Sequence Diagram(s)

sequenceDiagram
  participant ValuesPage
  participant useMetricValues
  participant FacetRoute
  participant Reader
  ValuesPage->>useMetricValues: Request values and facets
  useMetricValues->>FacetRoute: Request facets with shared filters
  FacetRoute->>Reader: Read facets without values
  Reader-->>FacetRoute: Return facets
  FacetRoute-->>useMetricValues: Return facets
  useMetricValues-->>ValuesPage: Return values and facets

Loading

Possibly related issues

• Renovate Dependency Dashboard #54 — The dependency constraint matches the climate-ref version described in the issue.
• Record input source types on execution groups and collections on diagnostics climate-ref#991 — The changes formalise MIP-era filtering in the app while using reader-side era and source-type helpers.

Possibly related PRs

• Climate-REF/ref-app#146 — This PR changes the climate-ref constraint and adopts query and reader APIs.
• Climate-REF/ref-app#145 — This PR adds the performance test contract that this PR updates.

Priority: Normal

Change: Feature

Merge Risk: Minimal · up to aad82

The previously reported retraction issues are addressed, and the checked API and tab behavior presents no remaining merge-blocking issue.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 56.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 160 functions across 52 files. (1 skipped…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly identifies the main change: refactoring the API to use climate-ref's query package with explicit filters. The breaking-change marker is appropriate for the documented API and behavio…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title clearly identifies the main change: refactoring the API to use climate-ref's query package with explicit filters. The breaking-change marker is appropriate for the documented API and behaviour changes.

Full details: Docstring Coverage

Explanation

Docstring coverage is 56.88% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 160 functions across 52 files. (1 skipped: 1 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 3

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

⚔️ Resolve merge conflicts: 💡

• Resolve merge conflict in branch refactor/query-package

🛠️ Fix failing CI checks: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 687f1a8c-0022-469b-8771-aabede5bf7ae

Commits

Reviewing files that changed from the base of the PR and between f7eb639 and 7988232.

Files ignored due to path filters: 2

• backend/tests/test-data/tests.integration.test_cmip7_aft/test_solve_cmip7_aft/db/climate_ref.db is excluded by !**/*.db
• backend/uv.lock is excluded by !**/*.lock

Files selected for processing: 58

• backend/pyproject.toml
• backend/src/ref_backend/api/routes/datasets.py
• backend/src/ref_backend/api/routes/diagnostics.py
• backend/src/ref_backend/api/routes/executions.py
• backend/src/ref_backend/api/routes/models.py
• backend/src/ref_backend/api/routes/results.py
• backend/src/ref_backend/core/execution_groups.py
• backend/src/ref_backend/core/filter_utils.py
• backend/src/ref_backend/core/metric_values.py
• backend/src/ref_backend/core/mip_eras.py
• backend/src/ref_backend/core/model_ensemble.py
• backend/src/ref_backend/core/model_runs.py
• backend/src/ref_backend/core/reader_values.py
• backend/src/ref_backend/core/resource_usage.py
• backend/src/ref_backend/models/__init__.py
• backend/src/ref_backend/models/common.py
• backend/src/ref_backend/models/datasets.py
• backend/src/ref_backend/models/diagnostics.py
• backend/src/ref_backend/models/executions.py
• backend/src/ref_backend/models/values.py
• backend/src/ref_backend/testing.py
• backend/tests/conftest.py
• backend/tests/perf/test_endpoints.py
• backend/tests/test_api/test_routes/test_datasets.py
• backend/tests/test_api/test_routes/test_diagnostics.py
• backend/tests/test_api/test_routes/test_executions.py
• backend/tests/test_api/test_routes/test_mip_era_params.py
• backend/tests/test_core/conftest.py
• backend/tests/test_core/test_filter_utils.py
• backend/tests/test_core/test_metric_values.py
• backend/tests/test_core/test_mip_era_edges.py
• backend/tests/test_core/test_model_runs.py
• backend/tests/test_core/test_resource_usage.py
• changelog/147.breaking.md
• changelog/147.feature.md
• changelog/147.improvement.md
• frontend/src/client/@tanstack/react-query.gen.ts
• frontend/src/client/index.ts
• frontend/src/client/sdk.gen.ts
• frontend/src/client/types.gen.ts
• frontend/src/components/dashboard/executionStats.test.tsx
• frontend/src/components/dashboard/executionStats.tsx
• frontend/src/components/datasets/diagnosticSummaryTable.tsx
• frontend/src/components/diagnostics/diagnosticCard.tsx
• frontend/src/components/execution/values/valuesPanel.test.tsx
• frontend/src/components/execution/values/valuesPanel.tsx
• frontend/src/components/explorer/chartValues.test.ts
• frontend/src/components/explorer/chartValues.ts
• frontend/src/components/explorer/content/filterControls.tsx
• frontend/src/components/explorer/content/useExplorerMetricValues.ts
• frontend/src/hooks/useDiagnosticMetricValues.ts
• frontend/src/hooks/useExecutionMetricValues.ts
• frontend/src/hooks/useMetricValues.test.ts
• frontend/src/hooks/useMetricValues.ts
• frontend/src/lib/failures.test.ts
• frontend/src/lib/failures.ts
• frontend/src/lib/resourceUsageCsv.test.ts
• frontend/src/routes/_app/diagnostics.$providerSlug.$diagnosticSlug/route.tsx

Files with no reviewable changes: 2

• backend/tests/test_core/test_filter_utils.py
• backend/src/ref_backend/core/filter_utils.py

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.