ExecuteSQL 2025.10.2.19¶

捆绑包¶

org.apache.nifi | nifi-standard-nar

描述¶

Executes provided SQL select query. Query result will be converted to Avro format. Streaming is used so arbitrarily large result sets are supported. This processor can be scheduled to run on a timer, or cron expression, using the standard scheduling methods, or it can be triggered by an incoming FlowFile. If it is triggered by an incoming FlowFile, then attributes of that FlowFile will be available when evaluating the select query, and the query may use the ? to escape parameters. In this case, the parameters to use must exist as FlowFile attributes with the naming convention sql.args. N.type and sql.args. N.value, where N is a positive integer. The sql.args. N.type is expected to be a number indicating the JDBC Type. The content of the FlowFile is expected to be in UTF-8 format. FlowFile attribute 'executesql.row.count' indicates how many rows were selected.

标签¶

database、jdbc、query、select、sql

输入要求¶

ALLOWED

支持敏感的动态属性¶

true

属性¶

属性	描述
Content Output Strategy	Specifies the strategy for writing FlowFile content when processing input FlowFiles. The strategy applies when handling queries that do not produce results.
数据库连接池服务	用于获取数据库连接的控制器服务
最大等待时间	The maximum amount of time allowed for a running SQL select query , zero means there is no limit. Max time less than 1 second will be equal to zero.
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	A semicolon-delimited list of queries executed after the main SQL query is executed. Example like setting session properties after main query. It 's possible to include semicolons in the statements themselves by escaping them with a backslash (';'). Results/outputs from these queries will be suppressed if there are no errors.
sql-pre-query	A semicolon-delimited list of queries executed before the main SQL query is executed. For example, set session properties before main query. It 's possible to include semicolons in the statements themselves by escaping them with a backslash (';'). Results/outputs from these queries will be suppressed if there are no errors.

关系¶

名称	描述
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 值。如果没有传入连接，则不会添加该属性。