AI-Assisted SQL: Generate, Review, and Validate Queries
Telemetry can use a plain-language question and table metadata to produce a first DataFusion SQL query or visualization plan. The SQL stays visible and editable in the Query workspace. This can reduce blank-page time, but it does not turn an ambiguous business question into an authoritative metric.
Use AI assistance for acceleration. Keep ownership of event contracts, counting rules, privacy decisions, and production thresholds with people who can review the underlying system.
Write a bounded prompt
A useful prompt identifies the table, event grain, metric, time range, filters, grouping, and expected output. For example:
Using api_request_completed, calculate hourly error rate for production
over the last seven complete days. A failed request has outcome = 'error'.
Return request_count, failed_count, and error_rate. Split by route_template,
exclude incomplete current-hour data, and order newest hour first.
This is safer than “show API health” because the denominator, outcome definition, time boundary, and grouping are explicit.
Do not paste secrets, raw customer content, access tokens, private prompts, or unreviewed personal data into the instruction. Prefer schema names, bounded categories, and synthetic examples.
Review the generated query
Before running or saving generated SQL, inspect these assumptions:
| Review area | Question |
|---|---|
| Table and grain | Does one row represent the unit being counted? |
| Field names and types | Do the referenced fields exist with compatible types? |
| Time | Is the intended UTC timestamp filtered, and are incomplete buckets handled? |
| Denominator | Does the rate divide by all eligible outcomes rather than only successes? |
| Nulls | Are missing values excluded, grouped, or defaulted deliberately? |
| Joins | Was each table pre-aggregated to a safe grain before joining? |
| Duplicates | Can retries or repeated delivery count the same business outcome twice? |
| Dimensions | Are grouping fields bounded enough to return a useful result? |
| Units | Are duration, bytes, tokens, currency, and percentages converted consistently? |
DataFusion SQL differs from PostgreSQL, BigQuery, Snowflake, and other engines. A syntactically familiar function may need a supported equivalent. Use the DataFusion SQL reference when a generated expression does not plan.
Validate the result
Successful execution only proves that the query ran. Validate meaning with a fixture or a small known window:
- Inspect raw rows for one expected group.
- Calculate one count, sum, or rate manually.
- Compare the result with the generated aggregate.
- Test an empty period and a period containing nulls.
- Check the newest bucket for partial data.
- Change one filter and confirm the result changes in the expected direction.
For joins, compare the row count before and after the join. An unexpected multiplication often indicates incompatible grains.
Save only reviewed analysis
Rename a reviewed query for the decision it supports, not for the prompt that created it. Include units and important scope in the name where practical. Save a new history entry when changing the logic, and explain material definition changes beside the dashboard that uses it.
Do not connect generated SQL directly to a paging alert, billing workflow, access-control decision, or customer-facing financial report without domain review and representative testing.
Improve a weak first answer
If the first query is wrong, make the correction explicit:
- define the row grain and eligible population;
- provide exact categorical values;
- specify whether identity is per user, account, session, or event;
- name the expected time field and bucket;
- state how to handle nulls, retries, and duplicate delivery;
- request intermediate counts beside the final percentage;
- ask for a short assumptions list with the SQL.
The Telemetry prompt pack includes reusable instrumentation and SQL review prompts. Continue with SQL Observability and Event Analytics or practice against deterministic data in the SaaS SQL Lab.