用途：通过 Omni CLI 对 Omni Analytics 的语义层发起查询，用维度、度量、筛选等语义元素描述需求，由 Omni 翻译为优化 SQL，并解读与串联结果完成多步分析。若不清楚可用主题与字段，建议先用 omni-model-explorer。
前提：需安装 Omni CLI（参见 https://github.com/exploreomni/cli#readme）。用 command -v omni 检查安装；用 omni config show 查看并选择 profile，多个时询问用户后用 omni config use <profile-name> 切换；用 omni whoami whoami 确认认证与权限。401 时请用户执行 omni config login <profile>（OAuth 2.1 浏览器流程），不要在无头/CI 会话自行登录。还需模型 ID 与可用主题、字段信息。
用法：omni query --help、omni query run --help、omni query run --schema 查看命令；用 -o json 强制结构化输出。查询建议基于主题构建，设 table 为主题基础视图并传 join_paths_from_topic_name；查询需在 query 内包含 modelId，结果类型 resultType 放顶层。字段用 view.field 形式，日期支持 [date]/[week]/[month] 等 timeframe。筛选须用带类型的对象（type/kind/values），布尔用 is_negative；不要用裸字符串简写。表计算写在 calculations[]，其 calc_name 还须出现在 query.fields。
限制：非主题路径（裸基础视图、userEditedSQL 原始 SQL）不应用主题级行级访问过滤与 always_where，原始 SQL 还会绕过对象级权限，仪表盘中对受限角色默认不可见。透视查询不允许 limit: null。计算列若为空应视为失败排查；保持 swallow_errors: false 以暴露真实错误。