用途：通过 Omni Analytics 的 REST API 对语义层运行查询。你只需指定所需内容（维度、度量、过滤条件），Omni 会将其翻译为优化后的 SQL。若不清楚可用主题与字段，建议先用 omni-model-explorer。
前置条件：需要配置环境变量 OMNI_BASE_URL 与 OMNI_API_KEY，并准备模型 ID、可用主题和字段。不确定端点或参数是否存在时，可先获取 OpenAPI 规范：curl -L "$OMNI_BASE_URL/openapi.json" -H "Authorization: Bearer $OMNI_API_KEY"。
主要能力：运行查询 POST /api/v1/query/run，必填参数 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"、">100"、"between 10 and 100"、"contains sales" 等表达式。
结果处理：默认返回 base64 编码的 Apache Arrow 表，原始响应为二进制，无法逐行解析，可用 summary.row_count 判断是否有数据；如需人类可读结果，请求 resultType 为 csv。Arrow 结果可用 pyarrow 解码为 pandas DataFrame。若响应含 remaining_job_ids，可调用 POST /api/v1/query/wait 并传入 jobIds 轮询直至完成。
其他用法：可从仪表盘提取既有查询并重跑，使用 documents/{dashboardId}/queries 接口，支持以指定 userId 运行、通过 cache 参数跳过缓存。复杂分析可按“广查询—检查结果—聚焦追问—综合”的模式串联查询。查询是临时的，没有持久 URL；要分享可指向已有仪表盘或通过 omni-content-builder 创建文档后分享。
已知缺陷：IS_NOT_NULL 过滤会生成 IS NULL；存在 pivots 时布尔过滤器可能被静默丢弃。限制：需有效 API Key 与模型 ID，字段与主题需来自已有模型，未提供价格与配额信息。