过滤器查询参考

watsonx Assistant 服务 REST API 通过过滤器查询，提供功能强大的日志搜索功能。您可以使用 v2 /logs API filter 参数在技能日志中搜索符合指定查询的事件。

filter 参数是一个可缓存的查询，可将结果限制为符合指定过滤条件的条目。可以过滤属于 JSON 响应模型的各种对象（例如，用户输入文本、检测到的意向和实体或置信度分数）。

要查看过滤器查询的示例，请参阅示例。

如需了解 /logs GET 方法及其响应模型的更多信息，请参阅 API参考。

过滤器查询语法

以下示例显示过滤器查询的一般格式：

地区	查询运算符	术语
`request.input.text`	`::`	`"IBM Watson"`

_该位置_标识了您要过滤的字段（在此示例中为 request.input.text ）。
查询操作符，用于指定匹配类型（模糊匹配或精确匹配）。
_该术语_指定了用于评估字段匹配的表达式或值。项可以包含字面值文本和运算符，如下一节中所述。

按意图或实体进行过滤所需的语法与其他字段略有不同。有关更多信息，请参阅按意向或实体过滤。

**注：**过滤器查询语法使用了 HTTP 查询中不允许的一些字符。请确保在作为 HTTP 查询的一部分发送时，对所有特殊字符（包括空格和引号）都进行了 URL 编码。例如，过滤器 response_timestamp<2020-01-01 将被指定为 response_timestamp%3C2020-01-01。

操作程序

可以在过滤器查询中使用以下运算符。

运算符	描述
`:`	模糊匹配查询运算符。如果要匹配包含查询项或查询项语法变体的任何值，请使用 `:` 作为查询项的前缀。模糊匹配可用于用户输入的文本和实体值。
`::`	完全匹配查询运算符。如果要仅匹配完全等于查询项的值，请使用 `::` 作为查询项的前缀。
`:!`	否定模糊匹配查询运算符。如果您只想匹配_不包含_查询词或查询词语法变体的值，请在查询词前加上 `:!`。
`::!`	否定完全匹配查询运算符。如果您只想匹配_与查询词不完全匹配的_值，请在查询词前加上 `::!`。
`<=`, `>=`, `>`, `<`	比较运算符。要基于算术比较进行匹配，请使用这些运算符作为查询项的前缀。
``	转义运算符。用于包含控制字符的查询，不然这些控制字符会解析为运算符。例如，`!hello` 与文本 `!hello` 匹配。
`""`	字面值短语。用于包含空格或其他特殊字符的查询词。 API 不会解析引号括起的特殊字符。
`~`	近似匹配。将后跟 `1` 或 `2` 的此运算符附加到查询项末尾，以指定允许查询字符串与响应对象中的匹配项之间的单字符差异数。例如，`car~1` 将与 `car`、`cat` 或 `cars` 匹配，但不会与 `cats` 匹配。当您对 `log_id` 或任何日期或时间字段进行过滤或模糊匹配时，此操作无效。
`*`	通配符运算符。与零个或零个以上字符组成的任意序列匹配。当您按 `log_id`，`language`，`request.context.system.assistant_id`，`workspace_id`，`request.context.metadata.deployment` 或任何日期或时间字段进行过滤时，此运算符无效。
`()`, `[]`	分组运算符。用于通过布尔运算符对多个表达式进行逻辑分组。
`\|`	布尔_或_运算符。
`,`	布尔_和_运算符。

按意向或实体过滤

由于意图和实体在内部存储方式不同，用于过滤特定意图或实体的语法与返回的 JSON 中其他字段的语法不同。要在intent或entity集合内指定intents或entities字段，必须使用 : 匹配运算符，而不是使用点。

例如，以下查询匹配的记录事件是，响应包含检测到的名为 hello 的意向：

response.output.intents:intent::hello

请注意，: 运算符代替了点 (intents:intent)

使用同一模式可匹配响应中检测到的意向或实体的任何字段。例如，以下查询匹配的记录事件是，响应包含检测到的值为 soda 的实体：

response.output.entities:value::soda

同样，您可以过滤请求中发送的意图或实体，如下例所示：

request.input.intents:intent::hello

按其他字段过滤

要在日志数据的另一个字段上进行过滤，请将位置指定为路径，以识别来自/logs API的JSON响应中嵌套对象的层级。使用点 (.) 来指定 JSON 数据中的后续嵌套级别。例如，request.input.text 标识用户输入文本字段，如下面的 JSON 片段所示：

  "request": {
    "input": {
      "text": "Good morning"
    }
  }

过滤并不是可用于所有字段。可以对以下字段进行过滤：

assistant_id
customer_id
language
request.context.global.system.user_id
request.input.text
request_timestamp
response.context.global.system.user_id
response.output.entities
response.output.intents
response_timestamp
session_id
skill_id
snapshot

目前不支持对其他字段进行过滤。

示例

以下示例说明了使用这种语法进行各种查询。

描述	查询
响应日期为 2020 年 7 月。	`response_timestamp>=2020-07-01,response_timestamp<2020-08-01`
响应的时间戳记早于 `2019-11-01T04:00:00.000Z`。	`response_timestamp<2019-11-01T04:00:00.000Z`
消息标注有客户标识 `my_id`。	`customer_id::my_id`
消息已发送给特定助手。	`assistant_id::dcd5c5ad-f3a1-4345-89c5-708b0b5ff4f7`
用户输入文本包含单词“order”或语法变体（例如，`orders` 或 `ordering`）。	`request.input.text:order`
响应中的意向名称与 `place_order` 完全匹配。	`response.output.intents:intent::place_order`
响应中的实体名称与 `beverage` 完全匹配。	`response.output.entities:entity::beverage`
回复中的名字与 `order` 不匹配。	`response.intents:intent::!order`
用户输入文本不包含单词“order”或语法变体。	`request.input.text:!order`
用户输入文本包含字符串 `!hello`。	`request.input.text:!hello`
用户输入文本包含字符串 `IBM Watson`。	`request.input.text:"IBM Watson"`
用户输入文本包含的字符串与 `Watson` 的差异不超过 2 个单字符。	`request.input.text:Watson~2`
用户输入的文本包含一个由 `comm` 组成的字符串，后面跟着零个或多个字符，再后面跟着 `s`。	`request.input.text:comm*s`
响应中的意向名称与 `hello` 或 `goodbye` 完全匹配。	`response.output.intents:intent::(hello\|goodbye)`
响应中的意向名称与 `order` 完全匹配，并且响应中的实体名称与 `beverage` 完全匹配。	`[response.output.intents:intent::order,response.output.entities:entity::beverage]`

过滤 V1 日志

如果您的应用程序仍在使用 v1，则可以使用 v1查询和过滤日志。过滤语法是相同的，但 V1 日志和消息请求的结构是不同的。有关更多信息，请参阅 API 参考。

使用 V1 /logs API，可以过滤以下字段：

language
meta.message.entities_count
request.context.metadata.deployment
request.context.system.assistant_id
request.input.text
response.context.conversation_id
response.entities
response.input.text
response.intents
response.top_intent
workspace_id

目前不支持对其他字段进行过滤。