omni-query

Use `omni query run` with a JSON body containing the modelId, base view as `table`, a `fields` array of view.field references, and `join_paths_from_topic_name` set to the topic. Add `resultType: "csv"` or `"json"` at the top level to get readable output instead of the default base64 Arrow response.

Add a `calculations[]` entry with a `calc_name` and a `sql_expression` AST using a template operator like `Omni.OMNI_RUNNING_TOTAL` or `Omni.OMNI_PERCENT_OF_TOTAL` with one `for_calc: true` field operand. The `calc_name` must also appear in `query.fields` or the column is computed but never rendered.

Blank or `#ERROR!` calc columns usually mean the calc failed silently under `swallow_errors: true`. Re-run with `swallow_errors: false` to surface the real error, and check operand order, `for_calc` flags, date truncation, and that every field the calc references is included in `query.fields`.

Use `userEditedSQL` only when no topic can express the query or the user explicitly asks to run SQL as-is. Raw SQL bypasses access grants, row-level access filters, and always_where controls, is invisible to Viewer roles in dashboards, and unbounded results are capped at 50,000 rows.

Some string date filters fail to bind in pivoted queries, returning the same row count as unfiltered. Retry with the typed date-filter object shape (type, kind, left_side, right_side, ui_type), and note that pivoted queries also reject `limit: null` — pass an explicit numeric limit.

Use `omni ai job-submit` with the model ID and a natural-language prompt, then poll `omni ai job-status` (reading the `state` field until COMPLETE) and retrieve output with `omni ai job-result`. For simple single queries, `omni ai generate-query` returns query JSON synchronously.