filterql-builder

FilterQL 构建器

用途

将结构化条件转换为有效的 FilterQL 语法。接收包含 AND/OR 分组的字段/运算符/值元组，并生成语法正确的 FilterQL 字符串。

环境

• 无需配置（纯构建，不调用 API）

输入

• 条件：由（字段、运算符、值）元组组成的列表
• 分组：AND/OR/NOT 组合
• 表：目标表（默认值：user）
• 别名：片段 slug 名称

行为

第 1 步：将每个条件映射为 FilterQL 语法

对于每个条件，请使用 ../references/field-types.md 中的类型与运算符兼容性矩阵：

字段类型	自然语言	FilterQL
string	等于 "X"	field = "X"
string	不等于 "X"	field != "X"
string	包含 "X"	field CONTAINS "X"
string	匹配模式	field LIKE "pattern*"
string	A、B、C 中的一个	field IN ("A", "B", "C")
bool	为 true	field = true
bool	为 false	field = false
int/number	大于 N	field > N
int/number	大于或等于 N	field >= N
int/number	小于 N	field < N
date	晚于 N 天前	field > "now-Nd"
date	早于 N 天前	field < "now-Nd"
date	过去 N 小时内	field > "now-Nh"
[]string（集合）	有 "X"	field INTERSECTS ("X")
[]string（集合）	没有 "X"	field NOT INTERSECTS ("X")
任意	有任意值	EXISTS field
任意	为空	NOT EXISTS field

第 2 步：组合条件

使用 AND/OR/NOT 包装条件：

FILTER AND (
  condition1,
  condition2,
  OR (condition3, condition4)
) FROM table ALIAS slug_name

规则：

• 单个条件：FILTER condition FROM table ALIAS slug
• 多个条件默认使用 AND
• NOT 可以包装任意单个条件或分组
• AND/OR 分组必须使用括号
• 分组内的条件以逗号分隔

第 3 步：生成 Slug 名称

将别名转换为有效的 slug：

• 转为小写
• 将空格替换为下划线
• 移除特殊字符
• 保持描述清晰且简洁

第 4 步：输出

返回完整的 FilterQL 字符串：

FILTER AND (country = "US", visitct > 5) FROM user ALIAS us_active_visitors

日期计算参考

周期	语法	示例
小时	"now-Nh"	"now-24h" = 1 天前
天	"now-Nd"	"now-30d" = 30 天前
周	"now-Nw"	"now-4w" = 4 周前
月	"now-NM"	"now-6M" = 6 个月前
年	"now-Ny"	"now-1y" = 1 年前

常见换算：

• 1 年 = "now-1y" 或 "now-8760h" 或 "now-365d"
• 90 天 = "now-90d" 或 "now-2160h"
• 1 周 = "now-1w" 或 "now-7d" 或 "now-168h"

错误处理

• 如果字段类型与请求的运算符不兼容，请建议正确的运算符
• 如果值包含引号，请对其进行转义
• 如果 FilterQL 语法无效，请找出并修复问题

依赖项

• 参考资料：../references/filterql-grammar.md、../references/field-types.md