Skip to content

Commit

Permalink
Doc filter nil op
Browse files Browse the repository at this point in the history
  • Loading branch information
谭彪 committed Sep 25, 2024
1 parent 97d9322 commit f2604a6
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 6 deletions.
39 changes: 35 additions & 4 deletions internal/export/doc/en/datakit-filter.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.*"]}` |

<!-- markdownlint-disable MD046 -->
???+ 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:

Expand All @@ -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
```

<!-- markdownlint-enable -->

### 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:
Expand Down
34 changes: 32 additions & 2 deletions internal/export/doc/zh/datakit-filter.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,7 +139,12 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛
{ service = re('.*') AND ( abc IN [1,2,'foo', 2.3] OR def MATCH ['foo.*', 'bar.*']) }
```

除此之外,还支持如下列表操作:
- 内置常量

- `true/false`
- `nil/null`: 空值,见下文说明

- 匹配和列表操作

| 操作符 | 支持数值类型 | 说明 | 示例 |
| ---- | ---- | ---- | ---- |
Expand All @@ -149,7 +154,7 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛
<!-- markdownlint-disable MD046 -->
???+ attention

列表中**只能出现普通的数据类型**,如字符串、整数、浮点,其它表达式均不支持。
- 列表中**只能出现普通的数据类型**,如字符串、整数、浮点,其它表达式均不支持。

`IN/NOTIN/MATCH/NOTMATCH` 这些关键字**大小写不敏感**,即 `in` 和 `IN` 以及 `In` 效果是一样的。除此之外,其它操作数的大小写都是敏感的,比如如下几个过滤器表达的意思不同:

Expand All @@ -160,8 +165,33 @@ Filter 的主要功能就是数据筛选,其筛选依据是通过一定的筛
```

在数据点中,**所有字段以及其值都是大小写敏感的**。

- 恒等/恒不等表达式写法:

```python
# 恒等
{ 1 = 1}
{ 'abc' = 'abc'}

# 恒不等
{ true = false }
{ 'abc' = 'ABC' } # 字符串大小写敏感
```
<!-- markdownlint-enable -->

### 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` 命令可以查看过滤情况:
Expand Down

0 comments on commit f2604a6

Please sign in to comment.