omni-query 用于通过 REST API 查询 Omni Analytics 的语义层。用户只需指定所需内容（维度、度量、过滤器），无需编写 SQL，由 Omni 将字段选择转换为优化后的 SQL。若不清楚可用主题与字段，建议先用 omni-model-explorer 探索。
使用前需设置环境变量 OMNI_BASE_URL 与 OMNI_API_KEY，并准备 model ID 及可用的主题、字段知识。当不确定端点或参数是否存在时，可获取 OpenAPI 规范进行核对。
核心用法是向 $OMNI_BASE_URL/api/v1/query/run 发送 POST 请求，查询对象包含 modelId、table、fields，并推荐提供 join_paths_from_topic_name；还可选 limit（默认 1000，最大 50000，null 为不限）、sorts、filters、pivots。字段采用 view_name.field_name 命名，日期字段支持 [date]、[week]、[month]、[quarter]、[year] 时间粒度。过滤器支持 “last 90 days”、“this quarter”、“between 10 and 100”、“contains sales” 等表达式。
结果默认返回 base64 编码的 Apache Arrow 表，无法直接解析行数据，可通过 summary.row_count 判断是否有数据；如需可读结果，可设置 resultType 为 csv。Arrow 结果可用 base64 与 pyarrow 解码为 DataFrame。若响应含 remaining_job_ids，可轮询 $OMNI_BASE_URL/api/v1/query/wait 等待完成。还支持从仪表盘提取查询、以指定用户身份运行以及设置缓存策略。
多步分析模式为：先做宽泛查询了解数据形态，检查结果找模式，再做聚焦的后续查询，最后综合成叙述。已知问题包括 IS_NOT_NULL 过滤器可能生成 IS NULL，以及存在 pivots 时布尔过滤可能被静默丢弃。查询结果本身没有持久化 URL，若要分享链接，可对已有仪表盘使用其标识，或通过 omni-content-builder 新建文档后再分享。