diff --git a/internal/export/doc/en/datakit-filter.md b/internal/export/doc/en/datakit-filter.md index 309dfdac6b..4d3f210a27 100644 --- a/internal/export/doc/en/datakit-filter.md +++ b/internal/export/doc/en/datakit-filter.md @@ -131,17 +131,22 @@ Support basic numerical comparison operations: { service = re('.*') AND ( abc IN [1,2,'foo', 2.3] OR def MATCH ['foo.*', 'bar.*']) } ``` +- Built-in constants + + - `true/false` + - `nil/null`: null value, see following usage about them + In addition, the following list operations are supported: -| Operator | Support Numeric Types | Description | Example | -| ---- | ---- | ---- | ---- | -| `IN`, `NOTIN` | Numeric list | Whether the specified field is in a list, and multi-type cluttering is supported in the list | `{ abc IN [1,2, "foo", 3.5]}` | +| Operator | Support Numeric Types | Description | Example | +| ---- | ---- | ---- | ---- | +| `IN`, `NOTIN` | Numeric list | Whether the specified field is in a list, and multi-type cluttering is supported in the list | `{ abc IN [1,2, "foo", 3.5]}` | | `MATCH`, `NOTMATCH` | Regular expression list | Whether the specified field matches the regular in the list, which only supports string types | `{ abc MATCH ["foo.*", "bar.*"]}` | ???+ attention - **Only ordinary data types** such as string, integer, floating point can appear in the list. Other expressions are not supported. + - **Only ordinary data types** such as string, integer, floating point can appear in the list. Other expressions are not supported. The keywords `IN/NOTIN/MATCH/NOTMATCH` **are case insensitive**, meaning `in`, `IN` and `In` have the same effect. In addition, other operands are case sensitive, for example, the following filters express different meanings: @@ -152,8 +157,34 @@ In addition, the following list operations are supported: ``` In data point, all fields of **and their values are case-sensitive**. + + - Identity/Non-identity Expression Syntax: + + ```python + # Identity + { 1 == 1} + { 'abc' == 'abc'} + + # Non-identity + { true != false } + { 'abc' != 'ABC' } # String comparison is case-sensitive + ``` + +### Usage of nil/null {#nil} + +`nil/null` is used to indicate the non-existence of certain fields, and can be used in `=/!=/IN/NOTIN` operations: + +```python +{ some_tag_or_field != nil } # The field exists +{ some_tag_or_field = nil } # The field does not exist +{ some_tag_or_field IN ["abc", "123", null] } # The field either does not exist or can only equal specified values +{ some_tag_or_field NOTIN ["abc", "123", null] } # The field is not null and not equal to specified values +``` + +Here, `nil/null` is not case sensitive and can be written in various forms such as `NULL/Null/NIL/Nil`. + ## Usage Example {#usage} You can view the filtering using the `datakit monitor -V` command: diff --git a/internal/export/doc/zh/datakit-filter.md b/internal/export/doc/zh/datakit-filter.md index 5292875e9a..636521285b 100644 --- a/internal/export/doc/zh/datakit-filter.md +++ b/internal/export/doc/zh/datakit-filter.md @@ -139,7 +139,12 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛 { service = re('.*') AND ( abc IN [1,2,'foo', 2.3] OR def MATCH ['foo.*', 'bar.*']) } ``` -除此之外,还支持如下列表操作: +- 内置常量 + + - `true/false` + - `nil/null`: 空值,见下文说明 + +- 匹配和列表操作 | 操作符 | 支持数值类型 | 说明 | 示例 | | ---- | ---- | ---- | ---- | @@ -149,7 +154,7 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛 ???+ attention - 列表中**只能出现普通的数据类型**,如字符串、整数、浮点,其它表达式均不支持。 + - 列表中**只能出现普通的数据类型**,如字符串、整数、浮点,其它表达式均不支持。 `IN/NOTIN/MATCH/NOTMATCH` 这些关键字**大小写不敏感**,即 `in` 和 `IN` 以及 `In` 效果是一样的。除此之外,其它操作数的大小写都是敏感的,比如如下几个过滤器表达的意思不同: @@ -160,8 +165,33 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛 ``` 在数据点中,**所有字段以及其值都是大小写敏感的**。 + + - 恒等/恒不等表达式写法: + + ```python + # 恒等 + { 1 = 1} + { 'abc' = 'abc'} + + # 恒不等 + { true = false } + { 'abc' = 'ABC' } # 字符串大小写敏感 + ``` +### nil/null 用法 {#nil} + +`nil/null` 用于表示某些字段不存在,我们可以在 `=/!=/IN/NOTIN` 操作中使用: + +```python +{ some_tag_or_field != nil } # 某个字段存在 +{ some_tag_or_field = nil } # 某个字段不存在 +{ some_tag_or_field IN ["abc", "123", null] } # 某个字段要么不存在,要么只能等于指定的值 +{ some_tag_or_field NOTIN ["abc", "123", null] } # 某个字段不为 null 且不为指定的值 +``` + +此处 `nil/null` 不区分大小写,我们可以写成 `NULL/Null/NIL/Nil` 等多种形式。 + ## 用法示例 {#usage} 使用 `datakit monitor -V` 命令可以查看过滤情况: