2.9 KiB
User guide: from question to validated SQL
This guide is for a reviewer using a configured ThothII installation. Installation, workspace publication, preprocessing, and database administration are separate paths; links to them are at the end of this page.
Before creating a session
An administrator must have selected a workspace and configured the installation-wide provider, model, and thinking settings. The New session form deliberately asks only for the question.
The workspace is a pinned Git revision. A subsequent workspace update cannot alter a session already created from an earlier revision. If a workspace cannot reach its configured runtime DWH, new sessions are refused before any session state is written.
Create and review a session
- Sign in and select New session.
- Enter a precise business question, including the relevant time period and desired output. For example: “List patients discharged in the last 30 days, with ward and discharge date.”
- Review each gate and make the decision requested by the widget. A choice with a decision payload can persist immediately; a multi-choice widget records each selected decision; a confirmation widget approves an artifact or phase.
- Inspect the generated artifacts, especially schema linking, CTEs, and final SQL. The final SQL is available only after the F7 review gate.
- At F8, decide whether a datamart is requested. This is distinct from approving the SQL.
The workflow phases are fixed:
| Phase | What is reviewed |
|---|---|
| F1–F3 | clarification, reusable Memory, and the rewritten question |
| F4–F5 | proposed tables, columns, Evidence, then their summary |
| F6 | a CTE plan or an explicit skip |
| F7 | sql_final.sql |
| F8 | the datamart request or refusal |
Resume, archive, and the meaning of saved state
The sidebar lists sessions and their current lifecycle. Resuming returns to the last incomplete phase. A finalized or archived session cannot be resumed.
The source of truth is the workspace session directory: session_manifest.yaml, phase artifacts,
and review_decisions.jsonl. The visible activity stream is rebuilt from live SSE events and is
not a transcript store. Therefore a decision or artifact that has not been persisted did not
happen from the workflow’s point of view.
Choose the correct neighbouring path
- To prepare, update, validate, or preprocess a workspace, use Workspace operations.
- To create a database configuration, refresh its physical schema, or generate catalog descriptions, use Database management.
- To author material the workflow can retrieve, use Evidence. A proposal from a session does not become Evidence automatically: a curator must review and publish it in Git.
- For login and access recovery, use local authentication or OIDC authentication.