字段查找规则

字段查找规则
查找通过匹配添加查找表中的字段来丰富您的搜索数据，字段查找规则可以定义基于csv文件、外部脚本及KV存储类型的查找，需要定义查找表中的信息以及该信息如何与事件数据中的字段相匹配。一个查找表可以配置多个查找规则。创建查找规则后，您可以在搜索中调用lookup命令进行查找。

CSV查找规则

CSV类型的字段查找规则基于csv静态文件，需要上传csv查找表文件并基于该文件创建查找规则，通常情况下适用于数据量较小且相对静态的查找源，通过匹配事件数据中的字段和表文件中的字段，将csv表文件中对应的字段值输出到事件中。

创建CVS查找规则

CSV查找规则的创建流程如下：
1、点击设置 > 查找管理 > 查找规则进入查找规则管理列表；
2、点击新建按钮配置查找规则，选择匹配类型为CSV文件，具体配置如下：

3、点击保存完成基于CSV文件的查找规则的创建，可以在查找规则列表中进行查看，默认权限为个人所有。

P.s.在配置基于CSV文件的查找规则前，您需要先上传用于匹配查找的csv表文件，并将该表文件访问权限设置为在APP内或全局范围共享。

配置CSV查找规则权限

完成查找规则的创建后，可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用，具体配置步骤如下：

1. 点击设置—>查找管理—>查找规则进入查找规则管理列表；
2. 在列表中选择要配置权限的查找规则，点击授权按钮。
3. 在“设置权限”配置框中，选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限；
4. 点击保存完成权限配置。

注：查找表文件的权限必须等同于或高于使用这些文件的查找规则的权限。

KV存储查找规则

KV存储查找规则可以将APP中KV存储数据表里的字段进行查找并输出至您的事件数据中，完成查找规则定义后使用lookup，inputlookup，及outputlookup算子进行调用，KV存储查找规则通常适用于更新频率较高或者较大的lookup表。
创建基于KV存储的查找规则具体配置步骤如下：
1、创建KV存储数据表。KV存储表将您的数据存储为键值对。创建KV存储查找时，数据表至少包含两个字段，其中一个字段作为输入字段与搜索数据中字段进行匹配。当在搜索中调用lookup命令进行查找时指定输入匹配字段，当事件中输入字段值与KV存储表中指定字段的值匹配时，该KV存储表中其他对应字段的值将输出到搜索数据中。用户可以使用API进行创建数据表、插入数据、查询数据、删除数据、修改数据等数据管理操作；
2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表；
3、点击新建按钮配置查找规则，选择匹配类型为KV存储，具体配置如下：

4、点击保存完成基于KV存储的查找规则的创建，可以在查找规则列表中进行查看，默认权限为个人所有。

KV存储查找对比CSV文件查找
CSV文件：

• 适用于小文件或较少修改数据的文件
• 支持区分大小写的字段查找
• 更易于手动修改- 需要完全重写文件以进行编辑操作
• 不支持REST API访问

KV存储：

• 支持针对单条记录的更新
• 不支持不区分大小写的字段查找
• 支持 REST API 访问

配置外部脚本查找规则权限

完成查找规则的创建后，可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用，具体配置步骤如下：

1. 点击设置 > 查找管理 > 查找规则进入查找规则管理列表；
2. 在列表中选择要配置权限的查找规则，点击授权按钮。
3. 在“设置权限”配置框中，选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限；
4. 点击保存完成权限配置。

外部脚本查找规则

定义基于外部脚本的查找规则后，在执行查找时调用外部脚本，可以使用python脚本或二进制可执行文件来匹配查找外部源查找表的字段，并输出到搜索数据中。具体脚本实现参见查找外部脚本。
创建外部脚本查找规则具体配置步骤如下：
1、编辑查找脚本，如pisatest.py，并将脚本添加到./app/{app_name}/bin目录下；
2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表；
3、点击新建按钮配置查找规则，选择匹配类型为外部脚本，具体配置如下：

4、点击保存完成基于外部脚本的查找规则的创建，可以在查找规则列表中进行查看，默认权限为个人所有。

配置外部脚本查找规则权限

完成查找规则的创建后，可以针对具体查找规则配置权限来定义可以在哪些应用范围内共享给哪些用户角色使用，具体配置步骤如下：

1. 点击设置 > 查找管理 > 查找规则进入查找规则管理列表；
2. 在列表中选择要配置权限的查找规则，点击授权按钮。
3. 在“设置权限”配置框中，选择在APP内或者全局范围内哪些用户角色可以对该查找规则进行查看/访问、编辑或删除权限；
4. 点击保存完成权限配置。

外部查找脚本

外部脚本可以是Python脚本或二进制可执行脚本（如C++可执行文件），脚本中定义如何获取外部源数据作为查找表。外部脚本必须以csv表的格式输入输出数据，传递的脚本参数是输入输出csv表的表头。
以DNS_lookup为例，定义一个外部脚本来创建一个lookup表，里面包括clienthost，clientip字段。csv表中数据如下：

clienthost,clientip
10.200.20.22,cs2
10.200.20.39,cs19
...,...

点击下载dns示例脚本

注：当脚本中引用了CSV文件，文件路径必须相对于脚本所在的目录。

脚本说明：

1. 需要引入 pdr_python_sdk，并继承 SplStreamingBatchCommand
2. init_env_by_getinfo 方法初始化 csv 文件表头信息，如 clienthost,clientip
3. streaming_handle 方法对传入的 csv 文件内容 lines 进行填充，可以自定义逻辑，如输入：

cs2,
cs19,

输出：

cs2,10.200.20.22
cs19,10.200.20.39

自动查找

手动查找配置完成后需要在搜索中调用lookup命令运行。配置自动查找，则查找在每次搜索时针对相应搜索数据自动运行，无需使用lookup命令。
在查找规则配置时勾选自动查找，具体配置如下：

避免自动查找引用循环

在配置自动查找时，当查找的输入/输出字段在同一查找规则或相关查找规则间中被重复引用时，可能会发生引用循环。在对应搜索时您将收到自动查找定义的查找引用循环的错误提示。
例如，以下自动查找规则设置会导致引用循环：

• 在事件中用于匹配的输入字段与输出字段名相同，如输入和输出字段都是type。

    lookup_sales slaes_type as type ouputnew type

• 当定义两个或多个相关自动查找规则，输出字段留空时默认将查找表中所有不是匹配字段的字段作为输出字段，可能会遇到更复杂的引用循环。例如，多个查找组合后出现：f1 ← f3 ← f2 ← f1。
  例如，配置一个查找表fields（包含字段：f1，f2，f3，f4 ），设置以下两个基于fields查找表的自动查找规则：

    lookup_fields1 f1 as f2 ouput
    lookup_fields2 f1 as f3 ouputnew f4

时间查找

如果查找表中有时间字段，可以创建基于时间的字段查找，也称为时间查找，三种查找表类型都支持配置基于时间的查找。
基于时间的查找将数据搜索结果中的时间戳与查找表中的时间戳进行匹配，然后将匹配的数据添加到搜索结果中。用户还可以定义时间偏移范围，基于数据搜索结果中的时间定义匹配查找表的时间范围。
在查找规则配置时勾选时间查找，具体配置如下：

高级配置

支持编辑最小匹配数、最大匹配数、默认匹配、匹配类型、过滤条件等高级配置。具体配置如下：

查找示例

CSV文件查找示例

该示例中定义了一个基于CSV文件的lookup查找HTTP状态码，针对Web访问日志，用户可以基于查找表http_status.csv进行查找，该查找将事件中的http_status_code字段与查找表中对应列相匹配，在Web访问日志中输出相应的http_status_name和http_status_description字段。CSV表文件中内容示例：

点击下载该http_status_code.csv文件
使用步骤如下：
1、点击设置 > 查找管理 > 查找表文件进入查找表文件管理列表，创建CSV文件http_status.csv：选择目标应用，浏览选择对应CSV文件，选择提取方式，输入文件名称http_status后点击保存；

2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表，创建基于该CSV文件的查找规则http_status：选择目标应用，输入规则名称http_status，查找类型选择基于文件，选择前面创建的表文件http_status.csv，点击保存。

3、（可选）可以将查找配置为自动运行。勾选自动查找，将查找应用于sourcetype=Apache的数据上，输入字段配置为http_status_code > status_code（左侧输入框为csv表中字段，右侧输入框为搜索数据中字段），输出字段是查找表中要添加到事件中的字段：http_status_description > status_description（左侧输入框为csv表中要输出的字段，右侧输入框为要输出到搜索数据中的字段名）；
4、（可选）可以选择配置最小匹配数、最大匹配数、默认匹配、过滤条件等高级配置项；
5、定义查找后，可以在搜索中使用lookup命令调用它，例如运行以下搜索，在包含http_status_code字段的Apache访问日志access_log中添加http_status_description。

repo="apache"| lookup http_status http_status_code as status_code output http_status_description as status_description

外部脚本查找示例

该示例中定义了一个基于python脚本的查找规则DNS_lookup查找域名对应的IP地址。定义一个外部脚本来创建一个lookup表，里面包括clienthost，clientip字段。csv表中数据如下：

clienthost,clientip
10.200.20.22,cs2
10.200.20.39,cs19
...,...

点击下载示例脚本dns_lookup.py

注：当脚本中引用了CSV文件，文件路径必须相对于脚本所在的目录。

使用步骤如下：
1、编辑查找脚本，并将脚本dns_lookup.py添加到./app/search/bin目录下；
2、点击设置 > 查找管理 > 查找规则进入查找规则管理列表，创建基于外部脚本的查找规则dns_lookup：选择目标应用，输入规则名称dns_lookup，查找类型选择基于外部脚本，输入脚本命令及支持字段clienthost,clientip，点击保存。
3、（可选）可以将查找配置为自动运行。勾选自动查找，将查找应用于sourcetype=_internal的数据上，输入字段配置为clienthost > clienthost（左侧输入框为csv表中字段，右侧输入框为搜索数据中字段），输出字段是查找表中要添加到事件中的字段clientip > clientip（左侧输入框为csv表中要输出的字段，右侧输入框为要输出到搜索数据中的字段名）；
4、（可选）可以选择配置最小匹配数、最大匹配数、默认匹配、过滤条件等高级配置项；
5、定义查找后，可以在搜索中使用lookup命令调用它，例如运行以下搜索，在包含host字段的日志中添加ip。

repo="_internal"| lookup dns_lookup clienthost as host output clientip as ip