Multi-stage queries in REST API

[AivanF]

Summary by CodeRabbit

• New Features

  • REST /query endpoint now supports multi-stage DAG queries alongside single-stage queries, with automatic stage ordering.

• Documentation

  • Updated documentation clarifying multi-stage query support across REST API, Python SDK, CLI, and MCP execution surfaces.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c9e790ac-e15d-4126-9c40-dba153b09537

📥 Commits

Reviewing files that changed from the base of the PR and between 48ffe02 and 8e7c483.

📒 Files selected for processing (6)

• .claude/skills/slayer-query.md
• CLAUDE.md
• docs/concepts/queries.md
• pyproject.toml
• slayer/api/server.py
• tests/test_api_server.py

---

📝 Walkthrough

Walkthrough

REST /query endpoint now accepts multi-stage DAG queries via a new QueryListRequest model that includes a queries list and top-level execution flags, while QueryRequest.source_model broadens to accept inline model dictionaries. The handler discriminates request shapes, validates DAGs for cycles, and executes through the engine's auto-sort. Tests cover DAG validation, out-of-order auto-sorting, cycle rejection, and inline model extension/definition. Documentation clarifies surface coverage across Python SDK, CLI, MCP query_nested, and REST endpoints. Version bumped to 0.6.7.

Changes

Multi-stage query DAG and inline source model support

Layer / File(s)	Summary
Request models and type updates slayer/api/server.py	Import Union type; expand QueryRequest.source_model from Optional[str] to Optional[Union[str, Dict[str, Any]]] for polymorphic inline models; introduce QueryListRequest with required queries: List[Dict[str, Any]] and optional top-level variables, dry_run, explain fields and extra="forbid" validation.
REST endpoint handler for single/multi-stage discrimination slayer/api/server.py	Modify /query handler to accept Union[QueryRequest, QueryListRequest]; detect multi-stage requests by queries presence; validate non-empty queries and route to engine.execute(query=list(...), variables=..., dry_run=..., explain=...) for DAG auto-sort and cycle detection; preserve existing QueryRequest paths for run-by-name and source-model/query-fields.
Tests for multi-stage DAGs and inline source models tests/test_api_server.py	Add TestQueryListBody to validate DAG dry-run SQL generation, out-of-order stage auto-sorting, rejection of empty queries, and 400 cycle errors; add TestQueryInlineSourceModel to verify source_model as model-extension dict and full inline model dict during dry-run.
Documentation for interfaces and version release .claude/skills/slayer-query.md, CLAUDE.md, docs/concepts/queries.md, pyproject.toml	Update "Surfaces" and "Surface coverage" sections to enumerate REST POST /query multi-stage list-body support alongside Python SDK, CLI, and MCP query_nested; clarify single-stage MCP query tool remains single-query only; document QueryRequest.source_model polymorphism; bump version to 0.6.7.

Sequence Diagram

sequenceDiagram
  participant Client
  participant Handler
  participant Engine
  Client->>Handler: POST /query with body
  alt body has "queries" field
    Handler->>Handler: Validate non-empty queries
    Handler->>Engine: execute(query=list(queries), variables=..., dry_run=..., explain=...)
    Engine->>Engine: Auto-sort stages (DAG)
    Engine->>Engine: Detect cycles
  else body has "query" field or run name
    Handler->>Handler: Validate QueryRequest shape
    Handler->>Engine: execute_query_request(source_model=str\|dict, ...)
  end
  Engine-->>Handler: result or error
  Handler-->>Client: response with SQL/result or 400 cycle error

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• MotleyAI/slayer#10: Both PRs modify slayer/api/server.py's /query handling to accept/use dry_run/explain (main PR for multi-stage QueryListRequest, retrieved PR for query-level flags and returning sql/meta).
• MotleyAI/slayer#109: The main PR's REST /query changes broaden QueryRequest.source_model to accept inline model dict payloads (not just model name strings), which aligns with the retrieved PR's MCP query tool accepting the same inline source_model shapes.
• MotleyAI/slayer#67: Main PR's slayer/api/server.py extends the existing /query endpoint to accept {"queries":[...]} multi-stage bodies (and inline source_model dicts), which relies on the earlier engine/query/variables execution model introduced in the retrieved PR.

Suggested reviewers

• ZmeiGorynych

Poem

A rabbit hops through query DAGs so grand,
Where stages auto-sort across the land,
Inline models bloom in polymorphic grace,
While cycles fall at breakneck pace! 🐰✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 45.45% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Multi-stage queries in REST API' accurately summarizes the primary change: adding support for multi-stage DAG queries through the REST /query endpoint.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch aivan/2026-05-14-Nested-Queries-REST-API

---

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

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud