Skip to content

DEMO.md

Latest commit

 

History

History
253 lines (206 loc) · 10.7 KB

DEMO.md

File metadata and controls

253 lines (206 loc) · 10.7 KB
Raw

Query Doctor Local UI Demo

Last reviewed: 2026-06-19

Language: English | Russian

query-doctor-web starts a localhost-only UI for Query Doctor. The current navigation centers on Diagnose, Details pages, Help, Known Query ID Python report autogeneration, and explicit selected-case LLM report/optimizer actions. Diagnose contains the Recent queries workflow and the secondary Known Query ID mode.

This is not a production web deployment. Public, repeatable demos should use query-doctor-web --public-demo; use query-doctor-demo directly only when you need to inspect or reuse the generated pack. Do not use old prepared-pack case IDs, account names, local deep links, or environment-specific query IDs in public demo material.

Synthetic Demo Startup

For the normal read-only public demo, run one command:

query-doctor-web --public-demo

This generates a fresh synthetic pack under the system temp directory, points the web UI at that pack, forces Python-only mode, ignores default local config and owner-source environment hints, rejects explicitly loaded external source settings, and blocks all POST routes. The pack includes static read-only Trino Beta demo cases rendered from raw-free compact diagnosis facts; those cases do not contact a Trino coordinator and do not enable materialized Details, Python Report, optimizer behavior, generated SQL, or SQL execution.

If you need to inspect or reuse the generated pack manually, generate a local synthetic pack and open it in the web UI:

DEMO_PACK="${TMPDIR:-/tmp}/query-doctor-demo-pack"
query-doctor-demo --out "$DEMO_PACK" --overwrite
QUERY_DOCTOR_ACTION_OUTCOMES_PATH="$DEMO_PACK/action_outcomes.jsonl" \
  query-doctor-web --host 127.0.0.1 --port 8766 --batch-summary "$DEMO_PACK/batch_summary.json"

Open the localhost URL printed by query-doctor-web. The demo generator requires a dedicated query-doctor-* temp output path; keep the generated pack outside the repository. Useful demo filters:

/?query_group=workloads#scan-context
/?query_group=workloads#recent-results
/?query_group=optimization#recent-results
/?query_group=stats#recent-results
/?query_group=frequent_short#recent-results

The synthetic pack does not call Cloudera Manager, Impala, Prometheus, a local generation backend, or the network. It contains only generated demo data and is not performance evidence. The Trino Beta demo section is a bounded static compact diagnosis demo, not a live Trino source and not broader/shared Trino production support.

Read-Only Public Demo

--public-demo remains a click-through GET-only UI over the generated synthetic workflow. Collection, report generation, optimizer actions, uploads, job cancellation, and feedback writes are disabled.

Real Local Startup

Use ignored local config and credentials from environment variables. For a Cloudera Manager (CM) workflow, Query Doctor expects read-only CM credentials in ~/.qdcreds/cm-ro.env. For direct Impala workflows, keep daemon hosts, Prometheus URLs, Kerberos service names, and metadata coordinator settings in ~/.qdcreds/query-doctor-config.json or another ignored local config. Secret values are not stored in the repository and must not enter committed config.

Preferred local startup:

scripts/query-doctor-web-local

For a local Python-only session where selected-case report and optimizer actions do not call an LLM:

scripts/query-doctor-web-local-no-llm

Manual startup with the current config filename:

mkdir -p ~/.qdcreds
cp query-doctor-config.example.json ~/.qdcreds/query-doctor-config.json
# Edit ~/.qdcreds/query-doctor-config.json with CM or direct Impala settings.
set -a
source ~/.qdcreds/cm-ro.env
set +a
query-doctor-web \
  --config ~/.qdcreds/query-doctor-config.json \
  --host 127.0.0.1 \
  --port 8765

~/.qdcreds/query-doctor-config.json stores only non-secret settings such as CM URL, cluster, service, username fallback, output path, CA bundle, direct Impala daemon hosts, Prometheus URL, and metadata coordinator. Do not put passwords, tokens or Authorization headers in the config file.

For CLI single-query collection, use the same environment file:

set -a
source ~/.qdcreds/cm-ro.env
set +a
DEMO_CASE_OUT="$(mktemp -d)"
query-doctor-collect-cm-profiles \
  --query-id QUERY_ID_WITH_COLON \
  --limit 1 \
  --out "$DEMO_CASE_OUT" \
  --redact \
  --ca-bundle ~/.qdcreds/cm-chain.pem

Main Surfaces

  • Diagnose / Recent queries: discovers completed query summaries from the selected source, collects bounded selected profiles, ranks deterministically, and never auto-runs reports or optimizer jobs.
  • Diagnose / Running now: uses the same result shape for queries running at scan time, with no date/hour filters and lower-confidence live evidence.
  • Diagnose / Known Query ID: analyzes one explicit Impala query ID, prepares the deterministic Python report in the same submit job, clears the input after submit, and appends each result to the Known Query ID analysis table. It uses Cloudera Manager by default or direct Impala daemon profile endpoints when cluster_type=impala is configured. LLM report and optimizer actions remain explicit.
  • Details: shows safe deterministic analysis details, the generated Python report when available, and explicit LLM report / Query LLM optimizer actions for one analyzed query.
  • Help: keeps workflow, safety boundaries, and GitHub documentation links available inside the product.

The pasted-SQL Query Optimizer direct route remains read-only for compatibility and safety testing. It accepts one safe SELECT / WITH ... SELECT, parses it locally, does not execute it, and does not render pasted SQL back after submit. It is not a primary demo navigation item unless you intentionally need to explain pre-profile SQL review.

Safety

  • The server listens on 127.0.0.1 by default.
  • Non-local bind is rejected unless --allow-nonlocal-web-bind is explicitly passed. Legacy alias --allow-nonlocal-demo-bind is still accepted for older scripts.
  • Do not publish ordinary local mode externally. Use query-doctor-web --public-demo for public synthetic demos.
  • Web forms do not accept CM URLs, credentials or local config contents.
  • Credentials stay only in the web server process environment.
  • Recent queries scans perform bounded selected-profile collection; standalone collector listing mode remains listing-only.
  • Known Query ID collection is explicit and redacted.
  • Direct Impala workflows can use optional bounded Prometheus runtime metrics when configured; those metrics are context, not discovery or events.
  • The collector applies the max profile size guard; default is 52428800 bytes.
  • Raw profile text, raw SQL, raw provider API responses, raw metadata and credentials must not appear in UI, logs, docs or reports.

Generated local case data may remain sensitive even after redaction. Keep it in ignored output directories or temporary locations, and do not commit generated cases, reports, metadata, local config, browser output, screenshots from real clusters, or credentials.

Known Query ID Scope

After query ID submit, the UI runs existing tools in sequence:

  1. query-doctor-collect-cm-profiles with --query-id, --limit 1 and --redact, or query-doctor-collect-impala-profile when cluster_type=impala is configured.
  2. query-doctor-pipeline in analyzer-first mode for deterministic facts.
  3. Deterministic Python report generation and validation.
  4. LLM report and Query LLM optimizer only when the user clicks explicit actions on the details page.

The UI does not enable SQL execution, automatic LLM work, or Cloudera Manager events for direct Impala Known Query ID mode. Direct Impala Recent/Running scans can discover bounded daemon query-list entries when that cluster source is selected, and configured Prometheus metrics remain bounded context only. These paths do not change analyzer/report behavior.

Demo Storyline

Goal: show Query Doctor as an engineering diagnostic and validation tool, not as a chat interface over raw profiles.

Use demo-cases.md for the current synthetic scenario list and demo-data-engineer-brief.md for the detailed talk track. The useful public demo arc is:

  1. Scan context workload follow-up that shows which repeated pattern to open;
  2. deterministic candidate ranking from generated profile/analyzer facts;
  3. Details page before any report or optimizer action;
  4. explicit trusted report that phrases Python-owned facts;
  5. explicit Query LLM optimizer outcome that shows trusted recommendations, trusted no-rewrite guidance, or a validated SQL draft only when supported;
  6. statistics-maintenance candidate evidence with required confirmation steps;
  7. mixed-signal and unknown-but-useful cases that avoid false certainty;
  8. direct Impala profile compatibility where missing optional endpoints are non-fatal;
  9. rejected/partial optimizer output staying untrusted and hidden.

Recommended synthetic path:

  1. Open Scan context at #scan-context.
  2. Show the Admission/runtime workload follow-up, local synthetic action outcomes, then open Workload Details and follow a representative case Action card to show where rerun feedback is recorded.
  3. Open the synthetic optimization recommendations case.
  4. Show deterministic ranking, Details findings, and safe review locations.
  5. Open the trusted report and optimizer outcome.
  6. Open the statistics-maintenance candidate and show the metadata/estimate evidence chain plus confirmation requirements.
  7. Open the mixed-signal case to show staged review without a single root-cause claim.
  8. Open the unknown and direct Impala cases if the audience asks about limitations or old-cluster compatibility.
  9. Open Frequent short and show low-value repeat handling.
  10. Mention the rejected-draft scenario to show that validation can refuse an unsafe generated rewrite.

Keep raw SQL, raw profiles, raw metadata, local artifact paths, model/runtime internals, command output, account names, real query IDs, and local config details out of the presented demo.

Pre-Demo Smoke

python3 -m pytest -q tests/test_demo_data.py tests/test_web_ui_home.py tests/test_web_ui_help.py
python3 -m pytest -q tests/test_web_server.py tests/test_web_optimizer.py tests/test_query_optimizer.py
git diff --check

Optional optimizer-specific confidence checks before a real-cluster private demo:

  • run scripts/compare_optimizer_models.py on private prepared cases if model or prompt behavior changed;
  • for any externally prepared SQL draft, first run the deterministic optimizer validator; only then run a separate read-only Impala smoke comparison;
  • never use the pasted-SQL Query Optimizer page to execute SQL. It remains parse/analyze only.