lhc analytics
Commands for chart generation, analytics pipeline, SQL validation, and context inspection.
These commands talk to the Analytics service (LHC_ANALYTICS_BASE_URL).
Chart generation
analytics generate <query>
Trigger chart generation from a natural-language query:
lhc analytics generate "<query>" [--datasources <ids>] [--model <slug>] [--wait] [--timeout <s>] [--poll-interval <s>]
| Flag | Default | Description |
|---|---|---|
--datasources | — | Comma-separated datasource IDs (e.g. 10,1,7) |
--model | — | Custom model slug |
--wait | false | Poll until the job completes, fails, or times out |
--timeout | 440 | Max polling duration in seconds (only with --wait) |
--poll-interval | 8 | Seconds between poll iterations (only with --wait) |
Without --wait the CLI prints the trigger response (including job_id) and exits immediately — the caller is responsible for polling.
With --wait the CLI blocks until the job reaches completed or failed state and prints the final job record.
Example:
lhc analytics generate "Show sales by region" \
--datasources 10,1 \
--model awdw \
--wait
analytics job <job-id>
Get the current status of a chart-generation job:
lhc analytics job <job-id>
Example:
lhc analytics job 4f8c3d4e-0000-0000-0000-000000000001
Job status values: pending, running, completed, failed.
completed does not by itself mean that a chart was created. The job's result.outcome says what
the run produced:
outcome | Meaning |
|---|---|
chart | A chart was created — its ID is in the result |
dashboard | A dashboard was created |
clarification | The question was ambiguous; the answer asks you to clarify before a chart is built |
text_only | The run answered in text without a chart, for example because the data cannot answer the question as asked; result.suppression_reason explains why when a safeguard held the chart back |
Check outcome rather than status in scripts that expect a chart.
Context and SQL
analytics context-describe
Describe the analytics context for a model — available tables, hierarchies, and chart types:
lhc analytics context-describe --model <slug>
| Flag | Required | Description |
|---|---|---|
--model | yes | Custom model slug |
analytics sql-validate <sql>
Validate a SQL query against the analytics service before running it:
lhc analytics sql-validate "<sql>" [--model <slug>]
Example:
lhc analytics sql-validate "SELECT count(*) FROM orders" --model awdw
Pipeline (step-by-step)
The pipeline commands expose each step of chart generation individually. Use these when you need full control over the pipeline state or want to debug a specific step. For most use cases, analytics generate --wait is simpler.
The pipeline follows four steps: sql → dataset → chart → finalize. Each step returns a pipeline_state_token that must be passed to the next step.
analytics pipeline sql
Step 1 — Generate and validate the SQL query:
lhc analytics pipeline sql --message "<query>" [--datasources <ids>] [--model <slug>]
| Flag | Required | Description |
|---|---|---|
--message | yes | Natural-language user query |
--datasources | no | Comma-separated datasource IDs |
--model | no | Custom model slug |
Returns a pipeline_state_token for step 2.
analytics pipeline dataset
Step 2 — Deploy the Superset view and register the dataset:
lhc analytics pipeline dataset --token <pipeline-state-token>
Returns an updated pipeline_state_token for step 3.
analytics pipeline chart
Step 3 — Create the chart in Superset:
lhc analytics pipeline chart --token <pipeline-state-token> [--chart-type <type>]
| Flag | Required | Description |
|---|---|---|
--token | yes | Pipeline state token from step 2 |
--chart-type | no | Override chart type (bar, line, pie, area, scatter, table, big_number, …) |
Returns an updated pipeline_state_token for step 4.
analytics pipeline finalize
Step 4 — Build the dashboard and embedding configuration:
lhc analytics pipeline finalize --token <pipeline-state-token>
Returns the final chart and dashboard metadata including the chart_id and dashboard_id.
Full pipeline example
# Step 1 — SQL
TOKEN=$(lhc analytics pipeline sql \
--message "Revenue by month" \
--datasources 10 \
--model awdw \
--output json | python3 -c "import json,sys; print(json.load(sys.stdin)['pipeline_state_token'])")
# Step 2 — Dataset
TOKEN=$(lhc analytics pipeline dataset --token "$TOKEN" \
--output json | python3 -c "import json,sys; print(json.load(sys.stdin)['pipeline_state_token'])")
# Step 3 — Chart
TOKEN=$(lhc analytics pipeline chart --token "$TOKEN" \
--output json | python3 -c "import json,sys; print(json.load(sys.stdin)['pipeline_state_token'])")
# Step 4 — Finalize
lhc analytics pipeline finalize --token "$TOKEN"