omni-query

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Omni Query

Omni 查询

Run queries against Omni's semantic layer via the Omni CLI. Omni translates field selections into optimized SQL — you specify what you want (dimensions, measures, filters), not how to get it.

Tip: Use
omni-model-explorer
first if you don't know the available topics and fields.

通过Omni CLI对Omni的语义层运行查询。Omni会将字段选择转换为优化后的SQL——你只需指定想要的内容（维度、度量、筛选条件），无需关心实现方式。

提示：如果你不了解可用的主题和字段，请先使用
omni-model-explorer
。

Prerequisites

前提条件

bash

undefined

bash

undefined

Verify the Omni CLI is installed — if not, ask the user to install it

验证Omni CLI是否已安装——若未安装，请提示用户进行安装

See: https://github.com/exploreomni/cli#readme

参考：https://github.com/exploreomni/cli#readme

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

command -v omni >/dev/null || echo "ERROR: Omni CLI is not installed."


```bash

Show available profiles and select the appropriate one

显示可用配置文件并选择合适的配置文件

omni config show

If multiple profiles exist, ask the user which to use, then switch:

若存在多个配置文件，请询问用户使用哪个，然后切换：

omni config use <profile-name>


You also need a **model ID** and knowledge of available **topics and fields**.

omni config use <profile-name>


你还需要一个**model ID**，并了解可用的**主题和字段**。

Discovering Commands

命令探索

bash

omni query --help              # List query operations
omni query run --help          # Show flags for running a query
omni ai --help                 # AI-powered query generation

Tip: Use
-o json
to force structured output for programmatic parsing, or
-o human
for readable tables. The default is
auto
(human in a TTY, JSON when piped).

bash

omni query --help              # 列出查询操作
omni query run --help          # 显示运行查询的参数
omni ai --help                 # 基于AI的查询生成

提示：使用
-o json
强制输出结构化数据以便编程解析，或使用
-o human
输出易读的表格。默认值为
auto
（在终端中输出人类可读格式，管道传输时输出JSON）。

Running a Query

运行查询

Basic Query

基础查询

bash

omni query run --body '{
  "query": {
    "modelId": "your-model-id",
    "table": "order_items",
    "fields": [
      "order_items.created_at[month]",
      "order_items.total_revenue"
    ],
    "limit": 100,
    "join_paths_from_topic_name": "order_items"
  }
}'

bash

omni query run --body '{
  "query": {
    "modelId": "your-model-id",
    "table": "order_items",
    "fields": [
      "order_items.created_at[month]",
      "order_items.total_revenue"
    ],
    "limit": 100,
    "join_paths_from_topic_name": "order_items"
  }
}'

Query Parameters

查询参数

Parameter	Required	Description
`modelId`	Yes	UUID of the Omni model
`table`	Yes	Base view name (the `FROM` clause)
`fields`	Yes	Array of `view.field_name` references
`join_paths_from_topic_name`	Recommended	Topic for join resolution
`limit`	No	Row limit (default 1000, max 50000, `null` for unlimited)
`sorts`	No	Array of sort objects
`filters`	No	Filter object
`pivots`	No	Array of field names to pivot on

参数	是否必填	描述
`modelId`	是	Omni模型的UUID
`table`	是	基础视图名称（对应SQL的 `FROM` 子句）
`fields`	是	`view.field_name` 引用的数组
`join_paths_from_topic_name`	推荐	用于关联解析的主题
`limit`	否	行数限制（默认1000，最大50000，设为 `null` 表示无限制）
`sorts`	否	排序对象数组
`filters`	否	筛选条件对象
`pivots`	否	用于透视的字段名称数组

Field Naming

字段命名

Fields use

view_name.field_name

. Date fields support timeframe brackets:

users.created_at[date]      — Daily
users.created_at[week]      — Weekly
users.created_at[month]     — Monthly
users.created_at[quarter]   — Quarterly
users.created_at[year]      — Yearly

字段采用

view_name.field_name

格式。日期字段支持时间范围括号：

users.created_at[date]      — 按日统计
users.created_at[week]      — 按周统计
users.created_at[month]     — 按月统计
users.created_at[quarter]   — 按季度统计
users.created_at[year]      — 按年统计

Sorts

排序

json

"sorts": [
  { "column_name": "order_items.total_revenue", "sort_descending": true }
]

json

"sorts": [
  { "column_name": "order_items.total_revenue", "sort_descending": true }
]

Filters

筛选条件

json

"filters": {
  "order_items.created_at": "last 90 days",
  "order_items.status": "complete",
  "users.state": "California,New York"
}

Expressions:

"last 90 days"

"this quarter"

"2024-01-01 to 2024-12-31"

"not California"

"null"

"not null"

">100"

"between 10 and 100"

"contains sales"

"starts with A"

. See references/filter-expressions.md for the complete expression syntax reference.

json

"filters": {
  "order_items.created_at": "last 90 days",
  "order_items.status": "complete",
  "users.state": "California,New York"
}

表达式示例：

"last 90 days"

"this quarter"

"2024-01-01 to 2024-12-31"

"not California"

"null"

"not null"

">100"

"between 10 and 100"

"contains sales"

"starts with A"

。完整的表达式语法参考请查看references/filter-expressions.md。

Pivots

透视

json

{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.status", "order_items.count"],
    "pivots": ["order_items.status"],
    "join_paths_from_topic_name": "order_items"
  }
}

json

{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.status", "order_items.count"],
    "pivots": ["order_items.status"],
    "join_paths_from_topic_name": "order_items"
  }
}

Handling and Validating Results

结果处理与验证

Default response: base64-encoded Apache Arrow table. Arrow results are binary — you cannot parse individual row data from the raw response. To verify a query returned data, check

summary.row_count

in the response.

For human-readable results, request CSV instead:

json

{ "query": { ... }, "resultType": "csv" }

默认响应：base64编码的Apache Arrow表格。Arrow结果为二进制格式——无法从原始响应中解析单行数据。要验证查询是否返回数据，请检查响应中的

summary.row_count

。

若需人类可读的结果，可请求CSV格式：

json

{ "query": { ... }, "resultType": "csv" }

Result Validation

结果验证

Every query response should be checked before trusting the results or presenting them to the user.

Check for errors:

If the response contains an
```
error
```
key, the query failed. Common causes: bad field name, missing join path, malformed filter expression, permission error.
If the response contains
```
remaining_job_ids
```
, the query is still running — poll with
```
omni query wait
```
before checking results.

Check row count:

```
summary.row_count == 0
```
— the query returned no data. This may be valid (e.g., no data in the filter range) but is worth flagging to the user. Common causes: overly restrictive filters, wrong date range, field that doesn't match any rows.
```
summary.row_count
```
equals the
```
limit
```
you set — results may be truncated. If the user needs complete data, re-run with a higher limit or
```
null
```
for unlimited.

Spot-check data with CSV:

When accuracy matters, request CSV and scan the output:

bash

omni query run --body '{
  "query": { ... },
  "resultType": "csv"
}'

Check that:

Column headers match the fields you requested
Values are in expected ranges (e.g., revenue isn't negative, dates aren't in the future)
Aggregations make sense (e.g., a count isn't returning a sum)

Validate filter behavior:

If your query includes filters, verify they're being applied:

bash

undefined

在信任结果或向用户展示之前，应检查每个查询的响应。

检查错误：

若响应包含
```
error
```
字段，则查询失败。常见原因：字段名称错误、缺少关联路径、筛选表达式格式错误、权限问题。
若响应包含
```
remaining_job_ids
```
，则查询仍在运行——需使用
```
omni query wait
```
轮询，直至查询完成后再检查结果。

检查行数：

```
summary.row_count == 0
```
——查询未返回数据。这可能是正常情况（例如筛选范围内无数据），但需向用户说明。常见原因：筛选条件过于严格、日期范围错误、字段无匹配行。
```
summary.row_count
```
等于设置的
```
limit
```
值——结果可能被截断。若用户需要完整数据，请重新运行查询并设置更高的限制，或设为
```
null
```
表示无限制。

通过CSV抽查数据：

当需要确保准确性时，请求CSV格式并扫描输出：

bash

omni query run --body '{
  "query": { ... },
  "resultType": "csv"
}'

检查内容：

列标题与请求的字段匹配
值在预期范围内（例如收入不为负数、日期不在未来）
聚合结果合理（例如计数未返回求和值）

验证筛选条件的有效性：

若查询包含筛选条件，请验证其是否生效：

bash

undefined

Run the same query without filters

运行不带筛选条件的相同查询

omni query run --body '{ "query": { ... (no filters) ... }, "resultType": "csv" }'

omni query run --body '{ "query": { ... (无筛选条件) ... }, "resultType": "csv" }'

Compare row counts — filtered should be <= unfiltered

比较行数——带筛选条件的行数应≤不带筛选条件的行数


If both queries return the same row count, the filter may not be binding (wrong field name, unsupported expression, or the known bug where boolean filters are dropped with pivots).


若两个查询返回的行数相同，可能是筛选条件未生效（字段名称错误、表达式不支持，或已知的透视时布尔筛选条件被忽略的bug）。

Validation Checklist

验证检查清单

Check	How	When
No error in response	Check for `error` key	Every query
Data was returned	`summary.row_count > 0`	Every query
Results not truncated	`row_count < limit`	When completeness matters
Columns are correct	CSV column headers match requested fields	When building dashboards or reports
Values are reasonable	Spot-check CSV output	When presenting to users
Filters are applied	Compare filtered vs unfiltered row counts	When using filters
Long-running query completed	No `remaining_job_ids` in final response	Queries on large tables

检查项	检查方式	检查时机
响应中无错误	检查是否存在 `error` 字段	每次查询后
返回了数据	`summary.row_count > 0`	每次查询后
结果未被截断	`row_count < limit`	当需要完整结果时
列信息正确	CSV列标题与请求字段匹配	构建仪表板或报表时
值合理	抽查CSV输出	向用户展示结果时
筛选条件已生效	比较带筛选和不带筛选的行数	使用筛选条件时
长时间运行的查询已完成	最终响应中无 `remaining_job_ids`	查询大型表时

Decoding Arrow Results

解码Arrow结果

python

import base64, pyarrow as pa
arrow_bytes = base64.b64decode(response["data"])
reader = pa.ipc.open_stream(arrow_bytes)
df = reader.read_all().to_pandas()

python

import base64, pyarrow as pa
arrow_bytes = base64.b64decode(response["data"])
reader = pa.ipc.open_stream(arrow_bytes)
df = reader.read_all().to_pandas()

Long-Running Queries

长时间运行的查询

If the response includes

remaining_job_ids

, poll until complete:

bash

omni query wait --jobids job-id-1,job-id-2

若响应包含

remaining_job_ids

，需轮询直至完成：

bash

omni query wait --jobids job-id-1,job-id-2

Running Queries from Dashboards

从仪表板运行查询

Extract and re-run queries powering existing dashboards:

bash

undefined

提取并重新运行现有仪表板中的查询：

bash

undefined

Get all queries from a dashboard

获取仪表板中的所有查询

omni documents get-queries <dashboardId>

Run as a specific user

以特定用户身份运行

omni query run --body '{ "query": { ... }, "userId": "user-uuid-here" }'

Cache policy (valid values: Standard, SkipRequery, SkipCache)

缓存策略（有效值：Standard, SkipRequery, SkipCache）

omni query run --body '{ "query": { ... }, "cache": "SkipCache" }'

undefined

omni query run --body '{ "query": { ... }, "cache": "SkipCache" }'

undefined

AI-Powered Query Generation

基于AI的查询生成

Instead of constructing query JSON manually, you can describe what you want in natural language and let Omni's AI generate the query.

无需手动构建查询JSON，你可以用自然语言描述需求，让Omni的AI生成查询。

Generate Query (synchronous)

生成查询（同步）

The fastest path — returns a generated query JSON synchronously. Pass

--run-query false

to get only the query structure without executing it (default runs the query).

bash

undefined

最快的方式——同步返回生成的查询JSON。传递

--run-query false

仅获取查询结构而不执行（默认会运行查询）。

bash

undefined

Just generate the query JSON (no execution)

仅生成查询JSON（不执行）

omni ai generate-query your-model-id "Show me revenue by month" --run-query false


Response:

```json
{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
    "table": "order_items",
    "filters": {},
    "sorts": [{"column_name": "order_items.created_at[month]", "sort_descending": false}],
    "limit": 500
  },
  "topic": "order_items",
  "error": null
}

bash

undefined

omni ai generate-query your-model-id "Show me revenue by month" --run-query false


响应：

```json
{
  "query": {
    "fields": ["order_items.created_at[month]", "order_items.total_revenue"],
    "table": "order_items",
    "filters": {},
    "sorts": [{"column_name": "order_items.created_at[month]", "sort_descending": false}],
    "limit": 500
  },
  "topic": "order_items",
  "error": null
}

bash

undefined

Generate and execute in one call

生成并执行查询

omni ai generate-query your-model-id "Top 10 customers by lifetime spend"


Optional flags:
- `--branch-id` — test against a specific model branch
- `--current-topic-name` — constrain topic selection to a specific topic

omni ai generate-query your-model-id "Top 10 customers by lifetime spend"


可选参数：
- `--branch-id` —— 在特定模型分支上测试
- `--current-topic-name` —— 将主题选择限制为特定主题

Pick Topic

选择主题

Check which topic the AI would select for a question, without generating a full query:

bash

omni ai pick-topic your-model-id "How many users signed up last month?"

查看AI会为问题选择哪个主题，无需生成完整查询：

bash

omni ai pick-topic your-model-id "How many users signed up last month?"

Agentic Queries (async)

智能代理查询（异步）

For the full Blobby experience — multi-step analysis, tool use, and topic selection as the AI would actually behave in production. This is async: submit a job, poll for status, then retrieve the result.

bash

undefined

体验完整的Blobby功能——多步骤分析、工具使用以及AI在生产环境中的实际主题选择逻辑。此方式为异步：提交任务、轮询状态、然后获取结果。

bash

undefined

1. Submit a job

1. 提交任务

omni ai job-submit your-model-id "Analyze revenue trends and identify our fastest growing product category"

→ returns { "jobId": "job-uuid", "conversationId": "conv-uuid" }

→ 返回 { "jobId": "job-uuid", "conversationId": "conv-uuid" }

2. Poll for completion (QUEUED → EXECUTING → COMPLETE)

2. 轮询完成状态（QUEUED → EXECUTING → COMPLETE）

omni ai job-status <jobId>

3. Get the result

3. 获取结果

omni ai job-result <jobId>


The result contains an `actions` array with each step the AI took — look for actions with `type: "generate_query"` to extract the generated queries. The response also includes `resultSummary` with the AI's narrative interpretation.

Additional job commands:
- `omni ai job-cancel <jobId>` — cancel a running job
- `omni ai job-visualization <jobId>` — get the visualization output

omni ai job-result <jobId>


结果包含`actions`数组，记录AI执行的每个步骤——查找`type: "generate_query"`的操作以提取生成的查询。响应还包含`resultSummary`，即AI生成的叙述性解读。

其他任务命令：
- `omni ai job-cancel <jobId>` —— 取消正在运行的任务
- `omni ai job-visualization <jobId>` —— 获取可视化输出

When to Use Which Approach

不同方式的适用场景

Approach	Best For
`omni query run`	You know exactly which fields, filters, and sorts you need
`omni ai generate-query`	Translating a natural language question into a single query
`omni ai job-submit`	Complex questions that may need multiple queries or multi-step reasoning

方式	最佳适用场景
`omni query run`	明确知道所需的字段、筛选条件和排序规则
`omni ai generate-query`	将自然语言问题转换为单个查询
`omni ai job-submit`	可能需要多个查询或多步骤推理的复杂问题

Multi-Step Analysis Pattern

多步骤分析模式

For complex analysis, chain queries:

Broad query — understand the shape of the data
Inspect results — identify interesting segments or patterns
Focused follow-ups — filter based on findings
Synthesize — combine results into a narrative

对于复杂分析，可链式执行查询：

宽泛查询——了解数据的整体结构
检查结果——识别有趣的细分或模式
针对性跟进查询——基于发现设置筛选条件
综合分析——将结果整合为叙述性结论

Common Query Patterns

常见查询模式

Time Series: fields + date dimension + ascending sort + date filter

Top N: fields + metric + descending sort + limit

Aggregation with Breakdown: multiple dimensions + multiple measures + descending sort by key metric

时间序列：字段 + 日期维度 + 升序排序 + 日期筛选

Top N分析：字段 + 度量指标 + 降序排序 + 行数限制

带细分的聚合：多个维度 + 多个度量 + 按关键指标降序排序

Known Bugs

已知Bug

IS_NOT_NULL
filter generates
IS NULL
(reported Omni bug) — workaround: invert the filter logic or use the base view to apply the filter differently.
Boolean filters may be silently dropped when a
```
pivots
```
array is present — if boolean filters aren't applying, remove the pivot and test again.

IS_NOT_NULL
筛选条件生成
IS NULL
（已上报Omni的bug）——解决方法：反转筛选逻辑，或使用基础视图以不同方式应用筛选条件。
当存在
pivots
数组时，布尔筛选条件可能被静默忽略——若布尔筛选条件未生效，请移除透视并重新测试。

Linking to Results

结果链接

Queries are ephemeral — there is no persistent URL for a query result. To give the user a shareable link:

For existing dashboards:
```
{OMNI_BASE_URL}/dashboards/{identifier}
```
(the
```
identifier
```
comes from the document API response)

For new analysis: Create a document via

omni-content-builder

with the query as a

queryPresentation

, then share

{OMNI_BASE_URL}/dashboards/{identifier}

查询是临时的——查询结果没有持久化URL。若要为用户提供可分享的链接：

对于现有仪表板：
```
{OMNI_BASE_URL}/dashboards/{identifier}
```
（
```
identifier
```
来自文档API响应）

对于新分析：通过

omni-content-builder

创建文档，将查询作为

queryPresentation

，然后分享

{OMNI_BASE_URL}/dashboards/{identifier}

Docs Reference

文档参考

Query API · Running Document Queries · Querying Documentation · Filter Syntax

Query API · Running Document Queries · Querying Documentation · Filter Syntax