PaginatedJsonQueryElasticsearch

文档中心 › 组件索引 › PaginatedJsonQueryElasticsearch

PaginatedJsonQueryElasticsearch Processor

类型全限定名:cn.org.acal.lynxus.processors.elasticsearch.PaginatedJsonQueryElasticsearch

所属 Bundle:cn.org.acal.lynxus:lynxus-elasticsearch-restapi-nar:2.11.8

描述

一个允许用户运行使用 Elasticsearch JSON DSL 编写的分页查询(带聚合)的处理器。除非 QUERY 属性已填充,否则将使用 FlowFile 的内容作为查询。Search After/Point in Time 查询必须包含有效的 'sort' 字段。

标签

elasticsearchelasticsearch7elasticsearch8elasticsearch9queryscrollpagereadjson

属性

下表中,加粗的属性为必填项;其余为可选项。表格同时标注默认值、是否支持表达式语言,以及是否为敏感属性(值会被加密)。

名称默认值可选值描述
Query Definition Stylefull
  • FULL_QUERY — 提供完整的查询。
  • BUILD_QUERY — 从单独的 JSON 对象构建查询。
如何定义 JSON 查询以供处理器使用。
QueryJSON 语法的查询,不是 Lucene 语法。例如:{"query":{"match":{"somefield":"somevalue"}}}。如果未设置此参数,将从 FlowFile 内容中读取查询。如果查询(属
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Query Clause使用 JSON 语法(而非 Lucene 语法)的 "query" 子句。例如:{"match":{"somefield":"somevalue"}}。如果查询为空,将使用默认的 JSON 对象,从而在 Elasticsearch 中产生 "match_all" 查询。
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Size查询中要检索的最大文档数。如果查询被分页,此「size」适用于查询的每一页,而不是整个结果集的「size」。
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Sort按一个或多个字段排序结果,JSON 语法。例如:[{"price" : {"order" : "asc", "mode" : "avg"}}, {"post_date" : {"format": "strict_date_optional_time_nanos"}}]
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
AggregationsJSON 语法中的一个或多个查询聚合(或「aggs」)。例如:{"items": {"terms": {"field": "product", "size": 10}}}
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Fields要检索的已索引文档的字段,JSON 语法。例如:["user.id", "http.response.*", {"field": "@timestamp", "format": "epoch_millis"}]
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Script Fields在查询运行时通过脚本评估创建的字段,JSON 语法。例如:{"test1": {"script": {"lang": "painless", "source": "doc['price'].value * 2"}}, "test2": {"script": {
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Query Attribute如果设置,则执行的查询将在指定属性中的每个结果 FlowFile 上设置。
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Index要使用的索引的名称。
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Type该文档的类型(Elasticsearch 用于索引和搜索)。
支持表达式语言:是(使用 FlowFile 属性与环境/系统变量求值)
Max JSON Field String Length20 MB解析 JSON 文档或属性时字符串值允许的最大长度。
Client Service控制器服务 API:
ElasticSearchClientService
cn.org.acal.lynxus-lynxus-elasticsearch-client-service-api-nar-2.11.8
用于运行查询的 Elasticsearch 客户端服务。
Search Results SplitsplitUp-no
  • PER_HIT — 每个 hit 一个 FlowFile。
  • PER_RESPONSE — 每个响应一个 FlowFile。
  • PER_QUERY — 合并所有查询响应的结果(整个分页 hit 结果集对应一个 FlowFile)。请注意,聚合无法分页,它们在整个结果集上生成,并作为第一页的一部分返回。结果以每行一个 JSON 对象的形式输出(允许在不将所有结果加载到内存的情况下合并来自多页的 hit)。
输出包含所有命中结果的 FlowFile,或为每个单独命中输出一个 FlowFile,或输出包含所有分页响应中所有命中结果的 FlowFile。
Search Results FormatFULL
  • FULL — 包含完整的 Elasticsearch Hit,含 Document Source 和 Metadata。
  • SOURCE_ONLY — 仅 Document Source(存在时)。
  • METADATA_ONLY — 仅 Hit Metadata。
Hits 输出的格式。
Aggregation Results SplitsplitUp-no
  • PER_HIT — 每个 hit 一个 FlowFile。
  • PER_RESPONSE — 每个响应一个 FlowFile。
输出包含所有聚合的 FlowFile 或每个单独聚合的一个 FlowFile。
Aggregation Results FormatFULL
  • FULL — 包含完整的 Elasticsearch 聚合,含 Buckets 和 Metadata。
  • BUCKETS_ONLY — 仅 Bucket 内容。
  • METADATA_ONLY — 仅聚合 Metadata。
聚合输出的格式。
输出无命中false
  • true
  • false
即使查询未找到命中,也输出 "hits" FlowFile。如果为 true,即使输出了 "aggregations",也将输出空的 "hits" FlowFile。
Pagination Typepagination-scroll
  • SCROLL — 使用 Elasticsearch "_scroll" API 对结果分页。不接受额外的查询参数。
  • SEARCH_AFTER — 使用 Elasticsearch "search_after" _search API 对排序结果分页。
  • POINT_IN_TIME — 使用 Elasticsearch(7.10+ 且带 XPack)"point in time" _search API 对排序结果分页。不可与 AWS OpenSearch 一起使用。
要使用的分页方法。并非所有类型都适用于所有 Elasticsearch 版本,请查看 Elasticsearch 文档以确认哪些适用于您的服务并推荐使用。
Pagination Keep Alive10 mins分页「keep_alive」周期。Elasticsearch 将在请求之间保持 scroll/pit 游标存活的时间段(这不是所有页面返回的预期时间,而是允许的最大时

动态属性

动态属性允许用户自定义属性的名称与值。

名称值描述
HTTP 请求头的名称用于检索 HTTP 请求头值的 Record Path 表达式前缀:HEADER: - 将指定的属性名称/值作为 HTTP 请求头添加到 Elasticsearch 请求中。如果 Record Path 表达式结果为 null 或空值,则将省略该 HTTP 请求头。
要添加的 URL 查询参数的名称URL 查询参数的值在用于处理的 Elasticsearch URL 中将指定的属性名称/值添加为查询参数。这些参数将覆盖查询请求体中任何匹配的参数。对于 SCROLL 类型的查询,这些参数仅在初始(第一页)查询中使用,因为 Elasticsearch Scroll API 不支持后续数据页使用相同的查询参数。

关系 (Relationships)

名称描述自动终止
aggregations聚合将路由到此关系。否
failure所有因与服务器可用性无关的原因而失败的 FlowFile 都会转至此关系。否
hits搜索命中将路由到此关系。否
original所有不会导致错误发生的原始 FlowFile 都会转到此关系。否

写入的 FlowFile 属性

名称描述
mime.type应用程序/json
aggregation.name结果位于输出 FlowFile 中的聚合的名称
aggregation.number结果在输出FlowFile中的聚合的数量
page.number页面(请求)的编号,从 1 开始,其中返回输出 FlowFile 中的结果
hit.count输出 FlowFile 中的命中数
elasticsearch.query.error如果查询索引出错,Elasticsearch 提供的错误消息。

状态管理

该组件不存储状态。

受限 (Restricted)

该组件不受限。

输入要求

该组件要求有传入连接。

系统资源考量

资源描述
MEMORY应注意每页的大小,因为 Elasticsearch 的每个响应将一次性全部加载到内存中并转换为结果 FlowFile。

详细说明

PaginatedJsonQueryElasticsearch

该 Processor 适用于 Elasticsearch JSON DSL 与 Elasticsearch 5.X 及以上 版本。它的设计目标是能够接收一个 JSON 查询(例如来自 Kibana),并 以分页方式原样对 Elasticsearch 集群执行。与 "restapi" bundle 中的所有 Processor 一样,它使用官方 Elastic 客户端 API,因此支持 leader 检测。

要执行的查询 JSON 可以在 Query 配置属性中提供,也可以通过 FlowFile 内容提供。如果配置了 Query Attribute 属性,已执行的 查询 JSON 会被放入该属性指定的 Attribute 中。

查询通过可用的方法之一在 Elasticsearch 中分页——"Scroll" 或 "Search After"(对于启用 XPack 的 Elasticsearch 7.10+,可以可选地 配合 "Point in Time")。每页结果数量可以通过查询 JSON 中的 size 参数控制。对于 Search After 功能,查询 JSON 中必须 包含 sort 参数。

搜索结果和聚合结果可以拆分为多个 FlowFile。聚合结果只在顶层 拆分,因为嵌套聚合如果与父聚合分离,就会失去上下文(从而失去 其价值)。此外,所有页的结果可以合并为单个 FlowFile(但 Processor 在任何时刻都只把当前页的数据加载到内存)。

以下是可接受的查询示例:

{
  "query": {
    "size": 10000,
    "sort": {
      "product": "desc"
    },
    "match": {
      "restaurant.keyword": "Local Pizzaz FTW Inc"
    }
  },
  "aggs": {
    "weekly_sales": {
      "date_histogram": {
        "field": "date",
        "interval": "week"
      },
      "aggs": {
        "items": {
          "terms": {
            "field": "product",
            "size": 10
          }
        }
      }
    }
  }
}