ExecuteSQL 2025.5.31.15¶

捆绑包¶

org.apache.nifi | nifi-standard-nar

描述¶

执行提供的 SQL select 查询。查询结果将转换为 Avro 格式。采用流式处理方式，因此支持任意大的结果集。可以使用标准调度方法将该处理器调度为在计时器或 cron 表达式上运行，也可以由传入的 FlowFile 触发。如果它是由传入的 FlowFile 触发的，则在评估 select 查询时，该 FlowFile 的属性将可用，并且该查询可以使用“?”转义参数。在这种情况下，要使用的参数必须作为命名约定 sql.args.N.type 和 sql.args.N.value 的 FlowFile 属性存在，其中 N 为正整数。sql.args.N.type 应为表示 JDBC 类型的数字。FlowFile 的内容预计采用 UTF-8 格式。FlowFile 属性“executesql.row.count”表示选择的行数。

标签¶

database、jdbc、query、select、sql

输入要求¶

ALLOWED

支持敏感的动态属性¶

true

属性¶

属性	描述
Content Output Strategy	指定处理输入 FlowFiles 时写入 FlowFile 内容的策略。该策略适用于处理未产生结果的查询。
数据库连接池服务	用于获取数据库连接的控制器服务
最大等待时间	允许正在运行的 SQL select 查询运行的最长时间量，零表示没有限制。如果最长时间小于 1 秒，则视同为零。
SQL 查询	要执行的 SQL 查询。查询可以为空，也可以是常量值，也可以使用表达式语言根据属性构建。如果指定了此属性，则无论传入的 FlowFile 的内容如何，都将使用该属性。如果此属性为空，则传入的 FlowFile 的内容应包含有效的 SQL select 查询，该查询将由处理器向数据库发出。请注意，不针对 FlowFile 内容评估表达式语言。
compression-format	写入 Avro 文件时使用的压缩类型。默认为“None”。
dbf-default-precision	当 DECIMAL/NUMBER 值作为 Avro 的“decimal”逻辑类型写入时，需要指定一个表示可用数字位数的特定“precision”。通常，精度由列数据类型定义或数据库引擎默认值定义。但是，某些数据库引擎可以返回未定义的精度（即 0）。这时将使用“默认小数精度”来写入这些未定义精度的数值。
dbf-default-scale	当 DECIMAL/NUMBER 值作为 Avro 的“decimal”逻辑类型写入时，需要指定一个表示可用小数位数的特定“scale”。通常，标度由列数据类型定义或数据库引擎默认值定义。但是，当数据库返回未定义的精度（即 0）时，某些数据库引擎也可能无法确定标度。这时将使用“默认小数标度”来写入这些未定义标度的数值。如果一个值的小数位数多于指定的标度，则该值将被舍入，例如，标度为 0 时，1.53 变成 2；标度为 1 时，1.53 会变为 1.5。
dbf-normalize	是否将列名中不兼容 Avro 的字符更改为与兼容 Avro 的字符。例如，为了建立有效的 Avro 记录，冒号和句点将更改为下划线。
dbf-user-logical-types	是否对 DECIMAL/NUMBER、DATE、TIME 和 TIMESTAMP 列使用 Avro 逻辑类型。如果禁用，则以字符串形式写入。如果启用，则使用逻辑类型并以其基础类型写入，具体而言，DECIMAL/NUMBER 写入为逻辑“decimal”：以字节形式写入，并包含额外的精度与标度元数据；DATE 写入为逻辑“date-millis”：以整数形式写入，表示自 Unix 纪元以来的天数 (1970-01-01)，TIME 写入为逻辑“time-millis”：以整数形式写入，表示自 Unix 纪元以来的毫秒数，TIMESTAMP 写入为逻辑“timestamp-millis”：以长整型写入，表示自 Unix 纪元以来的毫秒数。如果书面 Avro 记录的读取器也知道这些逻辑类型，则可以根据读取器的实现在更多上下文中对这些值进行反序列化。
esql-auto-commit	启用或禁用 DB 连接的自动提交功能。默认值为“true”。默认值可用于大多数 JDBC 驱动程序，并且此功能在大多数情况下不会产生任何影响，因为该处理器用于读取数据。但是，对于某些 JDBC 驱动程序（例如 PostgreSQL 驱动程序），需要禁用自动提交功能以限制一次提取的结果行数。启用自动提交后，postgreSQL 驱动程序会立即将整个结果集加载到内存中。在执行提取大型数据集的查询时，这可能会导致大量内存消耗。有关 PostgreSQL 驱动程序中这种行为的更多详细信息，请参阅 https://jdbc.postgresql.org//documentation/head/query.html (https://jdbc.postgresql.org//documentation/head/query.html)。
esql-fetch-size	一次要从结果集中提取的结果行数。这是数据库驱动程序的提示，不一定会被严格遵循和/或完全一致。如果指定的值为零，则忽略该提示。
esql-max-rows	单个 FlowFile 中将包含的最大结果行数。这将允许您将非常大的结果集分成多个 FlowFiles。如果指定的值为零，则所有行都以单个 FlowFile 形式返回。
esql-output-batch-size	提交过程会话之前需要缓存的输出 FlowFiles 队列数量。当设置为零时，将在处理完所有结果集行并且输出 FlowFiles 准备好传输到下游关系时提交会话。对于大型结果集，这可能导致处理器执行结束时出现 FlowFiles 数据的突发性集中传输。如果设置了此属性，则当指定数量的 FlowFiles 准备好传输时，将提交会话，从而将 FlowFiles 释放到下游关系。NOTE：设置此属性后，FlowFiles 不会启用 fragment.count 属性。
sql-post-query	执行主 SQL 查询后执行的查询列表，以分号分隔。例如，在主查询之后设置会话属性。通过使用反斜杠（“;”）进行转义，可以在语句中包含分号。如果没有错误，将自动抑制这些查询的结果/输出。
sql-pre-query	执行主 SQL 查询前执行的查询列表，以分号分隔。例如，在主查询之前设置会话属性。通过使用反斜杠（“;”）进行转义，可以在语句中包含分号。如果没有错误，将自动抑制这些查询的结果/输出。

关系¶

名称	描述
failure	SQL 查询执行失败。传入的 FlowFile 将被惩罚并路由到此关系
success	成功从 SQL 查询结果集创建了 FlowFile。

写入属性¶

名称	描述
executesql.row.count	包含查询返回的行数。如果设置了“Max Rows Per Flow File”，则此数字将反映 FlowFile 中的行数，而不是整个结果集的行数。
executesql.query.duration	查询执行时间和提取时间的总持续时间（以毫秒为单位）。如果设置了“Max Rows Per Flow File”，则此数字将仅反映 FlowFile 中的行提取时间，而不是整个结果集的提取时间。
executesql.query.executiontime	查询执行时间的持续时间（以毫秒为单位）。不管“Max Rows Per Flow File”设置如何，此数字都将反映查询的执行时间。
executesql.query.fetchtime	结果集提取时间的持续时间（以毫秒为单位）。如果设置了“Max Rows Per Flow File”，则此数字将仅反映 FlowFile 中的行提取时间，而不是整个结果集的提取时间。
executesql.resultset.index	假设返回了多个结果集，则该结果集的索引从零开始。
executesql.error.message	如果处理传入的 FlowFile 会导致异常，则 FlowFile 将路由到“failure”，并将此属性设置为异常消息。
fragment.identifier	如果设置了“Max Rows Per Flow File”，则来自同一查询结果集的所有 FlowFiles 的 fragment.identifier 属性的值都将相同。随后可以使用它来关联结果。
fragment.count	如果设置了“Max Rows Per Flow File”，则这是单个 ResultSet 生成的 FlowFiles 总数。这可以与 fragment.identifier 属性结合使用，以了解有多少个 FlowFiles 属于同一个传入 ResultSet。如果设置了“Output Batch Size”，则不会填充此属性。
fragment.index	如果设置了“Max Rows Per Flow File”，则此 FlowFile 在传出 FlowFiles 列表中的位置取决于它们是否源自同一结果集 FlowFile。这可以与 fragment.identifier 属性结合使用，以了解哪些 FlowFiles 源自同一查询结果集，以及 FlowFiles 的生成顺序
input.flowfile.uuid	如果处理器有传入连接，则传出 FlowFiles 会将此属性设置为输入 FlowFile 的 UUID 值。如果没有传入连接，则不会添加该属性。