#筛选（QueryType）

QueryType 描述 Logicform 的过滤条件，语法与 MongoDB 查询基本一致，可同时出现在根节点（影响整条查询）或 PredItemType.query（仅作用于某个指标）。同一套结构也会复用于 having，但 having 的字段名基于结果列别名，而不是原始 schema 字段。

#值类型

QueryType 的值不只可以是普通标量，还可以是：

• 标量：string、number、boolean、null
• 数组：常用于 $in / $nin
• 时间值：绝对时间、结构化时间、相对时间、MTD/YTD/QTD/WTD
• 子查询：完整的 LogicformType 或 LogicformType[]

#基本语法

{
  "query": {
    "渠道": "自营",
    "地区": { "$in": ["华东", "华北"] },
    "GMV": { "$gte": 1000000 }
  }
}

上述结构等价于 SQL WHERE 渠道='自营' AND 地区 IN (...) AND GMV >= 1000000。

query 的 key 也可以写成带下划线的跨表字段路径，例如 门店_地理位置、物料_品牌_品类。这类路径的规则见 基础结构 中的“跨表字段路径”。

#支持的操作符

常用组合写法如 { 销售额: { "$gt": 100, "$lte": 1000 } }。

#逻辑组合示例

{
  "query": {
    "$and": [
      { "渠道": "自营" },
      {
        "$or": [
          { "地区": "华东" },
          { "地区": "华北" }
        ]
      }
    ],
    "门店": { "$exists": true }
  }
}

#子查询

某些条件需要通过子查询才能表达，此时应把完整的 LogicformType 嵌入值中，而不是只写 operator/pred 片段。

#标量子查询

{
  "query": {
    "GMV": {
      "schema": "sales",
      "preds": [
        { "name": "max_gmv", "operator": "$max", "pred": "amount" }
      ]
    }
  }
}

可理解为：GMV = (SELECT MAX(amount) FROM sales)。

#集合子查询

{
  "query": {
    "客户ID": {
      "$in": {
        "schema": "orders",
        "query": { "日期": "YTD" },
        "preds": [
          { "pred": "客户ID", "name": "客户ID" }
        ]
      }
    }
  }
}

可理解为：客户ID IN (SELECT 客户ID FROM orders WHERE 日期 ... )。

#时间筛选

#标准范围写法

{
  "日期": {
    "$gte": "2024-01-01 00:00:00",
    "$lte": "2024-01-31 23:59:59"
  }
}

#结构化时间

{
  "日期": {
    "year": 2024,
    "month": 1
  }
}

你可以混用粒度，例如只指定 year/month/day 中的一部分。

#相对时间

{
  "日期": {
    "$offset": { "year": -1 },
    "month": 10
  }
}

该示例表示“去年 10 月”。支持的 offset 粒度包含 year、quarter、month、week、day、hour、minute、second。

#To-date 简写

{
  "日期": "YTD"
}

支持的 to-date 简写包括 MTD、QTD、YTD、WTD。

#带 $options 的时间条件

{
  "日期": {
    "$gte": "2025-01-01 00:00:00",
    "$lte": "2025-08-12 23:59:59",
    "$options": "YTD"
  }
}

$options 是辅助选项字段。在日期场景中，常用于补充 YTD/MTD/QTD/WTD 这类口径；在其他场景下也可能被底层执行器用于正则等高级选项。

#局部时间与高级写法

{
  "日期": {
    "$month": 10
  }
}

{
  "日期": {
    "period": "am"
  }
}

此外，结构化时间值还支持 $functions 字段，用于挂载额外时间函数；具体函数名和参数由执行器或算子定义。

#最佳实践

1. 所有字段名均为业务建模中配置的“展示名称”，保持与业务口径一致。
2. 当 query 同时存在于根节点和 pred 中时，两处条件作用范围不同，执行时会分别下推。
3. 建议在同一个 Logicform 中保持时间粒度一致，避免大模型自动补充不符合预期的时间范围。
4. 需要子查询时，请传入完整的 LogicformType，不要把 PredItemType 误当成子查询结构。