Skip to main content
Run and monitor query execution. See the Query API documentation for more information.
Replace MODEL_ID with your model ID, table with the base view name, join_paths_from_topic_name with the topic name, and order_items.total_revenue with a field from your model. modelId belongs inside query, and field references use view.field notation. Without resultType, run returns a newline-delimited JSON stream, not a single JSON document. Set resultType in the request body to json, csv, or xlsx when you need a result in that format. The global --format flag controls CLI presentation; it does not select the query’s result format.

​
Query results in the terminal

In human output (the default in a terminal, or --format human), query run and query wait decode the stream and print a table. The table uses the model’s field labels as headers, keeps the query’s column order, and applies each field’s number format. For example, a percent measure prints as 39.92%. If the query doesn’t finish before the first response returns, the CLI polls query/wait until every job is done.
In --format json, the stream passes through to stdout unchanged. A query with pivots prints pivoted: the other dimensions stay as rows, and each pivot value gets its own columns, up to the query’s column_limit.

​
Charts

Add --chart to draw the results as a bar table. Each dimension is a column, and each measure gets a column of bars scaled to its own maximum. On a pivoted query, the bars of a measure share one scale across all pivot values. Values that cross zero get a zero axis. revenue-by-category.json is a query body like the earlier example, without resultType:
If a chart is too wide for the terminal, the CLI removes columns and prints a note. When output isn’t a terminal, such as a pipe or a file, the chart is 80 columns wide. The CLI checks --chart and its related flags as follows:
  • If the request body sets resultType, --chart ignores it. In human output, the CLI prints a note.
  • --chart fails before it sends a request when you explicitly set JSON output: --format json, OMNI_OUTPUT_FORMAT=json, or a profile default set with omni config set-format json. It also fails with a planOnly body, or with a command other than query run or query wait.
  • --chart-value and --chart-rows fail without --chart.
The CLI checks --chart-value against the result’s columns only after the query returns. If a value doesn’t name a column, the command fails and lists the available columns. It also fails if the column holds no numbers. If you don’t set a format and you pipe the output, --chart still draws. For example, omni query run --body @revenue-by-category.json --chart | less works.

​
Open the query in a workbook

Add --workbook to query run to also open the query in an ephemeral workbook. The CLI sets workbookUrl: true in the request body, so you must pass a JSON body. --workbook can’t be used with a planOnly body.
In human output, the link prints under the results as Open in Omni: <url>. If the body requests CSV or XLSX, the link prints to stderr, so stdout contains only the file. In JSON output, including piped output, the link goes to stderr as {"workbookUrl": "<url>"}. You get a link only if you have permission to use workbooks on the query’s model; otherwise the CLI prints no link and no error.
Every command in this group also accepts the global flags, including --token, --profile, --format, and --compact.