5.3 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.
Standalone or inside Omics
In full mode, ThothII has its own red header. Sign in using the installation's local account or the configured identity provider. The header lets you select English/Italian, light/dark, and fullscreen; Esc exits fullscreen. Open the user name menu to log out of ThothII. OIDC logout does not necessarily log out other applications using the same provider.
In embedded mode, first sign in to Omics and choose Datamart Builder in its left menu. ThothII opens with that authenticated identity: there is no second login or duplicate header. Use Omics's language, theme, fullscreen and logout controls. If portal access expires, return to Omics, sign in and reopen the page.
The Mac starts in English unless the browser remembers another choice. Changing the UI language affects labels, not saved domain content. A new session takes the selected language for the model's questions and reviewer choices; an existing session retains its saved language when resumed. Omics's language change reloads the page: confirm or cancel any unsaved-work warning. Reopening the saved session selection shows documents; it does not automatically restart generation.
Before creating a session
An administrator must have selected a workspace and configured the installation-wide provider, model, and thinking settings. The new-question 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 Session (Sessione in Italian). If a session is already open and unfinished, this returns to it without restarting it. Otherwise it opens a new question; no session is created until you submit that question.
- 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
In Administration, the dot beside Workspace is green when readiness is confirmed and red otherwise. Hover the button for the exact state; assistive technology receives the same description. Select Workspace to inspect preparation.
The session sidebar has two accordion sections: Active sessions and Archive, both initially closed. Only their headers appear below the scope tabs. Inside each nonempty list, Select all selects only that list; its delete action also applies only to the selected sessions in that list. The other list's selection is preserved. Opening a section closes the other; clicking the open section closes it too. Empty lists show only "No sessions yet." Long lists scroll inside their own panels. Here active means not archived, not necessarily a running model process. Existing groups and session actions remain inside those sections.
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 for full, or contact the portal administrator for embedded/upstream access.