# 模型查询 API

本文档所描述的内容属于 TA 的高级使用功能，涉及较多技术细节，适用于对相关功能有经验的用户参考。如果对文档内容有疑惑，请咨询您的数据咨询顾问获取一对一的协助。

模型查询 API 主要用于获取各种数据分析报告。

请参见Open API文档中的调用方法描述。

# 一、通用参数

# 属性表达

几乎所有的 API 都会用到属性，例如按照某个属性进行过滤、分组或者聚合等等。属性包括事件属性，用户属性和用户分群属性，属性通常使用名称和表类型两个字段表达。例如表示省份这个事件属性的表达式如下:

{
    "tableType":"event",
    "columnName":"#province"
}

用户属性类似，例如表示用户级别:

{
    "tableType":"user",
    "columnName":"user_level"
}

# 筛选表达式

筛选表达式同样适用于绝大多数 API，用于表示对某些事件或者用户的筛选操作，使用如下格式的 JSON 表示:

{
  // 表示 filts 里的各个条件的关系是 或 还是 且
  "relation": "and",
  // 具体的条件列表，可以有多个
  "filts": [{
    // 条件的左值，是一个属性
    "tableType":"event",
    "columnName": "#os",
    // 条件的比较符，这里表示等于
    "comparator": "equal",
    // 条件的比较值，根据不同的比较符可以有一个或者多个
    "ftv": [
      "ios"
    ]
  },
  {
    "tableType":"user",
    "columnName":"user_level",
    "comparator": "equal",
    "ftv": [
      "5"
    ]
  }]
}

目前支持的操作符如下:

equal / notEqual

表示等于/不等于，对字符串、数值类型有效。如果 ftv 有多个，则相当于 In 或者 Not In。例如想筛选出来等级为 3 和 4 的用户:

{
    "tableType":"user",
    "columnName":"user_level",
    "comparator": "equal",
    "ftv": ["3","5"]
}

isTrue / isFalse

只对布尔类型有效。

isNull / notNull

某个属性是否有值，对字符串、数值类型有效。

include / notInclude

表示包含或不包含某个子串:

{
    "tableType":"user",
    "columnName":"channel",
    "comparator": "include",
    "ftv": ["应用宝"]
}

less / greater / range：表示小于/大于/小于且大于，其中 range 是前闭后闭的区间，对数值类型和时间类型有效。例如筛选物品剩余数量在 3 和 9 之间的所有事件:

{
    "tableType":"event",
    "columnName":"count_left",
    "comparator": "range",
    "ftv": [3, 9]
}

或者筛选所有最后登录时间在 2019-11-13 00:00~2019-11-23 00:00 之间的用户

{
    "tableType":"user",
    "columnName":"latest_login_time",
    "comparator": "range",
    "ftv":["2019-11-13 00:00","2019-11-23 00:00"]
}

regexMatch / notRegexMatch

正则匹配或者正则不匹配，只对字符串类型有效。

relativeCurrentBetween / relativeCurrentBefore

针对日期类型的操作符，分别表示相对当前时间在过去 N 天到过去 M 天之间/相对当前时间在过去 N 天之前。例如想筛选所有注册时间相对当前时间在过去 3 天之前的用户:

{
    "tableType":"user",
    "columnName":"register_time",
    "comparator": "relativeCurrentBefore",
    "ftv": [3]
}

或者筛选所有注册时间相对当前时间在过去 9 天到过去 3 天之间的用户:

{
    "tableType":"user",
    "columnName":"register_time",
    "comparator": "relativeCurrentBetween",
    "ftv": [9, 3]
}

relativeEventBefore / relativeEventAfter / relativeEventAbsolute

针对日期类型的操作符，分别表示相对事件发生时刻在之前 N 长时间之内/相对事件发生时刻在之后 N 长时间之内/相对事件发生时刻在前后 N 长时间之内。例如想筛选用户上次登录时间相对事件发生时刻在之前 3 个小时之内的事件:

{
    "tableType":"user",
    "columnName":"latest_login_time",
    "comparator": "relativeEventBefore",
    "ftv": [3],
    "timeUnit": "hour"
}

arrayIncludeItem / arrayNotIncludeItem

列表类型的操作符，表示列表是否包含某些元素

arrayItemPos

列表类型的操作符，表示列表第 n 个元素等于某个值

arrayIsNull / arrayNotNull

列表类型的操作符，表示列表是否存在